Beta Sessions Reference

Purpose and Scope

Beta sessions are the SDK surface for operating Managed Agent sessions under client.beta.sessions. A session is the running container for an agent invocation: it is created from an agent and an environment, may be given resources such as uploaded files, and exposes status and event streams as work proceeds. This page is a reference for the TypeScript SDK names around sessions, nested session resources, session events, threads, and thread events. It is intended for developers who already understand the Managed Agents concepts and now need the concrete SDK entry points and parameter shapes.

The beta namespace matters because Managed Agents are version-gated platform features. The official API examples use an anthropic-beta header such as managed-agents-2026-04-01, while the SDK exposes beta header values through betas arrays on relevant parameter objects. In practice, this means you normally call methods through client.beta.sessions... and supply beta versions only when the endpoint or account configuration requires them. The generated TypeScript resources keep those beta parameters near the methods they affect rather than forcing callers to construct raw headers themselves.

Sources: src/resources/beta/sessions/index.ts, src/resources/beta/sessions/threads/index.ts, tests/api-resources/beta/sessions/sessions.test.ts, tests/api-resources/beta/sessions/resources.test.ts, api.md

Relevant Source Files

• src/resources/beta/sessions/index.ts - Generated beta sessions barrel that re-exports the session resource family, nested Events and Resources resources, page cursor types, event payload types, resource payload types, and session parameter types.
• src/resources/beta/sessions/threads/index.ts - Generated threads barrel for nested session threads, including thread events, thread retrieval/list/archive parameter types, status, usage, stats, and cursor exports.
• tests/api-resources/beta/sessions/sessions.test.ts - SDK integration-style tests showing client.beta.sessions.create, retrieve, update, skipped list coverage, response helper behavior, beta parameters, and request option forwarding.
• tests/api-resources/beta/sessions/resources.test.ts - SDK tests for nested session resources showing retrieve, update, list, and delete call shapes, including session_id, pagination fields, authorization_token, betas, and request option forwarding.
• api.md - Generated API reference source for the repository, used as the broad contract location for endpoint-level reference material.

System-to-Code Mapping

The central export file for this surface is src/resources/beta/sessions/index.ts. It is generated from the OpenAPI specification and acts as the public TypeScript map for the beta sessions subtree. The file re-exports the Events resource and a large set of event payload types, including agent message, agent thinking, tool use, tool result, MCP tool use, MCP tool result, retry status, session status, thread status, model span, outcome evaluation, user interrupt, user message, and user tool confirmation events. That breadth is a signal that session operation is event-oriented: after creating a session, clients should expect state and content to arrive through typed event objects rather than only through a final session record.

The same sessions barrel also re-exports the Resources nested resource and several resource model types. The visible exports include file resources, GitHub repository resources, memory store resources, delete responses, session resource unions, resource parameter types, and cursor pagination for session resources. These names line up with Managed Agent sessions as isolated execution contexts that can mount or reference data. For example, the official Add Session Resource API accepts a previously uploaded file_id, a resource type of file, and an optional mount_path that defaults to a path under the session uploads directory. The SDK represents that workflow through the nested resources namespace rather than asking callers to hand-build /v1/sessions/{session_id}/resources requests.

Threads are separated into src/resources/beta/sessions/threads/index.ts, which exports a Threads class, nested thread Events, and typed request parameters for retrieving, listing, and archiving threads. A thread is the conversation or work stream inside a session; the exported types include BetaManagedAgentsSessionThread, BetaManagedAgentsSessionThreadStatus, BetaManagedAgentsSessionThreadStats, BetaManagedAgentsSessionThreadUsage, and BetaManagedAgentsStreamSessionThreadEvents. That split gives the SDK a clear hierarchy: sessions own session-level lifecycle and resources, threads own thread records and thread-local events, and both levels expose event streaming abstractions.

Sources: src/resources/beta/sessions/index.ts, src/resources/beta/sessions/threads/index.ts

Session API Components

The visible test coverage shows the primary session methods through the public client. client.beta.sessions.create accepts required agent and environment_id fields. Optional fields in the test include metadata, an initial resources array, title, vault_ids, and betas. The initial resource example contains file_id, type: 'file', and mount_path, which is the same resource vocabulary used by the standalone session resource API. This lets callers create a session and attach a file in one operation when the application already knows which file should be available to the agent.

client.beta.sessions.retrieve accepts a session id such as sesn_011CZkZAtmR3yMPDzynEDxu7. The test also demonstrates the SDK's standard method pattern: a call returns a promise-like API object that can be awaited for parsed data, converted to a raw Response with .asResponse(), or resolved with both parsed data and the raw response through .withResponse(). That behavior is not unique to sessions, but it is important for operational code that needs headers, status, tracing metadata, or raw response access while still using typed SDK resource methods.

client.beta.sessions.update is shown with a session id and an empty update object, which establishes the method shape even though the snippet does not expose a meaningful update payload. client.beta.sessions.list appears as skipped test coverage because of a noted path-level query issue in the generated mock-server path builder. The skipped list test still reveals the intended list-style pattern: it accepts a params object with filters such as agent_id, agent_version, and created-at comparison fields, plus the same response helper conventions as other SDK methods. Treat the list call as a paginated/filtering method whose exact filter set should be checked against the generated TypeScript definitions in your installed SDK version.

Sources: tests/api-resources/beta/sessions/sessions.test.ts

Session Resources Reference

Session resources are addressed below client.beta.sessions.resources. The test file shows methods for retrieving, updating, listing, and deleting resources. Each resource method that operates on a specific resource id also carries the parent session_id, because the REST path is nested under a session. For example, retrieve receives a resource id like sesrsc_011CZkZBJq5dWxk9fVLNcPht and a params object containing session_id; the optional form adds betas. This keeps the parent-child relationship explicit in TypeScript even when the method name already sits under the sessions namespace.

The update example demonstrates a session resource update with authorization_token, which is relevant for resource types that need follow-up credentials or authorization after being attached. The list example accepts the session id first and then a params object with limit, page, and betas. The delete example accepts the resource id plus session_id. The official API reference for adding a session resource describes a POST to /v1/sessions/{session_id}/resources with file_id, type: 'file', and optional mount_path, returning a BetaManagedAgentsFileResource with identifiers, timestamps, file id, mount path, and type. Use the SDK method names and generated types as the source of truth for your installed package version, and use the official endpoint examples to understand the corresponding HTTP shape.

const session = await client.beta.sessions.create({
  agent: 'agent_011CZkYpogX7uDKUyvBTophP',
  environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
  title: 'Order #1234 inquiry',
  resources: [
    {
      file_id: 'file_011CNha8iCJcU1wXNR6q4V8w',
      type: 'file',
      mount_path: '/uploads/receipt.pdf',
    },
  ],
  vault_ids: ['string'],
  betas: ['message-batches-2024-09-24'],
});

const resource = await client.beta.sessions.resources.retrieve(
  'sesrsc_011CZkZBJq5dWxk9fVLNcPht',
  { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' },
);

Sources: tests/api-resources/beta/sessions/resources.test.ts, src/resources/beta/sessions/index.ts, api.md

Events, Streaming, and Threads

The sessions export list is dense because events are first-class in Managed Agent operation. Session-level event types include lifecycle states such as idle, running, rescheduled, terminated, and deleted; thread creation and thread status changes; errors; retry states; user-originated events; agent-originated messages and thinking; tool use and tool results; MCP tool use and results; model request spans; and outcome evaluation spans. The exported parameter types EventListParams, EventSendParams, and EventStreamParams show that the SDK supports listing events, sending events, and streaming events through the beta session event resource.

For applications, the important design point is that sessions are not just CRUD records. A session can require user action, receive user interrupts, send user messages, emit tool confirmations, and report model or tool failures. The exported event vocabulary gives TypeScript applications discriminated event shapes for orchestration loops, user interfaces, logs, or worker processes. When you build a session runner, model these events as the durable stream of what happened, and use the session record as the current high-level state rather than as the only source of operational detail.

Threads add another level of event handling. The thread index exports Events with EventListParams and EventStreamParams, while the Threads resource exports ThreadRetrieveParams, ThreadListParams, and ThreadArchiveParams. It also exports thread status, stats, usage, and a stream type for thread events. Use session events when you need whole-session lifecycle, resource, or cross-thread context. Use thread APIs when you need to inspect, list, archive, or stream a particular conversation or work thread inside the session. This separation helps multi-threaded agent sessions remain observable without collapsing every event into one unstructured channel.

Sources: src/resources/beta/sessions/index.ts, src/resources/beta/sessions/threads/index.ts

Compact SDK Reference

Use this table as a navigation aid, not as a replacement for editor autocomplete. Because these files are generated from the OpenAPI specification, the installed .d.ts files in your dependency are the most precise reference for optionality, unions, cursor page types, and beta version enums. The tests are especially useful when you want to understand call order and SDK ergonomics: identifiers come first when they are path parameters, nested parent identifiers are carried in params objects, and request options can be passed as a final argument to exercise path overrides or other request-level behavior.

Sources: src/resources/beta/sessions/index.ts, src/resources/beta/sessions/threads/index.ts, tests/api-resources/beta/sessions/sessions.test.ts, tests/api-resources/beta/sessions/resources.test.ts

Testing Signals and Next Steps

The session tests provide two kinds of confidence. First, they verify generated methods return SDK response wrappers that can be consumed as parsed data, raw responses, or data-plus-response pairs. Second, they verify request options and beta params are threaded through the method signatures by intentionally using an invalid path and expecting Anthropic.NotFoundError. Some list and resource tests are skipped because the mock server could not match beta-only or path-query endpoints in the generated test environment. That skip status is a testing limitation, not a reason to avoid the SDK method names shown by the generated client surface.

When implementing against beta sessions, start with client.beta.sessions.create and decide whether initial resources should be attached at creation time or later through the nested resources API. Then choose the correct observation channel: retrieve the session for point-in-time state, list or stream session events for lifecycle and cross-thread changes, and use thread resources when your application presents or archives individual conversation threads. If your flow attaches files, make sure the file already exists and decide whether to set an explicit mount path. For further context, read the Managed Agents overview, beta agents reference, beta environments reference, and files resource reference pages.

Sources: tests/api-resources/beta/sessions/sessions.test.ts, tests/api-resources/beta/sessions/resources.test.ts, src/resources/beta/sessions/index.ts, src/resources/beta/sessions/threads/index.ts