自托管沙箱

默认情况下，Managed Agents 在 Anthropic 托管的云沙箱中执行工具和代码。自托管沙箱将编排保留在 Anthropic 一侧，但将工具执行转移到您控制的基础设施中，因此智能体的代码、文件系统和网络出口流量永远不会离开您的环境。

工具执行保留在您的主机上：智能体读写的文件系统、它生成的进程以及它可以访问的网络都在您的控制之下。工具的输入和输出仍会流向 Anthropic 的控制平面（Claude 在此运行），以便模型能够查看结果并决定下一步操作。有关完整的数据流边界，请参阅安全模型。

与云环境的区别

当智能体需要操作不能离开您网络边界的数据、访问无法公开路由的内部服务，或在您组织自己的合规和审计控制下运行时，自托管是一个很好的选择。

有关 Zero Data Retention（零数据保留）和 HIPAA BAA 资格，请参阅 API 和数据保留。

何时与 MCP 隧道结合使用

自托管控制的是智能体代码的执行位置。MCP 隧道控制的是 Anthropic 如何访问您网络中的 MCP 服务器。两者相互独立：在 Anthropic 云沙箱中运行的会话仍可通过隧道访问私有 MCP 服务器，而自托管会话可以使用隧道式或公共 MCP 服务器。当您希望执行和工具访问都保留在您的边界内时，请同时使用两者。

环境 worker

环境 worker 是您在自己的基础设施上运行的进程。它接收来自 Anthropic 的工具执行请求并在本地运行。self_hosted 环境充当工作队列：当一个会话被分配到该环境时，Anthropic 会将该会话作为工作项加入队列。您的 worker 从该队列中认领工作项，为每个工作项生成一个执行上下文，下载智能体的 skills（技能，即可复用的、基于文件系统的资源，为智能体提供特定领域的专业能力），运行工具调用，并将结果回传。

工作项通过轮询环境的队列来认领：可以通过持续轮询的常驻 worker，也可以通过在 session.status_run_started 事件触发时唤醒并开始轮询的 webhook 触发式处理程序。

CLI 和 SDK 都附带了预构建的 worker。ant CLI 仅支持常驻模式；SDK 同时支持常驻和 webhook 触发两种模式。两者均可配置：有关 CLI 标志，请参阅参考文档中的自托管 worker；有关 SDK 选项，请参阅本页的 SDK 辅助工具。如需更多控制，可直接调用 Environments Work 端点并实现您自己的 worker。在 Claude Platform on AWS 上，GET /v1/environments/{id}/work 列表端点及其 SDK 等效方法目前不可用；其他 work 端点（poll、ack、heartbeat、stop、post results、按项 get 和 stats）正常工作。

沙箱文件系统

• /workspace： 工具执行和技能下载的系统默认工作目录。CLI 的 --workdir 标志默认为当前目录；传递 --workdir /workspace 以匹配系统默认值。技能会下载到 <workdir>/skills/<name>/。如果您使用不同的工作目录，请更新智能体的系统提示，以便 Claude 能够找到技能文件。
• /mnt/session/outputs： worker 框架会指示 Claude 将最终交付物写入此处。在沙箱模式下，将主机目录挂载到此路径，以便在会话结束后检索输出。在进程内模式下，worker 的文件工具会写入工作目录下，因此此路径不适用。

开始之前

您需要：

• 一个现有的智能体。 如果您还没有，请先完成快速入门并记下其智能体 ID。
• 一台 Linux 主机，且 /bin/bash 位于该确切路径。TypeScript SDK 还需要 unzip、tar 和 Node.js 22 或更高版本；Python SDK 使用标准库进行归档提取，没有额外的二进制依赖要求。这些依赖项在固定路径解析，不遵循 PATH 覆盖。
• 在 worker 主机上安装 ant CLI 或 Anthropic SDK（Python、TypeScript 或 Go）。
• 两个凭据： 环境密钥（在后续步骤中生成）用于向队列验证 worker 的身份；您的 Claude API 密钥用于从 worker 主机外部创建会话和读取队列统计信息。

运行 worker

选择常驻模式以获得最简单的设置：一个长期运行的进程持续轮询队列，只需要出站 HTTPS。选择 webhook 触发模式可避免运行空闲的轮询器；它需要一个 Anthropic 可以访问的 webhook 端点（有关端点设置和签名验证，请参阅 Webhooks）。

SDK 辅助工具

SDK 提供了三个不同控制级别的辅助工具。EnvironmentWorker 涵盖了大多数用例；当您需要启动自己的按会话进程或针对已认领的会话运行工具时，可使用较低级别的辅助工具。

• EnvironmentWorker： 开箱即用的 worker。端到端处理轮询、设置和执行。
  • .run()：无限期运行，在会话到达时拾取它们。收到 SIGTERM 时正常退出。
  • .handle_item()：拾取一个待处理的会话，处理它，然后退出。
• work.poller()： 代表您轮询工作队列，并将每个已认领的会话交给您。当您希望决定每个会话的处理方式时使用此方法，例如启动沙箱而不是在进程内运行工具。
  • drain：是否在队列为空时停止轮询，而不是等待新工作。
  • block_ms：等待工作到达的时长（毫秒），超时后返回。必须介于 1 到 999 之间（单次轮询等待时长；辅助工具会自动重新轮询）。传递 null（Python 中为 None，Go 中为 param.Null[int64]()）进行非阻塞检查；省略该参数则使用默认的 999 毫秒长轮询。
  • reclaim_older_than_ms：重新认领已租给停止响应的 worker 的工作项。
  • auto_stop：迭代器退出后是否在工作项上发布停止信号。Go 轮询器没有退出选项，始终会发布停止信号，因此请在循环体中阻塞直到会话完成，而不是分离。
• client.beta.sessions.events.tool_runner()： 给定会话 ID 和工具列表，为单个会话运行工具调用。当您已经认领了工作并且只需要执行层时使用。

当您希望启动自己的按会话进程时（例如为每个已认领的会话启动一个沙箱），请直接使用 work 轮询器：

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # 替换为您自己的每会话沙箱启动器。将
    # ANTHROPIC_ENVIRONMENT_KEY 传入启动的沙箱，切勿传入
    # 您的 API 密钥。
    print(f"claimed session {work.data.id}")


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

AgentToolContext 是工具调用的执行上下文。它定义了工作目录和路径策略，并且在用作上下文管理器时可选择性地下载会话的技能。beta_agent_toolset_20260401(env) 接受一个 AgentToolContext 并返回标准工具实现（bash、read、write、edit、glob、grep）。

使用 EnvironmentWorker 时： 两者都会自动管理。传递 tools 工厂函数以自定义工具列表：

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

使用 work.poller() 和 tool_runner() 时： 将工具列表作为 tools 传递给 client.beta.sessions.events.tool_runner()。要构建该列表，请自行设置 AgentToolContext 并调用 beta_agent_toolset_20260401(env)：

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

验证 worker 已连接

在另一个 shell 中，使用您的 Claude API 密钥（而非环境密钥），确认 workers_polling 至少为 1：

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

如果 workers_polling 保持为 0，则表示 worker 未连接到队列：请确认 worker 主机上已设置 ANTHROPIC_ENVIRONMENT_KEY 和 ANTHROPIC_ENVIRONMENT_ID。有关完整的统计响应和其他语言示例，请参阅读取队列深度。

启动会话

worker 运行后，创建一个指向该环境的会话。会话进入环境的工作队列并在那里等待，直到 worker 认领它；如果没有 worker 连接，会话会保持排队状态而不会失败。

Anthropic 不会将文件或 GitHub 仓库挂载到自托管沙箱中。要使会话特定的文件可用，请在会话的 metadata 字段中传递文件引用（例如 S3 路径或提交 SHA）。您的启动脚本或 --on-work 处理程序从已认领的工作项中读取该元数据（通过 Environments Work 端点），并在工具执行开始之前将文件暂存到工作目录中。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

有关 CLI 标志的完整列表，请参阅参考文档中的自托管 worker；有关 SDK 辅助工具选项，请参阅 SDK 辅助工具。

监控和运维

这些调用从您的监控或运维工具中运行，使用您的 Claude API 密钥进行身份验证，用于观察和管理 worker 集群。认领和保活循环在 worker 辅助工具内部处理，因此您无需直接调用这些端点。

读取队列深度

work.stats 返回环境的队列状态：

• depth 是等待被认领的项目数量。根据此值扩展您的 worker 集群或对积压情况发出告警。
• pending 是 worker 已认领且当前正在处理的项目数量。
• oldest_queued_at 是队列中最早项目的时间戳，如果队列为空则为 null。
• workers_polling 是过去 30 秒内进行过轮询的 worker 数量。使用此值进行存活告警。

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

优雅地停止会话

使用 work.stop 请求处理特定会话的 worker 将其正常关闭。worker 会完成任何正在进行的工具调用，发布最终状态，然后释放会话。在请求体中传递 force: true 可立即中断，而不是等待当前工具调用完成。

由于这些调用是从您的运维工具而非 worker 主机运行的，因此 ANTHROPIC_WORK_ID 不会自动设置。在运行以下示例之前，请将其设置为目标工作项的 ID。

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

后续步骤