自托管沙箱

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

工具执行保留在您的主机上：代理读写的文件系统、它生成的进程以及它可以访问的网络都在您的控制之下。工具输入和输出仍会流向 Anthropic 的控制平面（Claude 运行的地方），以便模型可以看到结果并确定下一步要做什么。请参阅安全模型了解完整的数据流边界。



与云环境的区别

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

有关零数据保留和 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 可以直接或通过 MCP 隧道访问的 HTTP 端点。要使用只有您的网络可以访问的服务器，请改为让 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 个字符）；描述是必需的（1–4,096 个字符）；代理的 tools 数组最多接受 128 个条目（每个包装的工具是一个条目，内置工具集再占一个）。API 会拒绝重复使用工具名称、以内置代理工具（如 bash 或 read）命名自定义工具，或使用保留的 mcp__ 前缀的声明。MCP 辅助工具会保留服务器的名称和描述，因此请根据需要重命名或裁剪。当两个服务器公开相同的工具名称时，请自行在带前缀的名称下定义包装器，并让它调用服务器的原始工具名称。
• **大多数模式可以原样通过。**API 接受 MCP 服务器通常发出的 JSON Schema 关键字，例如 additionalProperties 和 title。它拒绝自定义工具的 input_schema 中任何位置的引用关键字（如 $ref），因此请将 pydantic 等生成器分解到 $defs 中的模式内联化。它还拒绝顶层的 oneOf、anyOf 和 allOf，以及字母、数字、下划线、点和连字符之外的属性名称（1–64 个字符）。
• **工具失败会以错误工具结果的形式呈现。**当 MCP 服务器报告工具错误时，worker 会发布一个模型可以响应的错误工具结果。没有工具结果等价物的 MCP 内容（例如音频块和资源链接）也会以错误的形式呈现。在 MCP 客户端上设置超时以获得更快、更清晰的失败，就像 Python worker 示例使用 read_timeout_seconds 所做的那样。如果没有超时，挂起的调用只有在 TypeScript MCP SDK 的默认请求超时触发时（约一分钟）或 worker 自身的后备机制触发时才会变成错误结果：Python 中约为两分半钟，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 请求处理特定会话的 worker 将其关闭。默认情况下，工作项会进入 stopping 状态：worker 在下一次租约心跳时注意到这一点，取消该会话正在进行的工具调用，并确认关闭，此时工作项变为 stopped。在请求体中传递 force: true（使用 CLI 时，传递 --force）可立即将工作项标记为 stopped，而无需等待 worker 的确认。

由于这些调用是从您的运维工具而非 worker 主机运行的，ANTHROPIC_WORK_ID 不会自动设置。在运行以下示例之前，请将其设置为目标工作项的 ID。要查找工作项的 ID，请通过 Environments Work 端点列出环境的工作项。

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)



后续步骤