sessions changedmanaged-agents/sessions
Nearest release: v2.1.312, published under an hour 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+14added
Lines−14removed
From line
404
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 404, old and new numbered
/
from line 404
404404 ```
405405</CodeGroup>
406406
407`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) are not echoed on the create response. To see the seeded message, list the session's events.
407`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) are not echoed on the create response. To see the seeded message, list the session’s events.
408408
409No other event type is accepted. Events that respond to an agent turn (`user.tool_confirmation`, `user.tool_result`, and `user.custom_tool_result`) aren't accepted because no agent turn exists yet, and `user.interrupt` isn't accepted because there is no turn to stop. Unlike `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) on a scheduled deployment, a session's `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) don't accept `system.message`.
409No other event type is accepted. Events that respond to an agent turn (`user.tool_confirmation`, `user.tool_result`, and `user.custom_tool_result`) aren’t accepted because no agent turn exists yet, and `user.interrupt` isn’t accepted because there is no turn to stop. Unlike `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) on a scheduled deployment, a session’s `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) don’t accept `system.message`.
410410
411411Each event in `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) is validated and persisted before the create response returns, in list order, with a server-assigned ID, exactly as if you had posted it to the [send events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#send-events) endpoint immediately after creation. Per-event content rules are also the same as on that endpoint. An empty list is equivalent to omitting the field. Validation is all-or-nothing: if any event fails validation, the whole request is rejected and no session is created.
412412
from line 423
423423
424424### Override agent configuration for a session
425425
426You can pass `agent` (csharp, go: `Agent`) in three forms: an agent ID string, a pinned-version object (`type: "agent"`), or an overrides object (`type: "agent_with_overrides"`). The overrides form changes parts of the agent's configuration for a single session. Use it to try a different model or grant an extra tool in one session without versioning the agent. For the overrides form, pass the agent's `id` (csharp, go: `ID`) and optionally a `version` (csharp, go: `Version`) (omit `version` (csharp, go: `Version`) to use the agent's latest version). Then include any of `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), or `skills` (csharp, go: `Skills`) with the values the session should use.
426You can pass `agent` (csharp, go: `Agent`) in three forms: an agent ID string, a pinned-version object (`type: "agent"`), or an overrides object (`type: "agent_with_overrides"`). The overrides form changes parts of the agent’s configuration for a single session. Use it to try a different model or grant an extra tool in one session without versioning the agent. For the overrides form, pass the agent’s `id` (csharp, go: `ID`) and optionally a `version` (csharp, go: `Version`) (omit `version` (csharp, go: `Version`) to use the agent’s latest version). Then include any of `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), or `skills` (csharp, go: `Skills`) with the values the session should use.
427427
428428Each overridable field follows the same three rules:
429429
from line 432
432432* **Set the field to `null`, or to an empty array for list fields:** The session runs with that field cleared. This rule applies in full to `system` (csharp, go: `System`; ruby: `system_`) and `skills` (csharp, go: `Skills`). There are three exceptions:
433433
434434 * `model` (csharp, go: `Model`) is never clearable. A session always needs a model, so setting `model` (csharp, go: `Model`) to `null` returns a 400 `agent_model_required` error.
435 * Clearing `tools` (csharp, go: `Tools`) returns a 400 error when the session's effective `skills` (csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, setting `tools` (csharp, go: `Tools`) to `null` or to an empty array clears the field.
436 * Clearing `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) returns a 400 error when the session's effective `tools` (csharp, go: `Tools`) still contains an `mcp_toolset` that references one of the agent's servers. Override `tools` (csharp, go: `Tools`) in the same request to remove those `mcp_toolset` entries, then clear `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).
435 * Clearing `tools` (csharp, go: `Tools`) returns a 400 error when the session’s effective `skills` (csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, setting `tools` (csharp, go: `Tools`) to `null` or to an empty array clears the field.
436 * Clearing `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) returns a 400 error when the session’s effective `tools` (csharp, go: `Tools`) still contains an `mcp_toolset` that references one of the agent’s servers. Override `tools` (csharp, go: `Tools`) in the same request to remove those `mcp_toolset` entries, then clear `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).
437437
438* **Set the field to a value:** The value replaces the agent's value in full. Overrides never merge with the agent's configuration, so a `tools` (csharp, go: `Tools`) override must list every tool the session should have. Likewise, a `model` (csharp, go: `Model`) override replaces the agent's `model` (csharp, go: `Model`) object in full, so the agent's own `effort` (csharp, go: `Effort`) isn't carried over. To run the session at a specific effort level, set `effort` (csharp, go: `Effort`) inside the override's `model` (csharp, go: `Model`) object. A level the model doesn't support returns a 400 error, and a `model` (csharp, go: `Model`) override without `effort` (csharp, go: `Effort`) runs at that model's default effort level.
438* **Set the field to a value:** The value replaces the agent’s value in full. Overrides never merge with the agent’s configuration, so a `tools` (csharp, go: `Tools`) override must list every tool the session should have. Likewise, a `model` (csharp, go: `Model`) override replaces the agent’s `model` (csharp, go: `Model`) object in full, so the agent’s own `effort` (csharp, go: `Effort`) isn’t carried over. To run the session at a specific effort level, set `effort` (csharp, go: `Effort`) inside the override’s `model` (csharp, go: `Model`) object. A level the model doesn’t support returns a 400 error, and a `model` (csharp, go: `Model`) override without `effort` (csharp, go: `Effort`) runs at that model’s default effort level.
439439
440440Overrides apply only to the session you create. They do not modify the agent resource or create a new agent version, so other sessions that reference the same agent are unaffected.
441441
from line 600
600600
601601#### Pin the inference geo for a session
602602
603Because a `model` (csharp, go: `Model`) override replaces the agent's `model` (csharp, go: `Model`) object in full, it also sets or clears the model's [inference geo](https://platform.claude.com/docs/en/manage-claude/data-residency) pin for the session. An override that includes `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) pins the geography that serves the session's model requests. An override that omits it clears the agent's pin, so the session follows the workspace's `default_inference_geo`. The overridden value is validated against the workspace's `allowed_inference_geos` when the session is created.
603Because a `model` (csharp, go: `Model`) override replaces the agent’s `model` (csharp, go: `Model`) object in full, it also sets or clears the model’s [inference geo](https://platform.claude.com/docs/en/manage-claude/data-residency) pin for the session. An override that includes `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) pins the geography that serves the session’s model requests. An override that omits it clears the agent’s pin, so the session follows the workspace’s `default_inference_geo`. The overridden value is validated against the workspace’s `allowed_inference_geos` when the session is created.
604604
605The following example starts a session from an agent whose model has no geo pin, and pins the session's model requests to US inference by including `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (csharp, go: `Model`) override. The response echoes the value in `agent.model` (csharp, go: `Agent.Model`):
605The following example starts a session from an agent whose model has no geo pin, and pins the session’s model requests to US inference by including `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (csharp, go: `Model`) override. The response echoes the value in `agent.model` (csharp, go: `Agent.Model`):
606606
607607<CodeGroup>
608608 ```bash cURL
from line 749
749749
750750### Set a session budget
751751
752To cap what a session can spend, pass the optional `budget` (csharp, go: `Budget`) object when you create it. A budget is a hard ceiling on the session's list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). The budget's `type` (csharp, go: `Type`) is always `limit`. Give `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) an `amount` (csharp, go: `Amount`) and a `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) is a whole number of US cents written as a string, such as `"125"` for $1.25 USD. The API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it completes first and the session's final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove the budget](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) later, but you can't add one to a session created without it.
752To cap what a session can spend, pass the optional `budget` (csharp, go: `Budget`) object when you create it. A budget is a hard ceiling on the session’s list cost: the platform prices everything the session consumes at public list rates, and the session stops issuing new model requests once that running total reaches `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). The budget’s `type` (csharp, go: `Type`) is always `limit`. Give `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) an `amount` (csharp, go: `Amount`) and a `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) is a whole number of US cents written as a string, such as `"125"` for $1.25 USD. The API takes a string rather than a number so no floating-point rounding is ever applied. `USD` is the only currency currently supported. When the session reaches the cap, it pauses and goes idle with the stop reason `budget_reached`. The cap is enforced between model requests, so the request that crosses it completes first and the session’s final list cost can land [a fraction past the cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A budget can only be attached at creation: you can [change or remove the budget](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) later, but you can’t add one to a session created without it.
753753
754754The following example creates a session with a $1.25 USD budget:
755755
from line 967
967967
968968## Starting the session
969969
970Creating a session without `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) registers the session but does not start any work; the environment's sandbox starts 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, and events drive the actual execution.
970Creating a session without `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) registers the session but does not start any work; the environment’s sandbox starts 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, and events drive the actual execution.
971971
972972<CodeGroup>
973973 ```bash cURL
from line 1091
10911091 ```
10921092</CodeGroup>
10931093
1094See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) for how to stream the agent's responses and handle tool confirmations.
1094See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) for how to stream the agent’s responses and handle tool confirmations.
10951095
10961096See [Session statuses](https://platform.claude.com/docs/en/managed-agents/session-operations#session-statuses) for the statuses a session moves through.
10971097
No line in this hunk matches that.