自托管沙箱

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

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



与云环境的区别

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

有关零数据保留和 HIPAA BAA 资格，请参阅 API 和数据保留。



何时与 MCP 隧道结合使用

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



环境工作进程

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

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

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



沙箱文件系统

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



开始之前

您需要：

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



运行工作进程

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



SDK 辅助工具

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

• EnvironmentWorker： 开箱即用的工作进程。端到端处理轮询、设置和执行。
  • .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)



验证工作进程已连接

在另一个 shell 中，将 ANTHROPIC_API_KEY 设置为您的 Claude API 密钥（而不是环境密钥），确认 workers_polling 至少为 1：

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

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



启动会话

工作进程运行后，创建一个以该环境为目标的会话。将 AGENT_ID 设置为您在开始之前中记下的代理 ID。会话进入环境的工作队列并在那里等待，直到有工作进程认领它；如果没有工作进程连接，会话会保持排队状态而不是失败。

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

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

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



监控和运维

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



读取队列深度

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

• depth 是等待被认领的项目数量。根据此值扩展您的工作进程集群或对积压发出警报。
• pending 是工作进程已认领且当前正在处理的项目数量。
• oldest_queued_at 是仍在排队或正在处理的最旧项目的时间戳，如果没有则为 null。
• workers_polling 是在过去 30 秒内进行过轮询的工作进程数量。将此用于存活性警报。

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 要求处理特定会话的工作进程干净地关闭它。工作进程会完成任何正在进行的工具调用，发布最终状态，并释放会话。在请求体中传递 force: true（使用 CLI 时传递 --force）以立即中断，而不是等待当前工具调用完成。

由于这些调用是从您的运维工具而不是工作进程主机运行的，因此 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)



后续步骤