Cloud Environments and Work

Purpose and Scope

Cloud environments are the Managed Agents configuration objects that describe where a session runs. In the first-party Managed Agents documentation, an environment can be created once and then referenced whenever a session starts; for type: cloud, each session receives its own isolated Linux sandbox even when multiple sessions reuse the same environment. This page explains that concept from the TypeScript SDK perspective and maps it to the generated beta Managed Agents surface and helper code that participates when agents run tools during sessions.

The repository evidence for this page is centered on agent resources and beta tool helpers rather than the environment resource implementation itself. That still matters for environment workflows: an environment is useful only when it is connected to an agent session, and the SDK code shows how Managed Agents resources consistently attach the managed-agents-2026-04-01 beta header and how tool execution is normalized across Messages and session event surfaces. Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/lib/tools/BetaRunnableTool.ts, src/lib/tools/BetaToolRunner.ts

Core Primitives

A Managed Agent workflow has three related primitives. The agent is the durable definition of the assistant configuration, including model, tools, skill references, MCP toolsets, and related policy fields exported from the beta agents module. The environment is the sandbox configuration used when the agent runs in a session; official docs show cloud environments with networking policy and optional package configuration. Work items are the queued execution units used by self-hosted sandbox workers, while cloud environments hide most of that orchestration behind the managed platform.

The SDK’s generated agent surface makes the agent primitive explicit through client.beta.agents.create, retrieve, update, list, and archive, plus client.beta.agents.versions.list. The export barrel exposes many Managed Agents types, including tool configs, built-in toolset input types, custom tools, MCP toolsets, model configs, multiagent coordinator types, and skill params. Those exported names are the TypeScript vocabulary users combine with environment IDs and session creation in higher-level Managed Agents flows. Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents.ts, src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Relevant Source Files

• src/resources/beta/agents/index.ts - Re-exports the generated Agents resource, Versions resource, and the Managed Agents type surface for agent configs, tools, skills, MCP toolsets, models, and pagination.
• src/resources/beta/agents.ts - Provides the beta agents namespace barrel by exporting from ./agents/index, which is how the generated resource group is surfaced to consumers.
• src/resources/beta/agents/agents.ts - Implements generated beta agent methods such as create, retrieve, update, list, and archive, and shows the managed-agents beta header being attached to requests.
• src/resources/beta/agents/versions.ts - Implements client.beta.agents.versions.list(agentID, ...) with cursor pagination and the same Managed Agents beta header pattern.
• src/lib/tools/BetaRunnableTool.ts - Defines runnable beta tools, session-event-compatible tool use context, tool name resolution, error formatting, and the optional cleanup hook used by session tool runners.
• src/lib/tools/BetaToolRunner.ts - Implements the beta tool runner loop for automatically alternating between assistant responses and local tool execution, including helper headers and iteration state.

System-to-Code Mapping

Official docs present cloud environment creation as client.beta.environments.create({ name, config: { type: "cloud", networking: { type: "unrestricted" } } }). That call creates the sandbox template, not the sandbox instance itself. The sandbox instance is created per session, so developers should think of the environment ID as reusable configuration and the session as the runtime boundary. In SDK code, the nearest visible managed-agent resource pattern is the generated Agents class, where each method uses buildHeaders to append managed-agents-2026-04-01 to any caller-supplied beta headers.

That header behavior is important because the official docs state that all Managed Agents API requests require the Managed Agents beta header and that the SDK sets it automatically. The agent methods demonstrate the pattern by destructuring betas from params, sending the remaining values as body or query, and composing the final anthropic-beta header with both caller betas and managed-agents-2026-04-01. Version listing follows the same approach for paginated reads under /v1/agents/{agentID}/versions?beta=true. Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Execution Flow

A typical cloud sandbox flow starts by creating an environment, then creating or selecting an agent, then starting a session that references the agent and environment. The environment config controls sandbox policy, such as whether networking is unrestricted or limited. The agent config controls model and capabilities. At runtime, the session owns the isolated container and the event stream. If the agent requests a local client-runnable tool, SDK helper code can execute the tool and feed the result back to the model.

For example, the cloud environment creation shape from the official docs is:

const environment = await client.beta.environments.create({
  name: "python-dev",
  config: {
    type: "cloud",
    networking: { type: "unrestricted" },
  },
});
 
console.log(`Environment ID: ${environment.id}`);

Self-hosted environments introduce an explicit work queue. The official API reference describes POST /v1/environments/{environment_id}/work/{work_id}/ack as an endpoint called automatically by the pre-built environment worker in SDKs and CLI implementations. Acknowledgement transitions a work item from queued to starting and removes it from the queue. For application developers, that means cloud environment users normally configure and reference environments, while self-hosted sandbox operators also run worker infrastructure that polls, acknowledges, executes, and reports work.

Tool Execution in Sandbox-Oriented Sessions

The tool helper layer clarifies the boundary between server-side sandbox execution and local client execution. BetaRunnableTool explicitly models tool types that can be implemented on the client and excludes server-side tools such as code execution, web search, and MCP toolsets. Its BetaToolUse union accepts both Messages tool-use content blocks and Managed Agents session events, including agent.tool_use and agent.custom_tool_use, so helper code can operate across the core Messages surface and session event streaming surface. Sources: src/lib/tools/BetaRunnableTool.ts

BetaToolRunner then provides the automatic loop for assistant-tool interaction. It is an async iterable that yields beta messages or streams depending on configuration, clones message params to avoid accidental mutation, collects helper markers, attaches a BetaToolRunner helper header, tracks iteration count, and coordinates completion promises. In an environment-backed session, this distinction helps decide what belongs in the sandbox and what belongs in the client process: server-side tools run as platform capabilities, while runnable tools with run, parse, and optional close hooks are executed by SDK helper code. Sources: src/lib/tools/BetaToolRunner.ts, src/lib/tools/BetaRunnableTool.ts

API Reference Notes

The visible generated resource methods for the Managed Agents agent layer are client.beta.agents.create(params, options?), client.beta.agents.retrieve(agentID, params?, options?), client.beta.agents.update(agentID, params, options?), client.beta.agents.list(params?, options?), client.beta.agents.archive(agentID, params?, options?), and client.beta.agents.versions.list(agentID, params?, options?). List methods return cursor-paginated page promises, and all these methods accept optional beta header params through a betas field. Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts

Use the official environment API shape for the environment-specific part of the workflow: create a cloud environment with name and config, then pass its ID into the session-starting flow documented for Managed Agents sessions. Treat work acknowledgement endpoints as worker-facing self-hosted infrastructure endpoints, not as normal application calls. For cloud environments, the concrete next step is to pair this page with the Managed Agent Sessions page, then review Deployments and Scheduled Runs if the sandbox should run on a schedule or outside an interactive session.