## Creating a session ### Seed the session with initial events ### Override agent configuration for a session #### Pin the inference geo for a session ### Set a session budget ## MCP authentication through vaults ## Starting the session ## Next steps
The whole hunk
1081 lines, first recorded
/
lines
The first capture of this source. The page was already there, and this is what it said.
---
title: Start a session
url: https://platform.claude.com/docs/en/managed-agents/sessions
description: Create a session to run your agent and begin executing tasks.
---
A session is an agent instance within an environment. Each session references an [agent](https://platform.claude.com/docs/en/managed-agents/agent-setup) and an [environment](https://platform.claude.com/docs/en/managed-agents/environments) (both created separately), and maintains conversation history across multiple interactions. Sessions follow a two-step lifecycle: first [create the session](https://platform.claude.com/docs/en/managed-agents/sessions#creating-a-session), then [send a user event](https://platform.claude.com/docs/en/managed-agents/sessions#starting-the-session) to start work. You can also collapse both steps into one call with [`initial_events`](https://platform.claude.com/docs/en/managed-agents/sessions#seed-the-session-with-initial-events).
<Note>
Managed Agents API requests require the `managed-agents-2026-04-01` beta header, except memory store endpoints, which use `agent-memory-2026-07-22` instead. The SDK sets the correct beta header automatically. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers#endpoint-specific-headers).
</Note>
## Creating a session
A 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.
<CodeGroup defaultLanguage="CLI">
```bash cURL
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")
```
```bash CLI
ant beta:sessions create \
--agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID"
```
```python Python
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
)
```
```typescript TypeScript
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id
});
```
```csharp C#
var session = await client.Beta.Sessions.Create(new()
{
Agent = agent.ID,
EnvironmentID = environment.ID,
});
```
```go Go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfString: anthropic.String(agent.ID),
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
```
```java Java
var session = client.beta().sessions().create(SessionCreateParams.builder()
.agent(agent.id())
.environmentId(environment.id())
.build());
```
```php PHP
$session = $client->beta->sessions->create(
agent: $agent->id,
environmentID: $environment->id,
);
```
```ruby Ruby
session = client.beta.sessions.create(
agent: agent.id,
environment_id: environment.id
)
```
</CodeGroup>
To 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.
<CodeGroup defaultLanguage="CLI">
```bash cURL
pinned_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
"environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
```
```bash CLI
ant beta:sessions create <<YAML
agent:
type: agent
id: $AGENT_ID
version: 1
environment_id: $ENVIRONMENT_ID
YAML
```
```python Python
pinned_session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": 1},
environment_id=environment.id,
)
```
```typescript TypeScript
const pinnedSession = await client.beta.sessions.create({
agent: { type: "agent", id: agent.id, version: 1 },
environment_id: environment.id
});
```
```csharp C#
var pinnedSession = await client.Beta.Sessions.Create(new()
{
Agent = new BetaManagedAgentsAgentParams
{
Type = BetaManagedAgentsAgentParamsType.Agent,
ID = agent.ID,
Version = 1,
},
EnvironmentID = environment.ID,
});
```
```go Go
pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
Agent: anthropic.BetaSessionNewParamsAgentUnion{
OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent,
ID: agent.ID,
Version: anthropic.Int(1),
},
},
EnvironmentID: environment.ID,
})
if err != nil {
panic(err)
}
```
```java Java
var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
.agent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(agent.id())
.version(1)
.build())
.environmentId(environment.id())
.build());
```
```php PHP
$pinnedSession = $client->beta->sessions->create(
agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
environmentID: $environment->id,
);
```
```ruby Ruby
pinned_session = client.beta.sessions.create(
agent: {type: :agent, id: agent.id, version: 1},
environment_id: environment.id
)
```
</CodeGroup>
### Seed the session with initial events
You can create a session and start its work in one call. `initial_events` is an optional array of initial [events](https://platform.claude.com/docs/en/managed-agents/reference#event-types) to send to the session at creation, processed in order. It supports `user.message` and [`user.define_outcome`](https://platform.claude.com/docs/en/managed-agents/define-outcomes) events, and accepts a maximum of 50 events. A non-empty list starts the agent loop in the same call: the session is created directly in the `running` status, with no further request.
The following example creates a session with a single `user.message` in `initial_events`:
<CodeGroup defaultLanguage="CLI">
```bash cURL
seeded_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"initial_events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "List the files in the working directory."}]
}
]
}
EOF
)
SEEDED_SESSION_ID=$(jq -r '.id' <<< "$seeded_session")
# initial_events aren't echoed on the create response; list the session's
# events to see the seeded message.
seeded_events=$(curl -fsSL \
"https://api.anthropic.com/v1/sessions/$SEEDED_SESSION_ID/events" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01")
echo "Seeded event: $(jq -r \
'.data[] | select(.type == "user.message") | .content[0].text' <<< "$seeded_events")"
```
```bash CLI
SEEDED_SESSION_ID=$(ant beta:sessions create \
--transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
- type: user.message
content:
- type: text
text: List the files in the working directory.
YAML
)
# initial_events aren't echoed on the create response; list the session's
# events to see the seeded message.
echo "Seeded event: $(ant beta:sessions:events list \
--session-id "$SEEDED_SESSION_ID" \
--format raw \
--transform 'data.#(type=="user.message").content.0.text' --raw-output)"
```
```python Python
seeded_session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
initial_events=[
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
],
},
],
)
# initial_events are not echoed on the create response; read them back
# from the session's event list.
for event in client.beta.sessions.events.list(seeded_session.id):
if event.type == "user.message":
for block in event.content:
if block.type == "text":
print(f"Seeded event: {block.text}")
```
```typescript TypeScript
const seededSession = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id,
initial_events: [
{
type: "user.message",
content: [{ type: "text", text: "List the files in the working directory." }]
}
]
});
// initial_events are not echoed on the create response; list the session's
// events to read the seeded message back.
for await (const event of client.beta.sessions.events.list(seededSession.id)) {
if (event.type === "user.message") {
for (const block of event.content) {
if (block.type === "text") {
console.log(`Seeded event: ${block.text}`);
}
}
}
}
```
Cut at 300 lines. The page has the rest.