The Sessions resource exposes managed-agent conversations with three nested sub-resources (events, resources, threads), supporting creation with an agent and environment, real-time event streaming, and tool dispatch via SessionToolRunner. The Anthropic Python SDK's Sessions API is gated by the managed-agents-2026-04-01 beta header and manages spend budgets, metadata, and updatable agent tooling — with SessionToolRunner handling async tool dispatch, permission gates, and idle timeouts on the event stream.
The Sessions resource in src/anthropic/resources/beta/sessions/sessions.py exposes three nested sub-resources — events, resources, and threads — each accessible as a @cached_property attribute on the Sessions class.[1] Every request made via Sessions automatically includes the anthropic-beta: managed-agents-2026-04-01 header; if additional betas are supplied they are prepended to that fixed value before it is set to the constant.[1] List pagination for Sessions uses SyncBidirectionalPageCursor / AsyncBidirectionalPageCursor.[1]
Sessions.create() requires agent and environment_id; all other parameters — budget, initial_events, metadata, resources, title, vault_ids, and betas — are optional and use the omit sentinel to exclude them from the serialized request body.[1] Sessions.create() posts to /v1/sessions?beta=true and returns a BetaManagedAgentsSession object.[1] The initial_events parameter of Sessions.create() accepts up to 50 events of types user.message or user.define_outcome, processed in order when the session is created.[1] The budget parameter of Sessions.create() sets a hard spend ceiling: the session stops issuing new model requests once the tracked list cost reaches max_list_cost.[1] The metadata parameter of Sessions.create() accepts a dict with a maximum of 16 key-value pairs, keys up to 64 characters and values up to 512 characters.[1] Sessions.retrieve() issues a GET to /v1/sessions/{session_id}?beta=true and returns a BetaManagedAgentsSession.[1] Both Sessions.retrieve() and Sessions.update() raise ValueError with a descriptive message if session_id is an empty string.[1] Sessions.update() accepts an agent param of type BetaManagedAgentsSessionAgentUpdateParam; only tools and mcp_servers fields within it are updatable, and the update is a full replacement — to preserve existing entries, GET the session, modify the array, and POST it back.[1] The metadata parameter of Sessions.update() is a patch: setting a key to a string upserts it, setting it to null deletes it, and omitting the field preserves existing metadata.[1] The vault_ids parameter of Sessions.update() is reserved for future use — requests setting this field are currently rejected.[1]
Sessions.with_raw_response returns a SessionsWithRawResponse wrapper that gives access to raw HTTP response objects rather than parsed content.[1] Sessions.with_streaming_response returns a SessionsWithStreamingResponse wrapper that does not eagerly read the response body, suitable for streaming use cases.[1]
SessionToolRunner (in src/anthropic/lib/tools/_beta_session_runner.py) attaches to a Managed Agents session's event stream, dispatches agent.tool_use and agent.custom_tool_use events against a local tool registry, posts results back via user.tool_result / user.custom_tool_result, and yields one DispatchedToolCall per completed call.[2] The tool type accepted by SessionToolRunner is BetaAnyRunnableTool, a union of BetaRunnableTool (sync) and BetaAsyncRunnableTool (async).[2] DispatchedToolCall is a frozen dataclass with an event field (the originating agent.tool_use or agent.custom_tool_use event), a result field (the posted-back result params, or None if nothing was posted), and convenience fields name and tool_use_id.[2]
Confirmation-gated tool calls — those with evaluated_permission of ask, e.g. always_ask tools — are held by SessionToolRunner until a user.tool_confirmation event arrives: executed on allow, never executed on deny.[2] SessionToolRunner stops itself after the session has been idle (with stop_reason end_turn) for max_idle seconds; the default is 60.0 seconds, and max_idle=None disables the timeout.[2] The per-tool-call timeout is TOOL_TIMEOUT = 150.0 seconds — intentionally larger than the bash tool's own 120-second timeout so the inner bash timeout can clean up before the outer one fires.[2] Stream reconnect backoff starts at STREAM_BACKOFF_START = 0.5 seconds and is capped at STREAM_BACKOFF_CAP = 10.0 seconds.[2] Result-posting to the session is retried up to SEND_RETRIES = 3 times.[2] SessionToolRunner does not manage work-item leases (heartbeating / force-stop); wrap it in anthropic.lib.environments.EnvironmentWorker if that behavior is needed — see Environment worker.[2]
The MANAGED_AGENTS_BETA constant ("managed-agents-2026-04-01") is the anthropic-beta header value that gates Sessions access to self-hosted environments; it is also required for work-item stop calls issued by EnvironmentWorker.[2]
Sources