Managed Agent Sessions

Purpose and Scope

Managed Agent sessions are the runtime instances that execute a configured agent inside an environment. In product terms, an agent is the versioned definition, an environment provides the execution context, and a session is where conversation history, tool requests, and task progress accumulate. The TypeScript SDK exposes this workflow through the beta namespace and supports it with generated agent resources plus helper code for operating session event streams. This page orients developers who already know how to create an agent and now need to start work, handle local tool calls, and understand how session threads fit into multi-agent execution.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/lib/tools/SessionToolRunner.ts

All Managed Agents API calls require the managed-agents-2026-04-01 beta capability. The SDK source makes that requirement concrete in two places: generated agent methods add the beta value to the anthropic-beta header, and the session tool runner defines the same value as MANAGED_AGENTS_BETA. That matters because sessions are not a separate mode of the SDK; they are part of the generated beta API surface and helper layer. When you use the SDK entrypoints rather than raw HTTP, beta header management is intended to be part of the client behavior.

Core Primitives

A session starts from an agent reference. The generated Agents resource exposes create, retrieve, update, list, archive, and nested version-listing operations for the versioned configuration that sessions run. Official Managed Agents guidance describes session creation as requiring an agent ID and an environment_id, with a string agent ID resolving to the latest agent version. The source reinforces that agents are versioned resources: Agents owns a versions subresource, and src/resources/beta/agents/index.ts re-exports both the agent types and the Versions class for callers that need to inspect available versions before starting or debugging a session.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/resources/beta/agents/index.ts

Threads are the unit of isolated conversation context inside a session. In a single-agent run, the primary thread is the session-level event stream. In a multi-agent session, the coordinator can delegate work to additional agents, and each delegated agent runs in its own persistent session thread with separate conversation history. The SDK type surface reflects this model through exported Managed Agents types such as BetaManagedAgentsMultiagentCoordinator, BetaManagedAgentsMultiagentSelfParams, and BetaManagedAgentsSessionThreadAgent. Those exports are useful when building higher-level configuration and orchestration code that needs to describe a coordinator and the agents it can call.

Relevant Source Files

• src/resources/beta/agents/index.ts re-exports the generated Managed Agents agent resource, agent configuration types, multi-agent types, session-thread agent type, and the nested versions resource.
• src/lib/tools/SessionToolRunner.ts implements the helper behavior for operating session event streams with local runnable tools, including beta header naming, retry constants, idle behavior, abort handling, and request option plumbing.
• src/resources/beta/agents.ts is the generated barrel that exposes the beta agents module from the broader beta resource tree.
• src/resources/beta/agents/agents.ts defines the generated Agents class, its nested versions resource, endpoint paths, pagination behavior, and beta-header injection for agent lifecycle methods.
• src/resources/beta/agents/versions.ts defines client.beta.agents.versions.list(agentID, params?, options?) and returns a cursor-paginated list of agent versions with the Managed Agents beta header.
• src/lib/tools/BetaRunnableTool.ts defines the shared runnable tool contract used by both Messages tool runners and the session event tool runner.

System-to-Code Mapping

The generated agent files are the configuration side of session operation. Agents.create() posts to /v1/agents?beta=true with the agent body, retrieve() and update() address /v1/agents/{agentID}?beta=true, list() uses SDK pagination over /v1/agents?beta=true, and archive() targets /v1/agents/{agentID}/archive?beta=true. These methods do not run a session by themselves; they produce and maintain the agent definitions that sessions reference. If a session behaves unexpectedly, checking the current agent version and the version history is often the first source-level place to reason about configuration drift.

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

The helper code is the operation side. SessionToolRunnerOptions accepts an Anthropic client, an array of BetaRunnableTool implementations, optional idle timeout, optional external abort signal, and request options shared across the stream, list, and send calls the runner issues. Its comments explicitly connect the helper to client.beta.sessions.events.toolRunner and recommend betaAgentToolset20260401({ workdir }) from @anthropic-ai/sdk/tools/agent-toolset/node for the standard local agent toolset. The request option design is practical: proxy headers and routing headers can be propagated, while the runner retains ownership of the abort signal.

Sources: src/lib/tools/SessionToolRunner.ts, src/lib/tools/BetaRunnableTool.ts

Execution Flow

A typical session flow has two phases. First, create or choose a versioned agent, then create a session with the agent ID and environment ID. Official TypeScript guidance shows await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id }). Second, send a user event to start work and consume the session event stream. The event stream is where user messages, agent messages, tool-use requests, tool results, stop reasons, and thread activity become visible. In multi-agent runs, the coordinator reports on the primary thread while delegated agents maintain their own persistent thread histories.

const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'Support triage agent',
});
 
const versions = client.beta.agents.versions.list(agent.id);
for await (const version of versions) {
  console.log(version.id);
}
 
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
});

After the session is started, decide whether the agent uses only server-side capabilities or also needs local client-run tools. Server-side MCP tool calls are intentionally excluded from the local runner’s dispatch path. The runner dispatches local built-in agent.tool_use events and custom agent.custom_tool_use events, then sends matching user.tool_result or user.custom_tool_result events back to the session. This strict pairing prevents a custom tool result from being posted for a built-in tool call or vice versa, which is important when multiple tools and event types are active.

Sources: src/lib/tools/SessionToolRunner.ts

Local Tool Runner Contract

BetaRunnableTool is the contract for client-side tools. A runnable tool combines a beta tool definition with parse(content), run(args, context?), and an optional close() cleanup hook. The BetaToolRunContext exposes toolUse, the event or content block that triggered execution, plus an abort signal. The type is intentionally shared across Messages and Managed Agent sessions: the same implementation can often run under client.beta.messages.toolRunner or client.beta.sessions.events.toolRunner as long as it only depends on common id, name, and input fields.

Sources: src/lib/tools/BetaRunnableTool.ts

Operationally, the runner is designed for long-lived iteration rather than a single request-response call. Its constants show the expected failure and lifecycle boundaries: stream backoff begins at 500 ms and caps at 10 seconds, individual tool calls have a 120 second timeout, draining has a 30 second timeout, and sends are retried three times. maxIdleMs defaults to 60 seconds and starts counting after the session goes idle with stop_reason.type === "end_turn". Set it to zero or a negative value when you want the runner to continue until termination, abort, or consumer break.

Compact Reference

Next Steps

Use the agent resource reference when you need exact generated method names and pagination behavior, then move to the session event streaming material for event ordering, deltas, and accumulation helpers. For local tool execution, read the tool helper and JSON Schema or Zod helper pages before wiring tools into sessions; the same runnable tool contract is shared across Messages and Managed Agent surfaces. For multi-agent designs, model the coordinator, delegated agents, and persistent thread boundaries first, then validate agent versions before creating sessions so runtime behavior matches the configuration you intended.