Follow Discord
Sweep 10 Nov 2026 · 02:18Z Build v2.1.322 539 read Stable v2.1.311 Latest v2.1.322 Next v2.1.322 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Developer Platform 18 Sep 2026
One change · api

sessions changedmanaged-agents/sessions

Nearest release: v2.1.277, published 4 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+12added
Lines−23removed
From line 14 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits25to this page, all time

The whole hunk

from line 14, old and new numbered
/
lines
from line 14
1414 
1515A session requires an `agent` ID and an `environment` ID. Agents are versioned resources; passing in the `agent` ID as a string creates the session with the latest agent version.
1616 
17<CodeGroup defaultLanguage="CLI">
17<CodeGroup>
1818 ```bash cURL
19 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
19 curl -fsSL https://api.anthropic.com/v1/sessions \
2020 -H "x-api-key: $ANTHROPIC_API_KEY" \
2121 -H "anthropic-version: 2023-06-01" \
2222 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 27
2727 "environment_id": "$ENVIRONMENT_ID"
2828 }
2929 EOF
30 )
31 SESSION_ID=$(jq -r '.id' <<< "$session")
3230 ```
3331 
3432 ```bash CLI
from line 93
9593 
9694To pin a session to a specific agent version, pass an object. This lets you control exactly which version runs and stage rollouts of new versions independently.
9795 
98<CodeGroup defaultLanguage="CLI">
96<CodeGroup>
9997 ```bash cURL
100 pinned_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
98 curl -fsSL https://api.anthropic.com/v1/sessions \
10199 -H "x-api-key: $ANTHROPIC_API_KEY" \
102100 -H "anthropic-version: 2023-06-01" \
103101 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 106
108106 "environment_id": "$ENVIRONMENT_ID"
109107 }
110108 EOF
111 )
112 PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
113109 ```
114110 
115111 ```bash CLI
from line 193
197193 
198194The following example creates a session with a single `user.message` in `initial_events`:
199195 
200<CodeGroup defaultLanguage="CLI">
196<CodeGroup>
201197 ```bash cURL
202198 seeded_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
203199 -H "x-api-key: $ANTHROPIC_API_KEY" \
from line 477
481477 
482478The following example starts a session that overrides the model and clears the system prompt:
483479 
484<CodeGroup defaultLanguage="CLI">
480<CodeGroup>
485481 ```bash cURL
486 override_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
482 curl -fsSL https://api.anthropic.com/v1/sessions \
487483 -H "x-api-key: $ANTHROPIC_API_KEY" \
488484 -H "anthropic-version: 2023-06-01" \
489485 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 495
499495 "environment_id": "$ENVIRONMENT_ID"
500496 }
501497 EOF
502 )
503 jq '.agent | {id, version, model, system}' <<< "$override_session"
504 OVERRIDE_SESSION_ID=$(jq -r '.id' <<< "$override_session")
505498 ```
506499 
507500 ```bash CLI
508501 # The response's `agent` is the resolved snapshot: each override replaces that
509502 # field for this session only, and the agent resource keeps its id and version.
510 ant beta:sessions create \
511 --transform 'agent.{id,version,model,system}' \
512 --format json <<YAML
503 ant beta:sessions create <<YAML
513504 agent:
514505 type: agent_with_overrides
515506 id: $AGENT_ID
from line 644
653644 
654645The following example starts a session from an agent whose model has no geo pin, pins the session's model requests to US inference by including `inference_geo` in the `model` override, and prints the value echoed in the response's `agent.model`:
655646 
656<CodeGroup defaultLanguage="CLI">
647<CodeGroup>
657648 ```bash cURL
658649 # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
659650 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
from line 827
836827 
837828If your agent uses MCP tools that require authentication, pass `vault_ids` at session creation to reference a vault containing stored OAuth credentials. Anthropic manages token refresh on your behalf. See [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults) for how to create vaults and register credentials.
838829 
839<CodeGroup defaultLanguage="CLI">
830<CodeGroup>
840831 ```bash cURL
841 vault_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
832 curl -fsSL https://api.anthropic.com/v1/sessions \
842833 -H "x-api-key: $ANTHROPIC_API_KEY" \
843834 -H "anthropic-version: 2023-06-01" \
844835 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 841
850841 "vault_ids": ["$VAULT_ID"]
851842 }
852843 EOF
853 )
854 VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")
855844 ```
856845 
857846 ```bash CLI
from line 919
930919 
931920Creating a session without `initial_events` registers the session but does not start any work; the environment's sandbox begins provisioning as soon as the session is created, so the first tool call does not wait on it. To delegate a task, send events to the session using a [user event](https://platform.claude.com/docs/en/managed-agents/reference#event-types). To supply the first event in the create request instead, see [Seed the session with initial events](https://platform.claude.com/docs/en/managed-agents/sessions#seed-the-session-with-initial-events). The session acts as a state machine that tracks progress while events drive the actual execution.
932921 
933<CodeGroup defaultLanguage="CLI">
922<CodeGroup>
934923 ```bash cURL
935924 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
936925 -H "x-api-key: $ANTHROPIC_API_KEY" \
Feedback