1# Managed Agents — Scheduled Deployments
2 
3A **scheduled deployment** runs an agent on a recurring cron schedule — each firing creates a session autonomously. Use it for predictable-cadence work: nightly triage, weekly compliance scans, hourly monitors.
4 
5Requires the `managed-agents-2026-04-01` beta header (the SDK sets it automatically for `client.beta.deployments.*` / `client.beta.deployment_runs.*` calls).
6 
7## Create a deployment
8 
9A 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:
10 
11- `agent` and `environment_id` are required — same shapes as `sessions.create` (see `shared/managed-agents-core.md`).
12- `initial_events` must contain the starting `user.message`.
13- `schedule` takes a cron `expression` and an IANA `timezone`. Minute-level granularity is the maximum.
14 
15```bash
16curl -fsSL https://api.anthropic.com/v1/deployments \
17  -H "x-api-key: $ANTHROPIC_API_KEY" \
18  -H "anthropic-version: 2023-06-01" \
19  -H "anthropic-beta: managed-agents-2026-04-01" \
20  -H "content-type: application/json" \
21  -d @- <<EOF
22{
23  "name": "Weekly compliance scan",
24  "agent": "$AGENT_ID",
25  "environment_id": "$ENVIRONMENT_ID",
26  "initial_events": [
27    {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
28  ],
29  "schedule": {
30    "type": "cron",
31    "expression": "0 20 * * 5",
32    "timezone": "America/New_York"
33  }
34}
35EOF
36```
37 
38```python
39deployment = client.beta.deployments.create(
40    name="Weekly compliance scan",
41    agent=agent.id,
42    environment_id=environment.id,
43    initial_events=[
44        {
45            "type": "user.message",
46            "content": [{"type": "text", "text": "Run the weekly compliance scan."}],
47        },
48    ],
49    schedule={
50        "type": "cron",
51        "expression": "0 20 * * 5",
52        "timezone": "America/New_York",
53    },
54)
55```
56 
57The 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:
58 
59```json
60{
61  "id": "depl_01xyz",
62  "status": "active",
63  "paused_reason": null,
64  "schedule": {
65    "type": "cron",
66    "expression": "0 20 * * 5",
67    "timezone": "America/New_York",
68    "last_run_at": null,
69    "upcoming_runs_at": ["2026-05-09T00:00:00Z", "2026-05-16T00:00:00Z", "2026-05-23T00:00:00Z"]
70  }
71}
72```
73 
74Deployments may apply up to **10 seconds of jitter** to distribute load. Maximum **1000 scheduled deployments per organization** (contact Anthropic support for more).
75 
76### Cron and timezone semantics
77 
78- **Expression:** standard POSIX cron (`minute hour day-of-month month day-of-week`).
79- **Timezone:** IANA identifier (e.g. `"America/Los_Angeles"`).
80- **DST:** literal wall-clock matching — `"0 20 * * *"` in `America/New_York` fires at 8:00 PM local regardless of EST/EDT.
81 
82> ⚠️ **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.
83 
84## Deployment runs
85 
86Every 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.
87 
88```python
89# All runs for a deployment
90for run in client.beta.deployment_runs.list(deployment_id=deployment.id):
91    print(run.created_at, run.session_id or run.error.type)
92 
93# Failures only
94for run in client.beta.deployment_runs.list(deployment_id=deployment.id, has_error=True):
95    print(run.created_at, run.error.type, run.error.message)
96```
97 
98```typescript
99for await (const run of client.beta.deploymentRuns.list({
100  deployment_id: deployment.id,
101  has_error: true,
102})) {
103  console.log(run.created_at, run.error?.type, run.error?.message);
104}
105```
106 
107Raw HTTP: `GET /v1/deployment_runs?deployment_id=...&has_error=true`.
108 
109A failed run looks like:
110 
111```json
112{
113  "type": "deployment_run",
114  "id": "drun_01abc124",
115  "deployment_id": "depl_01xyz",
116  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
117  "session_id": null,
118  "error": { "type": "environment_archived", "message": "environment `env_01abc` is archived" },
119  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
120  "created_at": "2026-05-09T00:00:01Z"
121}
122```
123 
124Error types include `environment_archived`, `agent_archived`, `vault_not_found`, `session_rate_limited`, and `service_unavailable`.
125 
126## Lifecycle: pause / unpause / archive
127 
128| Operation | SDK | Effect |
129|---|---|---|
130| Pause | `client.beta.deployments.pause(id)` | Suppresses scheduled triggers go-forward. Sessions already running continue. **Manual runs are still permitted while paused.** Sets `paused_reason: {"type": "manual"}`. |
131| Unpause | `client.beta.deployments.unpause(id)` | Resumes from the next scheduled occurrence. **Missed triggers are not backfilled.** Clears `paused_reason`. |
132| Archive | `client.beta.deployments.archive(id)` | **Terminal** — the schedule stops and the deployment can no longer be modified. Use pause for anything reversible. |
133 
134Raw HTTP: `POST /v1/deployments/{deployment_id}/pause` (likewise `/unpause`, `/archive`).
135 
136### Failure behavior
137 
138- **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.)
139- **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.
140- **Agent archived or deleted:** the deployment is automatically **archived** (terminal) and no further sessions are created.
141 
142## Manual runs
143 
144`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.
145