Beta Environments Reference

Purpose and Scope

Beta Environments are the SDK surface for configuring execution environments used by Managed Agents, especially when a session needs either an Anthropic-managed cloud environment or a self-hosted runner. In the TypeScript SDK, the public entry point is organized under the beta namespace as the environments resource, with a nested work resource for self-hosted work items. This page is a reference for the TypeScript names, request shapes, and operational flow visible in the generated SDK tests and environment helper exports. It is aimed at developers wiring Managed Agents into a production runner, not at users making ordinary Messages API calls.

Sources: src/resources/beta/environments/index.ts, tests/api-resources/beta/environments/environments.test.ts, tests/api-resources/beta/environments/work.test.ts, src/lib/environments/index.ts

The API is beta-gated. In the TypeScript SDK tests, beta opt-ins are passed as a request parameter named betas, which becomes the Anthropic beta header for that call. Official API documentation describes the same concept as an optional beta header and lists managed agents among available beta identifiers. Treat these values as part of your integration contract: create, session, and worker calls that depend on Managed Agents behavior should pass the required beta identifier consistently, rather than assuming a beta surface is enabled globally for every request.

Sources: tests/api-resources/beta/environments/environments.test.ts, tests/api-resources/beta/environments/work.test.ts, api.md

Relevant Source Files

• src/resources/beta/environments/index.ts — Barrel export for the generated beta environments namespace, including environment configuration types, environment method parameter types, work resource types, work lifecycle parameter types, and cursor page types.
• tests/api-resources/beta/environments/environments.test.ts — Generated API resource tests showing how client.beta.environments is called for create, retrieve, update, and list, including beta parameters and response helper behavior.
• tests/api-resources/beta/environments/work.test.ts — Generated API resource tests for client.beta.environments.work, including retrieve, update, acknowledgement, beta parameters, environment identifiers, and skipped list coverage for a known path query issue.
• src/lib/environments/index.ts — Helper barrel for worker-side utilities: WorkPoller, EnvironmentWorker, polling constants, backoff and jitter helpers, status predicates, and SessionToolRunner exports used by local self-hosted workers.
• api.md — Generated API reference material for the SDK and API surface, used here as repository-level reference context for the beta environments endpoint family.

Core Concepts

An environment is a named execution target. The official API documentation describes creation with a human-readable name and optional configuration. The configuration can represent a cloud environment, and the exported SDK types also include self-hosted configuration parameters. A cloud configuration can include networking policy and package lists. Networking may be unrestricted or limited; a limited policy can allow configured MCP servers, allow package managers, and name allowed outbound hosts. Packages are grouped by package manager, including apt, cargo, gem, go, npm, and pip in the generated test example.

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

A work item is the unit a self-hosted environment worker claims and serves. The nested work resource is exported beside the environment resource, and its types cover retrieval, update, listing, acknowledgement, heartbeat, polling, stats, and stop requests. This separation matters operationally: environment methods define and manage the execution target, while work methods coordinate leased tasks that a runner performs for sessions using that target. The tests show every work call carrying an environment identifier, so a runner should treat the environment id as a required routing key for work lifecycle requests.

Sources: src/resources/beta/environments/index.ts, tests/api-resources/beta/environments/work.test.ts

The helper layer turns the low-level work API into a worker-oriented runtime. The environment helper barrel exports a poller, a worker class, options types, polling constants, backoff and jitter functions, and predicates for status handling. It also re-exports the session tool runner used to execute session tool calls. This tells SDK users there are two legitimate integration levels. You can call the generated work resource directly when you already have an orchestrator, or you can use the higher-level worker utilities when your process should poll, claim, heartbeat, run tools, and stop work items as a managed loop.

Sources: src/lib/environments/index.ts

Environment Resource API

The primary resource is reached through the beta client namespace. The generated tests construct an Anthropic client, then call the environments resource with promise helpers that expose both parsed data and the underlying web response. The same response promise supports awaiting parsed data, reading the raw response, and obtaining both together through a response pair. That pattern is consistent with other generated resources in this SDK and is useful for production debugging because headers, status, and body parsing can be inspected without changing the high-level method call.

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

const environment = await client.beta.environments.create({
  name: 'python-data-analysis',
  config: {
    type: 'cloud',
    networking: {
      type: 'limited',
      allow_mcp_servers: true,
      allow_package_managers: true,
      allowed_hosts: ['api.example.com'],
    },
    packages: {
      type: 'packages',
      pip: ['pandas', 'numpy'],
    },
  },
  description: 'Python environment with data-analysis packages.',
  metadata: { team: 'analytics' },
  scope: 'organization',
  betas: ['managed-agents-2026-04-01'],
});

Create accepts only a name in the minimal generated test, which is helpful for incremental adoption. A team can first create a named environment and later update the configuration as isolation, networking, packages, and visibility requirements become clear. The richer test demonstrates the shape of a cloud environment with limited networking and package configuration, plus description, metadata, scope, and betas. Scope is important for self-hosted environments because official documentation distinguishes organization visibility from account visibility. Metadata is a useful place to add deployment ownership, environment purpose, or orchestration labels, but it should not be treated as a secret store.

Sources: tests/api-resources/beta/environments/environments.test.ts, api.md

The environment barrel exports configuration and response types for a broad set of operations: cloud and self-hosted configuration, limited and unrestricted networking, package definitions, environment creation, retrieval, update, list, delete, archive, and cursor pagination. The tests directly exercise create, retrieve, update, and list. Delete and archive are visible through exported parameter and response types, so consumers should expect those operations to be part of the generated resource surface even when designing a documentation-first integration. Listing accepts pagination-style inputs in the tests, including limit and page, along with an include archived flag for inventory views.

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

Work Resource and Worker Helpers

The nested work resource is reached through the environments namespace. The tests show calls such as retrieve and update receiving a work identifier as the path argument and an object containing environment_id as request parameters. Update requires metadata in the minimal test, and optional betas can be supplied. Acknowledgement follows the same identifier pattern and is the visible mechanism for confirming that a runner has claimed or accepted a work item. These shapes are important for orchestration because the work id alone is not enough; every request is scoped to the environment that owns the queue.

Sources: tests/api-resources/beta/environments/work.test.ts

const work = await client.beta.environments.work.retrieve('work_id', {
  environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
  betas: ['managed-agents-2026-04-01'],
});
 
await client.beta.environments.work.ack('work_id', {
  environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
});

The exported work types show the intended lifecycle beyond the small subset exercised in non-skipped tests. A self-hosted worker can retrieve work, update metadata, list or poll for available work, acknowledge a claim, heartbeat an active lease, request stats, and stop an item. Heartbeats are especially significant for long-running tool execution: they let the platform know that the worker is still alive while it is preparing a working directory, downloading session material, executing tools, or waiting for session events. Stop requests provide the cleanup side of the lifecycle, preventing abandoned work from looking active after a sandbox exits.

Sources: src/resources/beta/environments/index.ts, tests/api-resources/beta/environments/work.test.ts

The helper exports in the environment library are the SDK’s convenience layer for that lifecycle. WorkPoller and EnvironmentWorker package the repetitive polling and serving behavior, while backoff, jitter, isStatus, is4xx, and isFatal4xx support resilient loops and error classification. SessionToolRunner connects claimed session work to tool execution, and the exported constants document that polling and idle behavior are intentional parts of the runtime. When building a self-hosted runner, prefer these helpers unless you have a separate queueing system that already owns polling, process supervision, and lease management.

Sources: src/lib/environments/index.ts

Execution Flow

A typical cloud-environment flow starts with creation, using a clear name and a configuration that encodes package and network requirements. After creation, the environment can be retrieved to confirm server-side state, updated as requirements change, listed for administration, and archived or deleted according to lifecycle policy. A production platform should store the environment identifier returned by creation, not depend on name lookup, because all downstream sessions and work APIs identify environments by id. Use metadata for human and automation labels, and reserve beta parameters for explicit feature gating.

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

A typical self-hosted flow adds a worker loop. First, create or choose a self-hosted environment and configure sessions to target it. Next, a worker polls for work associated with that environment. When work is available, the worker acknowledges it, performs setup, runs session tools, and heartbeats the lease while the item remains active. When the item is complete or the process is shutting down, the worker stops the item or otherwise releases it according to the work API. The helper layer exists so application code can focus on tools and isolation boundaries rather than hand-writing the same control loop.

Sources: src/resources/beta/environments/index.ts, src/lib/environments/index.ts, tests/api-resources/beta/environments/work.test.ts

One testing signal deserves special attention. The generated work tests skip list coverage with a note that path-level query parameters are dropped by URL building for that case. That does not remove the exported list parameter type, but it is a reminder to verify list or poll behavior against the API version and SDK version you deploy. For worker systems, polling and acknowledgement are more operationally important than one-off list inspection, so integration tests should cover the exact queue access pattern your runner uses, including pagination or blocking behavior when applicable.

Sources: tests/api-resources/beta/environments/work.test.ts

Testing Signals and Response Handling

The generated tests consistently exercise response helper behavior for both environments and work. A method call returns a promise-like object that can yield the parsed resource, a raw Response, or a pair containing both data and response. The tests assert that the parsed response is not itself a Response and that the paired data is identical to the awaited parsed value. This matters when implementing diagnostics: you do not need to abandon typed SDK methods to inspect transport metadata, and you can keep normal application logic typed while adding targeted logging around status, headers, and request identifiers.

Sources: tests/api-resources/beta/environments/environments.test.ts, tests/api-resources/beta/environments/work.test.ts

The tests also verify request options are passed through by intentionally overriding the path to an unknown route and expecting a NotFoundError. That pattern appears for environment retrieval and listing, and for work listing in skipped coverage. For application code, the practical takeaway is that method parameters and per-call request options are separate concerns. Put API fields such as betas, pagination, metadata, and environment identifiers in the method parameter object. Use request options for transport-level overrides, diagnostics, or test-specific path behavior, and avoid mixing those responsibilities in wrapper functions.

Sources: tests/api-resources/beta/environments/environments.test.ts, tests/api-resources/beta/environments/work.test.ts

Next Steps

If you are defining the execution target itself, start with create, retrieve, update, and list on the beta environments resource, then decide whether your environment should be cloud or self-hosted. If you are operating a self-hosted runner, focus on the nested work resource and the helper exports from the environment library. Validate beta identifiers in every environment, session, and worker path that depends on Managed Agents. For adjacent documentation, read the Managed Agents overview, Managed Agent sessions reference, and cloud sandbox material before designing production isolation, package installation, outbound networking, and work lease policies.

Sources: src/resources/beta/environments/index.ts, src/lib/environments/index.ts, api.md