sessions changedmanaged-agents/sessions
Nearest release: v2.1.300, published 2 hours after 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−12removed
From line
14
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits18to this page, all time
The whole hunk
from line 14, old and new numbered
/
from line 14
1414
1515## Creating a session
1616
17A session requires an `agent` ID and an `environment` ID. Agents are versioned resources; passing in the `agent` (java, php; csharp, go: `Agent`) ID as a string creates the session with the latest agent version.
17A session requires an `agent` ID and an `environment` ID. Agents are versioned resources; passing in the `agent` (csharp, go: `Agent`) ID as a string creates the session with the latest agent version.
1818
1919<CodeGroup>
2020 ```bash cURL
from line 458
458458
459459### Override agent configuration for a session
460460
461You can pass `agent` (java, php; csharp, go: `Agent`) in three forms: an agent ID string, a pinned-version object (`type: "agent"`), or an overrides object. 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, set `type` to `agent_with_overrides` and pass the agent's `id` (java, php; csharp, go: `ID`) and optionally a `version` (java, php; csharp, go: `Version`) (omit `version` (java, php; csharp, go: `Version`) to use the agent's latest version). Then include any of `model` (java, php; csharp, go: `Model`), `system` (java, php; csharp, go: `System`; ruby: `system_`), `tools` (java, php; csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), or `skills` (java, php; csharp, go: `Skills`) with the values the session should use.
461You can pass `agent` (csharp, go: `Agent`) in three forms: an agent ID string, a pinned-version object (`type: "agent"`), or an overrides object. 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, set `type` to `agent_with_overrides` and 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.
462462
463463Each overridable field follows the same three rules:
464464
465465* **Omit the field:** The session inherits the value from the agent version it references.
466466
467* **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` (java, php; csharp, go: `System`; ruby: `system_`) and `skills` (java, php; csharp, go: `Skills`). There are three exceptions:
467* **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:
468468
469469 * `model` is never clearable. A session always needs a model, so `model: null` returns a 400 `agent_model_required` error.
470 * Clearing `tools` returns a 400 error when the session's effective `skills` (java, php; csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, `tools: null` and `tools: []` clear the field.
471 * Clearing `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) returns a 400 error when the session's effective `tools` (java, php; csharp, go: `Tools`) still contains an `mcp_toolset` that references one of the agent's servers. Override `tools` (java, php; csharp, go: `Tools`) in the same request to remove those `mcp_toolset` entries, then clear `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).
470 * Clearing `tools` returns a 400 error when the session's effective `skills` (csharp, go: `Skills`) is non-empty, because skills require the `read` tool. Otherwise, `tools: null` and `tools: []` clear the field.
471 * 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`).
472472
473* **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` (java, php; csharp, go: `Tools`) override must list every tool the session should have. Likewise, a `model` (java, php; csharp, go: `Model`) override replaces the agent's `model` (java, php; csharp, go: `Model`) object in full, so the agent's own `effort` (java, php; csharp, go: `Effort`) isn't carried over. To run the session at a specific effort level, set `effort` (java, php; csharp, go: `Effort`) inside the override's `model` (java, php; csharp, go: `Model`) object. A level the model doesn't support returns a 400 error, and a `model` (java, php; csharp, go: `Model`) override without `effort` (java, php; csharp, go: `Effort`) runs at that model's default effort level.
473* **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.
474474
475475Overrides 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.
476476
477In the response, the `agent` (java, php; csharp, go: `Agent`) object reflects the configuration the session runs with after the overrides are applied. Its `id` (java, php; csharp, go: `ID`) and `version` (java, php; csharp, go: `Version`) still identify the agent and version the overrides are applied to. This lets you trace a session back to its base agent.
477In the response, the `agent` (csharp, go: `Agent`) object reflects the configuration the session runs with after the overrides are applied. Its `id` (csharp, go: `ID`) and `version` (csharp, go: `Version`) still identify the agent and version the overrides are applied to. This lets you trace a session back to its base agent.
478478
479479The following example starts a session that overrides the model and clears the system prompt:
480480
from line 641
641641
642642#### Pin the inference geo for a session
643643
644Because a `model` (java, php; csharp, go: `Model`) override replaces the agent's `model` (java, php; 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, and one 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.
644Because 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, and one 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.
645645
646The 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` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (java, php; csharp, go: `Model`) override, and prints the value echoed in the response's `agent.model` (java, php; csharp, go: `Agent.Model`):
646The 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` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (csharp, go: `Model`) override, and prints the value echoed in the response's `agent.model` (csharp, go: `Agent.Model`):
647647
648648<CodeGroup>
649649 ```bash cURL
from line 800
800800
801801### Set a session budget
802802
803To cap what a session can spend, pass the optional `budget` (java, php; 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`). Set `type` (java, php; csharp, go: `Type`) to `limit` and give `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) an `amount` (java, php; csharp, go: `Amount`) and a `currency` (java, php; csharp, go: `Currency`). `amount` (java, php; csharp, go: `Amount`) is a whole number of US cents written as a string, such as `"125"` for $1.25. 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 finishes 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](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) it later, but you can't add one to a session created without it.
803To 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`). Set `type` (csharp, go: `Type`) to `limit` and 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. 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 finishes 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](https://platform.claude.com/docs/en/managed-agents/session-operations#updating-the-session-budget) it later, but you can't add one to a session created without it.
804804
805805The following example creates a session with a $1.25 budget:
806806
No line in this hunk matches that.