自托管沙箱

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

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



与云环境的区别

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

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



何时与 MCP 隧道结合使用

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



环境 worker

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

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

CLI 和 SDK 都附带了预构建的 worker。ant CLI 仅支持常驻模式；SDK 同时支持常驻和 webhook 触发两种模式。两者均可配置：有关 CLI 标志，请参阅参考文档中的自托管 worker；有关 SDK 选项，请参阅本页的 SDK 辅助工具。如需更多控制，可直接调用 Environments Work 端点并实现您自己的 worker。



沙箱文件系统

• /workspace： 工具执行和技能下载的系统默认工作目录。CLI 的 --workdir 标志默认为当前目录；传递 --workdir /workspace 以匹配系统默认值。技能会下载到 <workdir>/skills/<name>/。如果您使用不同的工作目录，请更新智能体的系统提示，以便 Claude 能够找到技能文件。
• 输出： 在自托管环境中，会话的系统提示会省略 Anthropic 托管沙箱上使用的 /mnt/session/outputs 指令，因此最终交付物会落在智能体在您的沙箱文件系统中写入的任何位置，通常在工作目录下。



开始之前

您需要：

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



运行 worker

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



SDK 辅助工具

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

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

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

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 已下载到 /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



验证 worker 已连接

在另一个 shell 中，将 ANTHROPIC_API_KEY 设置为您的 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 运行后，创建一个指向该环境的会话。将 AGENT_ID 设置为您在开始之前中记下的智能体 ID。会话进入环境的工作队列并在那里等待，直到有 worker 认领它；如果没有 worker 连接，会话会保持排队状态而不会失败。

Anthropic 不会将文件或 GitHub 仓库挂载到自托管沙箱中。要使会话特定的文件可用，请在会话的 metadata 字段中传递文件引用（例如 S3 路径或提交 SHA）。已认领的工作项不携带会话的元数据，但携带会话 ID：您的派生脚本或 --on-work 处理程序检索会话（GET /v1/sessions/{session_id}）以读取 metadata 字段，然后在工具执行开始之前将文件暂存到工作目录中。

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

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



从您的沙箱提供自定义工具

自定义工具是由您自己的代码执行的工具：智能体发出 agent.custom_tool_use 事件并等待匹配的 user.custom_tool_result。worker 可以充当该代码，并且由于它在您的沙箱内运行，该工具可以访问您为沙箱配置的内部服务、凭据和网络出口，仅此而已。环境密钥授权发布自定义工具结果，因此您的 Claude API 密钥无需存放在 worker 主机上。

worker 只响应向其注册的工具。如果某个自定义工具在智能体上声明了但未向任何 worker 或客户端注册，会话将以 requires_action 停止原因暂停，直到有某个组件发布其结果；有关事件流程，请参阅处理自定义工具调用。



将 MCP 服务器封装为自定义工具

MCP 连接器从 Anthropic 一侧连接到 MCP 服务器，因此服务器必须暴露一个 Anthropic 可以访问的 HTTP 端点，无论是直接访问还是通过 MCP 隧道。要使用只有您的网络可以访问的服务器，请让 worker 充当 MCP 客户端，并将服务器的工具声明为自定义工具。MCP 服务器不需要来自您网络外部的入站连接；Anthropic 接收您在智能体上声明的工具定义、每次调用的输入以及您的 worker 回传的结果。在运行时，模型像调用任何其他自定义工具一样调用封装的工具：

1. 智能体发出 agent.custom_tool_use 事件。
2. worker 在您的沙箱内，通过其与您网络上服务器之间已打开的 MCP 会话转发该调用。
3. worker 将服务器的响应作为 user.custom_tool_result 发布。

SDK 的客户端 MCP 辅助工具将服务器的工具转换为 worker 接受的可运行工具；请在 Anthropic SDK 之外安装 MCP SDK（pip install "anthropic[mcp]" "mcp>=1.24"、npm install @modelcontextprotocol/sdk、go get github.com/modelcontextprotocol/go-sdk）。示例在不进行身份验证的情况下连接；要发送凭据，请配置您传递给 MCP 传输层的 HTTP 客户端或请求选项（Python 中为 http_client，TypeScript 中为 requestInit，Go 中为 HTTPClient）。

封装 MCP 服务器时，请注意以下几点：

• 工具是声明的，而非在运行时发现的。 worker 在启动时列出 MCP 服务器的工具一次，无法向正在运行的会话添加工具。当服务器的工具发生变化时，请重新声明它们——在智能体上声明，或通过更新智能体配置在空闲会话上声明——然后重启 worker。
• 名称和描述必须符合 Managed Agents API 的要求。 自定义工具名称在每个智能体中是唯一的，使用字母、数字、下划线和连字符（1–128 个字符）；描述必须非空；智能体的 tools 数组最多包含 128 个条目（每个封装的工具是一个条目，内置工具集是另一个条目）。API 会拒绝重复使用工具名称的声明、以内置智能体工具（如 bash 或 read）命名自定义工具的声明，或使用保留的 mcp__ 前缀的声明。MCP 辅助工具保留服务器的名称和描述，因此请在需要时重命名或裁剪。当两个服务器暴露相同的工具名称时，请自行以带前缀的名称定义封装器，并让它调用服务器的原始工具名称。
• 大多数 schema 可原样传递。 API 接受 MCP 服务器常用的 JSON Schema 关键字，例如 additionalProperties 和 title。它拒绝自定义工具 input_schema 中任何位置的引用关键字（如 $ref），因此请内联那些由 pydantic 等生成器提取到 $defs 中的 schema。它还拒绝顶层的 oneOf、anyOf 和 allOf，以及超出字母、数字、下划线、点和连字符范围的属性名称（1–64 个字符）。
• 工具失败以错误工具结果的形式呈现。 当 MCP 服务器报告工具错误时，worker 会发布一个模型可以响应的错误工具结果。没有对应工具结果的 MCP 内容（如音频块和资源链接）也会以错误形式呈现。在 MCP 客户端上设置超时以获得更快、更清晰的失败反馈，如 Python worker 示例中使用 read_timeout_seconds 所示。如果没有设置超时，挂起的调用只有在 TypeScript MCP SDK 的默认请求超时触发（约一分钟）或 worker 自身的后备机制触发时才会变成错误结果：Python 中约为两分半钟，Go 中为两分钟——Go worker 会取消超过其 120 秒默认值的工具调用并发布错误结果。
• 封装您运营或信任的服务器。 封装工具的名称、描述和结果会像任何其他工具一样进入模型的上下文：这是不受信任的输入，可能影响智能体使用其他工具（包括 worker 主机上的 bash）的方式。仅声明您打算让智能体使用的工具。
• 权限策略不适用于自定义工具。 权限策略管理内置和 MCP 工具集；worker 会执行模型发出的每个封装工具调用，因此请在您自己的工具代码中加入任何审批步骤。



监控和运维

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



读取队列深度

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

• depth 是等待被认领的项目数量。根据此值扩展您的 worker 集群或对积压发出警报。
• pending 是已被 worker 认领但尚未确认的项目数量。worker 辅助工具在处理每个项目之前会先确认它，因此在正常运行中此值保持接近零；持续的非零值意味着某个 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 请求处理特定会话的工作进程将其关闭。默认情况下，工作项会进入 stopping 状态：工作进程在下一次租约心跳时会注意到这一变化，取消该会话正在进行的工具调用，并确认关闭，此时工作项变为 stopped 状态。在请求正文中传递 force: true（使用 CLI 时传递 --force），可立即将工作项标记为 stopped，而无需等待工作进程的确认。

由于这些调用是从您的运维工具而非工作进程主机发起的，因此 ANTHROPIC_WORK_ID 不会被自动设置。在运行以下示例之前，请将其设置为目标工作项的 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)



后续步骤