部署自托管 worker
选择自托管沙箱 worker 如何认领工作以及会话在何处运行,然后运行常驻 worker 或通过 webhook 触发 worker。
自托管沙箱快速入门运行一个 ant CLI 工作进程,该进程持续轮询,并在一个进程中运行每个会话。本页帮助您选择部署模式,然后介绍常驻 worker 和由 webhook 触发的 worker。
选择部署模式
部署 worker 时,您需要做出两个选择:worker 如何认领工作,以及每个会话在何处运行。
worker 如何认领工作:
- 常驻运行: 一个长时间运行的进程持续轮询队列。该进程只发出出站 HTTPS 请求,因此您无需向 Anthropic 公开端点。
- Webhook 触发: 处理程序在
session.status_run_started时被唤醒并开始轮询。这避免了空闲的轮询器,但需要一个 Anthropic 可以访问的 webhook 端点。
每个会话在何处运行:
- 进程内: 认领会话的 worker 同时在一个共享工作目录中运行其工具调用。
- 每个会话一个沙箱: 轮询器为每个认领的会话启动一个全新的沙箱。如需更强的隔离,请选择此方式:全新的文件系统、资源限制或按会话的网络控制。请参阅每个会话运行一个沙箱,其中还介绍了适用于 Kubernetes 的 Helm chart。
CLI 和 SDK worker 支持不同的组合:
有关每个 CLI 标志和 SDK 选项,请参阅自托管 worker 参考。
如需更多控制,请直接调用环境工作端点并实现您自己的 worker。这样,您的 worker 需要完成 SDK worker 所做的工作。除其他事项外,它需要确认每个工作项、发送心跳,并下载智能体的技能。它只运行会话的权限策略所允许的工具调用。它将每个结果作为 user.tool_result 或 user.custom_tool_result 事件返回。最后,它停止该工作项。您可以参考 Python SDK、TypeScript SDK 或 Go SDK 中的 worker 源代码。
运行常驻 worker
这些示例使用 /workspace 作为 worker 的工作目录。该目录必须在 worker 启动前存在。在新主机上,请创建该目录并为 worker 的用户授予写入权限,如运行您的第一个会话中的“启动 worker”步骤所示。
在 macOS 上,mkdir 无法创建 /workspace,因为根卷是只读的。请改为创建 ~/workspace(如该步骤所示)。请使用 echo ~/workspace 输出的完整路径代替 /workspace,因为 SDK 不会展开 ~。
启动一个持续轮询队列的 worker。它使用快速入门中的环境密钥进行身份验证:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
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:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
)
task = asyncio.create_task(worker.run())
# 取消任务而非终止进程,可让 worker 停止其
# 正在处理的工作项,并在退出前上传已更改的记忆文件。
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())通过 webhook 触发 worker
订阅会话 webhook
在 Claude Console 中,定义一个监听
session.status_run_started事件的 webhook 端点。详情请参阅订阅 webhook。导出 webhook 签名密钥
除了运行您的第一个会话中的环境 ID 和密钥外,还要在处理程序主机上导出 webhook 签名密钥。处理程序使用它来验证传入的负载。
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."实现 webhook 处理程序
在
session.status_run_started触发时启动工作进程。处理程序会清空队列,并将每个认领的工作项交给handle_item()(在 Python、TypeScript 和 Go SDK 中)。该方法会下载技能、运行工具调用、回传结果,然后返回。这些示例使用
/workspace作为工作目录。在启动处理程序之前,请在处理程序主机上创建该目录。确保处理程序的用户可以写入该目录,如运行您的第一个会话中的“启动 worker”步骤所示。Python要验证 webhook 签名,请安装 webhooks 附加组件:
pip install "anthropic[webhooks]"。import asyncio import os import anthropic import standardwebhooks # installed by the anthropic[webhooks] extra environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] client = anthropic.AsyncAnthropic( auth_token=environment_key, ) # 由 shutdown() 取消,以便进行中的工作项能在进程退出前上传已更改的记忆文件并 # 删除其存储目录。 inflight: set[asyncio.Task[None]] = set() # 请在宿主的关闭钩子中 await 此方法,例如 ASGI lifespan 关闭阶段(FastAPI lifespan 中 # `yield` 之后的代码),uvicorn 会在收到 SIGTERM 时运行它。uvicorn 会先让未完成的请求 # 结束后再运行该钩子,因此请设置 --timeout-graceful-shutdown 以限制等待时间。 async def shutdown() -> None: for task in inflight: task.cancel() await asyncio.gather(*inflight, return_exceptions=True) async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]: try: event = client.beta.webhooks.unwrap(raw.decode(), headers=headers) except standardwebhooks.WebhookVerificationError: return {"error": "signature verification failed"}, 401 if event.data.type != "session.status_run_started": return {"status": "ignored"}, 200 task = asyncio.create_task(run_queued_work()) inflight.add(task) task.add_done_callback(inflight.discard) try: # 已屏蔽取消:投递中断或超时不得取消该工作项;只有 shutdown() 会取消。 await asyncio.shield(task) except asyncio.CancelledError: return {"status": "shutting down"}, 503 return {"status": "ok"}, 200 async def run_queued_work() -> None: async for work in client.beta.environments.work.poller( environment_id=environment_id, environment_key=environment_key, block_ms=None, reclaim_older_than_ms=2000, drain=True, auto_stop=False, ): await client.beta.environments.work.worker(workdir="/workspace").handle_item( work_id=work.id, environment_id=environment_id, session_id=work.data.id, environment_key=environment_key, # worker 凭借每个会话的密钥来挂载该会话的记忆存储。 work_secret=work.secret, )在 Python、TypeScript 和 Go SDK 中,
handle_item()需要工作项的机密来挂载记忆存储。使用run()轮询的 worker 已经持有该机密。此处理程序自行认领每个工作项,因此它通过work_secret参数传递该机密。请参阅转发工作项的机密。
此处理程序在一个进程中运行每个认领的工作项,并且会同时运行来自不同 webhook 投递的工作项。这些会话共享同一个文件系统,包括 /workspace 和 /mnt/memory。如果您的会话附加了同一个记忆存储,请参阅隔离共享同一存储的会话。
后续步骤
使用 Kubernetes 上的 Helm chart、启动脚本或 SDK 轮询器启动沙箱。
读取队列深度,干净地停止会话和 worker,并修复常见故障。
自托管沙箱环境的责任共担模型。
可用性
Claude API
- 状态
- Beta
- API
- Managed Agents
- Beta 请求头
- 需要
- 模型
- 所有模型
Claude Platform on AWS
- 状态
- Beta
- API
- Managed Agents
- Beta 请求头
- 需要
- 模型
- 所有模型
数据处理
数据处理概览适用的端点
/v1/agents/v1/sessions/v1/environments
不具备 ZDR 资格,自托管 Managed Agents 除外。会话是有状态的资源;对话记录会一直保留,直到您将其删除。 了解更多
不具备 HIPAA 资格。适用于所有 Managed Agents 子功能。
此页面对您有帮助吗?