Claude Platform Docs
Managed Agents自托管沙箱

部署自托管 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 支持不同的组合:

功能ant CLISDK(Python、TypeScript、Go)
常驻轮询是是
Webhook 触发否是
每个会话一个沙箱是是
记忆存储是,使用默认同步设置是,同步可配置
自定义工具否是

有关每个 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

  1. 订阅会话 webhook

    在 Claude Console 中,定义一个监听 session.status_run_started 事件的 webhook 端点。详情请参阅订阅 webhook。

  2. 导出 webhook 签名密钥

    除了运行您的第一个会话中的环境 ID 和密钥外,还要在处理程序主机上导出 webhook 签名密钥。处理程序使用它来验证传入的负载。

    export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
  3. 实现 webhook 处理程序

    在 session.status_run_started 触发时启动工作进程。处理程序会清空队列,并将每个认领的工作项交给 handle_item()(在 Python、TypeScript 和 Go SDK 中)。该方法会下载技能、运行工具调用、回传结果,然后返回。

    这些示例使用 /workspace 作为工作目录。在启动处理程序之前,请在处理程序主机上创建该目录。确保处理程序的用户可以写入该目录,如运行您的第一个会话中的“启动 worker”步骤所示。

    要验证 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,并修复常见故障。

自托管沙箱环境的责任共担模型。

可用性

预构建的自托管 worker
预构建的自托管 worker在所有支持的平台上的可用性要求相同。
状态
Beta
API
  • Managed Agents
Beta 请求头
需要
模型
  • 所有模型

适用的端点

  • /v1/agents
  • /v1/sessions
  • /v1/environments
零数据保留不具备资格

不具备 ZDR 资格,自托管 Managed Agents 除外。会话是有状态的资源;对话记录会一直保留,直到您将其删除。 了解更多

HIPAA不具备资格

不具备 HIPAA 资格。适用于所有 Managed Agents 子功能。

此页面对您有帮助吗?