Scheduled Agents: When to Start a Fresh API Session

Scheduling an agent requires an explicit decision about conversation state. Scripts can preserve state too, but an agent platform also has to decide which session receives each scheduled turn. An agent session holds a conversation, tool results and work in progress, so a schedule has to decide whether each run inherits that state or begins without it. OpenAI's Agents API documents that choice. Its scheduled automations guide, as it stood on October 26, 2026, describes saved schedules that either start a new session or deliver a task into one that already exists.

We are not treating this as launch news. The feature does not appear in the API changelog we read the same day, and the guide carries only a page timestamp, so we do not know when it shipped and say so. What we can do is read the documentation closely, because it answers a design question that applies to any scheduled agent on any platform: where should the state boundary sit?

This post assumes the Agents API basics, which our managed-runtime guide covers: an agent is a configuration of model, instructions and tools; a session is a durable instance of it; and an environment is the optional sandbox it works in. Everything below is about what happens when a clock, rather than a person, starts the next turn.

The guide defines an automation as a saved schedule for agent work. The Agents API stores it and, when the time comes, sends a task to the target session. Three resources are involved. The automation itself holds when to run and which session to use. An invocation records each attempt to send the task. The session does the work, and its events are where progress and results appear. All of it sits behind the Agents API beta header, and the openai-node repository's API listing shows the client methods: create, retrieve, update, list, delete, pause and resume on automations, plus create, retrieve and list on invocations.

Two schedule types exist. A periodic automation takes a five-field cron expression and a time zone, either UTC or an IANA name such as America/New_York. A one-time automation takes a Unix timestamp in seconds that must be in the future. The guide is explicit that the fields are exclusive: no timestamp on a periodic schedule, no expression or zone on a one-time one. Creating either saves it with an active status and does not run it; a periodic schedule's first run is the next matching time.

Two target types exist, and they are the subject of this post. A new-session target carries an agent, either a saved agent ID or an inline configuration but not both, an environment such as an OpenAI-hosted sandbox, and at least one initial message with text or an image. An existing-session target carries a session ID and reminder text, which the guide calls instructions and which the run delivers as an automation notification, distinct from a user message. Each run against a new-session target starts a fresh conversation; each run against an existing one lands in the same conversation, using the session's current agent configuration and saved state.

The guide's rule is short: use a new session for independent work, such as a monthly spending review, and an existing session for follow-up work that needs the session's previous findings. The examples behind it are a daily suggestions agent that starts fresh each morning with access to the user's calendar and tasks, and a dinner-planning session that keeps restaurant preferences and earlier availability checks while a two-hourly schedule asks it to check reservations again.

A fresh session resets the conversation history, which makes one source of state easier to inspect. It does not isolate shared files or external systems from earlier writes, and it does not make outputs deterministic. Reconstructing a run also requires its effective agent configuration, environment, tool activity and the data those tools returned. The cost is that the agent re-derives context every time, which for a review over a data source it can re-read is fine, and for a task that depends on what it found yesterday is not.

The failure case for continuing is the one the guide's multi-agent advice is designed to prevent. A session that receives a reservation check every two hours accumulates every tool result from every check. Repeated checks can accumulate stale availability tables unless the runtime compacts history or the application summarises it deliberately. The guide's answer is to enable multi-agent orchestration and instruct the main agent to delegate each scheduled task to a subagent, keep only a concise summary, and decide whether to continue, change or stop the schedule. The main session keeps the goal; the subagents absorb the noise. It is the same problem we described for cloud agents that outlive the session, now with a clock attached.

Three timing details in the guide will catch people who think of a schedule as a timer. First, the expression is interpreted as clock times in the chosen zone: the guide's example is that an every-three-hours expression fires at midnight, three, six and so on, not at three-hour intervals from creation. Second, the Agents API adds a small randomised delay to recurring runs to spread load, so a nine o'clock schedule is a schedule for roughly nine o'clock. Third, if the target session is busy when the run is due, delivery waits until it is free, and the guide says the wait can be longer than the delay.

The onboarding example in the guide shows the right response to the first of these. An application that wants to follow up a new user 48 hours after sign-up, then 48 hours after that, should not reach for a cron expression, because a day-of-month expression cannot express a 48-hour interval across month boundaries. Instead it creates a one-time schedule for 48 hours ahead, and after each completed follow-up creates the next one, stopping and deleting any pending schedule when onboarding ends or the user opts out.

A failure case from the time-zone field: a schedule written as nine in the morning in UTC for a team in New York runs at four or five in the morning local time depending on the season, because UTC does not observe daylight saving. Use the IANA zone the humans live in. What the guide does not say is how a cron expression behaves at the moment the clocks change in that zone, which section 07 lists among the open questions.

Every run, scheduled or manual, creates an invocation. The guide lists the fields to inspect: a status that starts as queued and becomes completed when delivery succeeds; a session ID that can be null before a session is available; a source type of manual or automation; and the intended scheduled time, null for a manual run. Then it states the sentence this whole section hangs on: a completed delivery does not mean the agent has completed its work. For a new session it means the session accepted its initial input. For an existing session it means the session accepted the notification and the request to start work.

Why this matters operationally: an invocation list is an audit trail of attempts, not of outcomes. If a scheduled run is supposed to send a customer a message, the invocation shows that a session was asked to do so at a certain time. Whether the message went, what it said, and whether a tool call failed on the way are in the session's events and items, reached through the invocation's session ID. The guide is direct that the automation schedules the work and the application displays the output and sends any notifications to the user.

One useful consequence is the manual invocation. Sending an empty request to the invocations endpoint runs the automation now, without changing the saved schedule or consuming a one-time run, and it works while the schedule is paused. That makes a paused automation a testable one: pause it, invoke it by hand, read the session, then resume. The failure case is treating the invocation list as complete history; the guide notes it contains invocations already created, not every future occurrence.

Adding the automations tool to an agent's configuration lets it schedule work requested during a conversation: a user who says check again in two hours gets a one-time schedule the agent creates for itself. The guide lists what the tool can do, which is create, list, get, update, pause, resume and delete the agent's own automations, and the Agents API sets the target to the current session every time. The agent can create one-time or periodic runs.

The boundaries are as important as the capability. The agent cannot use the tool to start a new session, and it cannot manage another session's automations. The tool sees only automations created by the agent in the current session; the application can see those too, through the API, alongside any it created itself, and the creator is recorded in a field the application must not set on create. An agent-created automation must keep its creator session as the target even when updated. The tool is absent by default, and removing it later does not delete schedules already saved.

The failure case here is permission creep by schedule. An agent that can create periodic automations targeting its own session can, if instructed carelessly, keep itself running indefinitely after the user has stopped caring. The guide's framing is that the automations tool manages schedules while the other tools and data access do the work; the design corollary is that the application owns the stop. Pause or delete through the API when the goal is met, and remember that pausing does not stop work a session has already accepted.

The lifecycle operations are small but each has a documented edge. An update leaves omitted fields unchanged, except that a supplied target replaces the whole target, so every required field must be present and the type must be retained. Updates apply to future invocations only; an invocation already queued keeps the target and input it was saved with, so a change made after the scheduled time has passed will not affect the run that is waiting for a busy session.

Pause holds pending scheduled deliveries and leaves manual invocation available. Resume reactivates the saved schedule. Delete prevents future scheduled and manual invocations. None of the three stops work a session has already accepted or deletes the session; a delivery in progress may still arrive. To stop current work, the guide points to cancelling the session's active turn, which is a session operation rather than an automation one.

The one-time schedule has its own corner. If its time passes while it is paused, you must set a new future timestamp before resuming. Once it has run, it is complete: it cannot be paused or resumed, although it can still be invoked manually, and another follow-up needs a new automation. For the onboarding pattern, that means the application is creating a new automation after every completed step and tidying the previous one.

We read the guide, the reference navigation and the openai-node listing looking for six behaviours that any scheduler eventually has to define, and found none of them stated. Retries: the guide describes an invocation becoming completed when delivery succeeds but does not describe a failed delivery, a failure status or any retry. Overlap: it says a run waits for a busy session but not what happens if the next periodic occurrence arrives while the previous invocation is still queued. Catch-up: it does not say whether a periodic schedule that was paused through several occurrences runs once, runs them all or skips them on resume.

Limits and clock changes are also absent: no maximum number of automations per project or per session, no minimum interval, and no statement of how an expression behaves when the named zone moves its clocks. Billing is stated only at the Agents API level, which is that model usage is charged at the model's API rates, OpenAI tools at their standard rates and OpenAI-hosted sandboxes at container rates; the guide names no charge for the automation itself, and we do not infer one either way.

The honest design response is to assume nothing is handled. Make scheduled turns idempotent, so a repeated or late delivery does not duplicate an action. Record your own expected-run table and reconcile it against the invocation list, so a missing run is noticed. And pin the model in the saved agent rather than relying on a floating alias, which is the rule our model-pinning policy for production automations sets out, because a schedule that runs unattended for months may outlive the model version it was tested on; monitor its retirement policy as well.

Put together, the documentation supports a rule that is more precise than new-for-independent and existing-for-follow-up. Ask three questions of every scheduled task. Does the run need something only the previous run produced, rather than something it can re-read from a system of record? Will the run produce output that should stay in context for the next one, or output that should be summarised and discarded? And must the run happen at a time of day, or after an interval from an event?

The first question picks the target. If the answer is no, start a new session, and give the agent tools that reach the source of truth; the invocation then leads to the new session, whose events show what the run saw. The second question picks the structure within an existing session: if output accumulates, enable multi-agent orchestration and delegate, keeping summaries in the main session as the guide suggests. The third picks the schedule type: cron for clock times, one-time schedules chained by the application for intervals.

Our worked example, illustrative rather than run: a weekly content-performance review for a marketing team. The run needs last week's analytics, which live in a warehouse the agent can query, so it does not need the previous session and starts fresh. It should run at nine on Monday in the team's zone, so it is periodic with an IANA zone. Its output is a report the application stores and posts, so the application, not the session, is the record. The invocation list shows it was delivered; the stored report shows it was done; the two are reconciled by the application once a week. That reconciliation step is the part our automation practice builds first, because comparing expected runs with recorded outcomes can reveal a missed run.