自托管 worker 参考
自托管沙箱 worker 的参考文档：ant CLI 标志、环境变量、主机要求、文件系统路径以及 SDK 辅助工具选项。
本页记录了为 self_hosted 环境提供服务的预构建 worker。如需面向任务的指南，请从自托管沙箱和部署自托管 worker 开始。
CLI 命令和标志
| 命令 | 描述 |
|---|---|
ant beta:worker poll | 从环境的队列中认领工作项，并在进程内运行每个会话。使用 --on-work 时，改为针对每个工作项调用您的脚本。 |
ant beta:worker run | 处理一个已认领的会话后退出。将其用作每会话沙箱的入口点。 |
| 标志 | 描述 |
|---|---|
--environment-id | 要轮询工作的环境。也会从 ANTHROPIC_ENVIRONMENT_ID 读取。 |
--environment-key | 使用此环境对 worker 进行身份验证。也会从 ANTHROPIC_ENVIRONMENT_KEY 读取。 |
--workdir | 下载技能以及工具读写文件的目录。默认为 .（当前目录）。 |
--on-work | 针对每个已认领工作项调用的脚本，用于替代在进程内运行工具。该脚本通过环境变量接收会话详细信息，并通过标准输入以 JSON 形式接收工作项。 |
--max-idle | 会话以 end_turn 停止原因进入空闲状态后，在关闭前等待的时长。默认为 60s。 |
--log-format | 日志输出格式。使用 json 以便进行结构化日志采集。默认为 text。 |
环境变量
| 变量 | 描述 | 设置方 |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | worker 所服务队列对应的环境。 | 您，在 worker 主机上设置。轮询器会将其传递给 --on-work 脚本。 |
ANTHROPIC_ENVIRONMENT_KEY | 向其队列验证 worker 的身份。 | 您，在 worker 主机上设置。轮询器会将其传递给 --on-work 脚本。 |
ANTHROPIC_SESSION_ID | 已认领工作项所代表的会话。 | 轮询器，为 --on-work 脚本设置。 |
ANTHROPIC_WORK_ID | 已认领的工作项。 | 轮询器，为 --on-work 脚本设置。 |
ANTHROPIC_WORK_SECRET | 工作项的每会话 secret。 | 您。轮询器不会设置它。请参阅转发工作项的 secret。 |
ANTHROPIC_BASE_URL | 覆盖默认的 API 端点。可选。 | 您，在 worker 主机上设置。 |
ANTHROPIC_WEBHOOK_SIGNING_KEY | 验证传入的 webhook 负载。 | 您，在 webhook 处理程序主机上设置。 |
主机要求
| Worker | 要求 |
|---|---|
| 所有 worker | 一台 Linux 主机，且 /bin/bash 位于该确切路径。worker 的 bash 工具会直接调用它，而不查询 PATH。 |
| TypeScript SDK | PATH 上有 unzip 和 tar，以及 Node.js 22 或更高版本。 |
| Python 和 Go SDK | 无需额外的二进制文件。这些 SDK 使用其标准库进行归档解压。 |
记忆存储有其自身的额外要求。
沙箱文件系统
| 路径 | 内容 |
|---|---|
/workspace | 用于工具执行和技能下载的系统默认工作目录。如果您使用不同的工作目录，请更新智能体的系统提示，以便 Claude 能够找到技能文件。 |
<workdir>/skills/<name>/ | 智能体已下载的技能。 |
/mnt/memory/<store>/ | 每个附加的记忆存储对应一个目录，位于该存储的 mount_path（例如 /mnt/memory/user-preferences/）。worker 在认领会话时创建这些目录，并在会话结束时删除它们。 |
在自托管环境中，会话的系统提示会省略 Anthropic 托管沙箱上使用的 /mnt/session/outputs 指令。最终交付物会落在智能体在您的沙箱文件系统中写入的任何位置，通常位于工作目录下。
技能可以包含智能体可直接运行的可执行文件。CLI 和 SDK worker 在解压技能包时会保留其中记录的可执行权限。如果您手动实现技能下载，则需要自行负责设置可执行权限。
SDK 辅助工具
Python、TypeScript 和 Go SDK 提供了三个不同控制级别的辅助工具：
| 辅助工具 | 功能 | 适用场景 |
|---|---|---|
EnvironmentWorker | 端到端处理轮询、设置和执行。 | 大多数情况。 |
work.poller() | 轮询工作队列，并将每个已认领的会话交给您。 | 您需要决定每个会话的处理方式，例如启动沙箱而不是在进程内运行工具。 |
client.beta.sessions.events.tool_runner() | 在给定会话 ID 和工具列表的情况下，为单个会话运行工具调用。 | 您已经认领了工作，只需要执行层。 |
EnvironmentWorker
| 方法 | 描述 |
|---|---|
run() | 无限期运行，在会话到达时接收它们。 |
handle_item() | 处理单个已认领的工作项后返回。可以显式传入工作、会话和环境标识符以及 work_secret，也可以让它读取 ANTHROPIC_* 变量。 |
| 选项 | 描述 |
|---|---|
tools | 一个工厂函数，接收会话的 AgentToolContext 并返回工具列表。默认为标准智能体工具集。 |
memory_sync_interval | 会话运行期间，附加的记忆存储与服务器进行协调的频率。请参阅同步间隔。 |
memory_sync_deletions | 智能体在本地删除的文件是否也从存储中删除。请参阅删除。 |
EnvironmentWorker 会自动管理 AgentToolContext 和工具集。传入 tools 工厂函数即可自定义工具列表：
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])工作轮询器
| 选项 | 描述 |
|---|---|
drain | 队列为空时是否停止轮询，而不是等待新工作。 |
block_ms | 每次轮询在返回前等待工作到达的时长，以毫秒为单位。必须介于 1 到 999 之间；辅助工具会自动重新轮询。传入 None 可进行非阻塞检查。默认为 999 毫秒的长轮询。 |
reclaim_older_than_ms | 重新认领那些已被认领但在此毫秒数内从未被确认的工作项。 |
auto_stop | 在您的循环体处理完每个工作项后，是否为其发送停止信号。当运行该工作项的程序会自行发送停止信号时，请将其设置为 False。handle_item() 会这样做，由您启动且负责停止调用的沙箱也会这样做。 |
如需完整示例，请参阅从 SDK 轮询器启动沙箱。
会话工具运行器
client.beta.sessions.events.tool_runner() 以 tools 的形式接收工具列表。要构建该列表，请自行设置 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)AgentToolContext 和智能体工具集
AgentToolContext 是工具调用的执行上下文。它定义了工作目录和路径策略，并且可以下载会话的技能。
| 选项 | 描述 |
|---|---|
allowed_roots | 除工作目录之外，文件工具（read、write、edit、glob、grep）可以访问的目录。 |
read_only_roots | write 和 edit 会拒绝其下路径的目录。 |
EnvironmentWorker 会自行将会话的记忆存储目录添加到 allowed_roots，并将以 access: "read_only" 附加的存储目录添加到 read_only_roots。
这种限制仅是针对文件工具的防护措施，而不是沙箱。它不会约束 bash。
beta_agent_toolset_20260401(env) 接收一个 AgentToolContext，并返回标准工具实现（bash、read、write、edit、glob、grep）。
Was this page helpful?