Managed Agents Scheduled Deployments

A deployment bundles everything a session needs (agent, environment, optional files / GitHub / memory stores / vaults) plus a schedule and the initial_events that kick off each run:

• agent and environment_id are required — same shapes as sessions.create (see shared/managed-agents-core.md).
• initial_events must contain at least one starting event — a user.message or a user.define_outcome. (A deployment’s initial_events also accepts system.message, which a session’s does not.)
• schedule takes a cron expression and an IANA timezone. Minute-level granularity is the maximum.

The response is a deployment object (depl_ ID prefix). Check schedule.upcoming_runs_at — the next fire times — to confirm the schedule parses the way you intended:

upcoming_runs_at reflects the exact configured schedule, but execution is jittered to distribute load: up to 15% of the interval between runs, floored at 5 seconds and capped at 9 minutes. An hourly deployment can therefore fire up to 9 minutes late; don’t build a downstream deadline that assumes the listed timestamp. Maximum 1000 scheduled deployments per organization (contact Anthropic support for more).

Cron and timezone semantics

• Expression: standard POSIX cron (minute hour day-of-month month day-of-week).
• Timezone: IANA identifier (e.g. "America/Los_Angeles").
• DST: literal wall-clock matching — "0 20 * * *" in America/New_York fires at 8:00 PM local regardless of EST/EDT.

⚠️ DST edge: wall-clock times that don’t exist on a spring-forward day (e.g. 2AM) are skipped; times that occur twice on a fall-back day fire twice. Schedule outside the 1–3AM local window, or use UTC, when missed or duplicate executions are unacceptable.

Deployment budgets

A deployment accepts the same budget object as a session ({type: "limit", max_list_cost: {amount, currency}} — minor-unit cents string, USD only; see shared/managed-agents-core.md § Session budgets). The cap is copied onto each session at fire time, and that session then behaves exactly like any budgeted session.

Deployment budget update semantics differ from a session’s:

• budget is accepted on create and update — it is not create-only.
• budget: null on update clears it, and a cleared budget can be re-added later — there is no one-way door.
• A change applies from the next fired session — sessions already running keep the cap they were created with (change those via their own session update).

Deployment runs

Every trigger attempt — successful or not — writes a deployment run record (drun_ prefix), so you can audit failures independent of the session lifecycle. A successful run carries the created session_id; follow that session via the event stream (shared/managed-agents-events.md) or webhooks (shared/managed-agents-webhooks.md) as usual. A failed run carries an error whose type explains why session creation was rejected.

Raw HTTP: GET /v1/deployment_runs?deployment_id=...&has_error=true. To retrieve a single run by ID, GET /v1/deployment_runs/{deployment_run_id} (SDK: client.beta.deployment_runs.retrieve(run_id)) — a deployment_run.* webhook event carries the run ID as its data.id.

A failed run looks like:

Error types include environment_archived, agent_archived, vault_not_found, session_rate_limited, and service_unavailable.

The outcome of each scheduled run (started/succeeded/failed) and each deployment lifecycle change (created/updated/paused/unpaused/archived/deleted) is also delivered as a webhook event — see shared/managed-agents-webhooks.md for the deployment.* and deployment_run.* event types — so you can react without polling. Manual runs do not emit deployment_run.* webhook events.

Lifecycle: pause / unpause / archive

Raw HTTP: POST /v1/deployments/{deployment_id}/pause (likewise /unpause, /archive).

Failure behavior

• Rate-limited: recorded immediately as a session_rate_limited run, no retry — the schedule simply tries again at the next occurrence. (Rate limits on API calls inside a session are handled by the session itself.)
• Other failed runs (e.g. environment_archived, vault_not_found, service_unavailable): the run records the error.type — monitor runs and fix the referenced resource, or pause the deployment.
• Agent archived: the deployment is automatically archived (terminal) in the same operation. Agent deleted: the next scheduled trigger detects the missing agent and archives the deployment then. Either way no deployment run is recorded, and no further sessions are created.

Manual runs

POST /v1/deployments/{deployment_id}/run (SDK: client.beta.deployments.run(id)) creates a session immediately and writes a run with trigger_context.type: "manual". Use it to test a deployment before committing to the schedule — and remember it works even while the deployment is paused.