Skip to main content
Connect Claude Managed Agents to a worker running in a CoreWeave sandbox. Anthropic manages the agent loop and conversation. The worker executes tools and returns their results to Anthropic. This integration uses a self-hosted environment and is separate from the Claude Code CLI and Remote Control. Claude Managed Agents is also in beta. Its API requires the managed-agents-2026-04-01 beta header. The Anthropic SDK used in this guide adds it automatically. See Anthropic beta access.

Prerequisites

Before you begin, you need the following:
  • W&B APIキー。以下のサンプルでは W&B 認証を使用します。
  • Anthropic のワークスペースで Claude Managed Agents を利用できること、およびセッションを作成するクライアント用の Console APIキー。
  • agent_toolset_20260401 を設定済みの既存のエージェント。Anthropic の Managed Agents クイックスタート に従ってエージェントを作成し、その ID を控えておいてください。
  • SDK のサンプルを使用する場合は、Python 3.11 以降と uv、または Node.js 22 以降。
このガイドの手順を実行するターミナルで、W&B APIキーをエクスポートします。cws-agent が W&B 認証を選択するよう、CoreWeave トークンが設定されている場合はすべて解除してください。

Create an environment

In the Claude Console, create a Self-hosted environment. Open it and generate an environment key. Record the environment ID and store the key securely. See Anthropic’s environment setup. The environment key authenticates workers to this environment. The Console API key creates sessions from your client. Keep the two credentials separate. For the verification task, use an environment with only the worker created in this guide. That prevents another worker from claiming the test session. With the environment ready, choose either cws-agent or the Sandbox SDK to start its worker, then run the verification task.

Quick start with cws-agent

cws-agent のインストール手順に従ってください。このツールは、ファイルシステムスナップショットによるワークスペースの保存とリストアに使用するスナップショットボリュームを設定します。 Replace [ENVIRONMENT-KEY], [ENVIRONMENT-ID], and [SANDBOX-NAME] with your environment key, environment ID, and a cws-agent session name for the sandbox. For the session name, use 1 to 40 lowercase letters, digits, or hyphens, starting with a letter or digit:
Launch starts one worker in /workspace/claude/0 and returns to your shell. The tool passes the environment key into the sandbox. To view the worker’s terminal, run:
Detach with Ctrl-b, then d. Continue to Run and verify a task. Send tasks through the Managed Agents API. The cws-agent run command doesn’t drive Managed Agents conversations.

Set up with the Sandbox SDK

This alternative starts Anthropic’s ant worker as the sandbox’s main process. It doesn’t require cws-agent or configure snapshots. Run Python snippets in the virtual environment created in this guide. Save TypeScript snippets as .mts files in the project where you install the client, then run them with npx tsx [FILENAME].mts.

Configure credentials and install the client

Export the environment key and ID from the Console in the terminal where you run the script:
Python 3.11 以降と uv を使用します。

Start the worker

Save the script for your language using the filename shown. The script installs the ant CLI in a Linux image with Bash, starts one worker, and prints the sandbox ID. The client reads ANTHROPIC_ENVIRONMENT_KEY from your local environment and passes its value in the sandbox request to set the worker’s environment variable.
start_claude_worker.py
Run the script:
The script waits for startup. In Python, wait() can also return if the main process has already completed. A printed sandbox ID doesn’t confirm that the worker is authenticated or polling. Before starting a task, inspect its status and recent logs. Replace [SANDBOX-ID] with the printed ID:
The Python client also reports per-container state, exit codes, and restart counts. The TypeScript client doesn’t expose those details yet. Rerun this check to fetch newer logs. This worker polls over outbound HTTPS. It doesn’t require an inbound service. Each session uses the same sandbox filesystem, so this example doesn’t provide a fresh sandbox per session. For that architecture, see Anthropic’s self-hosted sandbox integration guide.

オプション: シークレットストアを使用する

環境キーの値の代わりに、W&B シークレット参照を渡すこともできます。SDK のサンプルでは、W&B 認証がすでに選択されています。環境キーを W&B チームの Secret Manager に保存し、そのチームがデフォルトの entity でない場合は、WANDB_ENTITY でそのチームを指定してください。 [SECRET-NAME] をチームのシークレット名に置き換えます。
cwsandbox から Secret をインポートし、environment_variables から ANTHROPIC_ENVIRONMENT_KEY を削除して、Sandbox.run() に secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")] を追加します。
参照はプラットフォームによって解決され、ワーカーの環境変数に設定されます。

Run and verify a task

Run the session client on your own machine for either setup path. Install the Anthropic SDK for your language:
Replace [ANTHROPIC-API-KEY] with your Console API key, [AGENT-ID] with your existing agent ID, and [ENVIRONMENT-ID] with the environment connected to your worker:
Save the verification script for your language using the filename shown. It asks the agent to write a unique, non-secret value in its working directory. Self-hosted tool execution produces temporary idle events while the worker handles allowed calls. The script waits through those events and stops when the turn ends or another action is required. Inspect the printed stop reason before retrieving the file.
verify_claude_worker.py
Run it and inspect the events:
If the script stops with requires_action, inspect the referenced tool events. Calls with evaluated_permission: "ask" need Anthropic’s tool-confirmation workflow. The worker handles allowed calls. If they stall, inspect its logs. Keep the session ID to continue that session rather than creating another one. After the task completes, read the file from the sandbox with the command for your setup. Replace [SANDBOX-NAME] or [SANDBOX-ID] with the workspace name or printed sandbox ID:
For Python, reactivate the virtual environment where you installed cwsandbox if needed. For TypeScript, save the SDK snippet as an .mts file and run it with npx tsx. The file must match the value printed by the client. This ties the agent’s tool execution to the specific CoreWeave sandbox.

Keep results and stop

Wait for active tasks to finish and copy any results you need out of the sandbox. Then stop it using the command for your setup:
down は停止前にワークスペースのスナップショットを作成します。スナップショットの取得に失敗した場合は、cws-agent status [SANDBOX-NAME] で状態を確認し、問題を解決してから再試行してください。未保存の変更を破棄してもかまわない場合は、down --no-snapshot を使用します。
The sandbox’s lifetime can terminate a task in progress. Ending a Managed Agents session doesn’t stop this always-on worker. Stopping or restoring the sandbox also doesn’t delete or restore Anthropic’s conversation history.

Troubleshoot

Use these checks to resolve common issues:
  • If the session waits for a worker, check the environment ID, the worker logs, and whether another task already occupies the worker.
  • If the worker can’t authenticate, check its environment key. The Console API key used by the session client is a different credential.
  • If a tool is missing, build an image with the required dependencies. The example uses a Python image and doesn’t install a project-specific toolchain.
Tool inputs and outputs flow to Anthropic even though execution happens on CoreWeave. Managed Agents isn’t eligible for Zero Data Retention or HIPAA Business Associate Agreement coverage. See Anthropic’s data-retention eligibility. Review the self-hosted environment security model for data handling and worker permissions.
最終更新日 2026年9月30日