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" \