managed-agents-2026-04-01 ベータヘッダーが必要です。このガイドで使用する Anthropic SDK は自動的にそれを追加します。Anthropic beta access を参照してください。
前提条件
始める前に、以下が必要です:SANDBOX_USERaction を持つ CoreWeave API アクセストークン。- Anthropic ワークスペースでの Claude Managed Agents アクセスと、セッションを作成するクライアント用の Console APIキー。
agent_toolset_20260401で設定された既存のエージェント。Anthropic の Managed Agents クイックスタート に従って作成し、その ID を記録してください。- SDK の例では、
uvを使用した Python 3.11 以降、または Node.js 22 以降のいずれか。
環境を作成する
Claude Console で セルフホスト 環境を作成します。環境を開いて環境キーを生成してください。環境 ID を記録し、キーを安全に保管します。Anthropic の 環境の設定 を参照してください。 環境キーはワーカーをこの環境に対して認証します。Console APIキーはクライアントからセッションを作成します。2 つの認証情報は分けて管理してください。 検証タスクでは、このガイドで作成したワーカーのみが所属する環境を使用してください。これにより、別のワーカーがテストセッションを引き受けるのを防げます。 環境が準備完了したら、cws-agent または Sandboxes SDK のいずれかを選択してワーカーを起動し、検証タスクを実行してください。
cws-agent のクイックスタート
cws-agent のインストール手順に従ってください。このツールは、ファイルシステムスナップショットでワークスペースを保存およびリストアするためのスナップショットボリュームを設定します。
[ENVIRONMENT-KEY]、[ENVIRONMENT-ID]、[SANDBOX-NAME] を、それぞれ環境キー、環境 ID、サンドボックスの cws-agent セッション名に置き換えてください。セッション名には、先頭を英字または数字とし、1~40 文字の小文字の英字、数字、ハイフンを使用してください:
/workspace/claude/0 でワーカーを 1 つ起動し、シェルに戻ります。ツールは環境キーをサンドボックスに渡します。
ワーカーのターミナルを表示するには、次を実行します。
cws-agent run コマンドは Managed Agents の会話を実行しません。
Sandboxes SDK で設定する
この代替方法では、Anthropic のant ワーカーをサンドボックスのメインプロセスとして起動します。cws-agent やスナップショットの設定は必要ありません。
このガイドで作成した仮想環境で Python スニペットを実行します。TypeScript スニペットは、クライアントをインストールした project に .mts ファイルとして保存し、npx tsx [FILENAME].mts で実行します。
認証情報を設定してクライアントをインストールする
Console で取得した環境キーと ID を、スクリプトを実行するターミナルでエクスポートします:- Python
- TypeScript
Python 3.11 以降と
uv を使用します:ワーカーを開始する
言語に応じたスクリプトを表示されているファイル名で保存してください。このスクリプトは、Bash を備えた Linux イメージにant CLI をインストールし、1 つのワーカーを開始して、サンドボックス ID を出力します。クライアントはローカルの環境から ANTHROPIC_ENVIRONMENT_KEY を読み取り、その値をサンドボックスリクエストに渡して、ワーカーの環境変数を設定します。
- Python
- TypeScript
start_claude_worker.py
- Python
- TypeScript
wait() はメインプロセスがすでに完了している場合にも返ることがあります。出力されたサンドボックス ID は、ワーカーが認証済みまたはポーリング中であることを確認するものではありません。タスクを開始する前に、そのステータスと最近のログを確認してください。[SANDBOX-ID] を出力された ID に置き換えてください:
- Python
- TypeScript
オプション: シークレットストアを使用する
環境キーの値の代わりに Forge シークレット参照 を渡すことができます。このオプションを使用するには、Forge 認証とサーバーレス配置が必要です。環境キーを Forge チームの Secret Manager に保存してから、そのチームの認証情報をエクスポートしてください:FORGE_API_KEY と FORGE_TEAM は説明用の環境変数名であるため、SDK はこれらを自動的には検出しません。
- Python
- TypeScript
サンドボックスを作成する前に、
AuthHeaders をインポートして auth を定義します:Sandbox.run() に auth=auth を渡します。以降の Python の例でもこの設定を含め、すべての Sandbox.from_id() 呼び出しにも auth=auth を渡してください。[SECRET-NAME] をチームシークレットの名前に置き換えてください:
- Python
- TypeScript
cwsandbox から Secret をインポートし、environment_variables から ANTHROPIC_ENVIRONMENT_KEY を削除して、secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")] を Sandbox.run() に追加します。タスクを実行して確認する
どちらのセットアップ方法でも、ご自身のマシンでセッションクライアントを実行します。使用する言語に対応した Anthropic SDK をインストールしてください:- Python
- TypeScript
[ANTHROPIC-API-KEY] を Console の API キーに、[AGENT-ID] を既存のエージェント ID に、[ENVIRONMENT-ID] をワーカーに接続された環境に置き換えてください:
- Python
- TypeScript
verify_claude_worker.py
- Python
- TypeScript
requires_action で停止した場合、参照されているツールイベントを調査します。evaluated_permission: "ask" のある Call は、Anthropic の ツール確認ワークフロー が必要です。ワーカーは許可された Call を処理します。停止した場合は、そのログを調査します。別のセッションを作成するのではなく、そのセッションを継続するためにセッション ID を保持してください。
タスクが完了したら、セットアップに適したコマンドでサンドボックスからファイルを読み取ります。[SANDBOX-NAME] または [SANDBOX-ID] をワークスペース名または出力されたサンドボックス ID に置き換えてください。
- cws-agent
- Sandboxes SDK
cwsandbox をインストールした仮想環境を再有効化してください。TypeScript の場合、SDK スニペットを .mts ファイルとして保存し、npx tsx で実行してください。
ファイルの内容はクライアントが出力した値と一致する必要があります。これにより、エージェントのツール実行が特定の CoreWeave サンドボックスに紐づけられます。
結果を保持して停止する
実行中のタスクが終了するのを待ち、必要な結果をサンドボックスからコピーします。その後、セットアップに合ったコマンドを使用して停止します:- cws-agent
- Sandboxes SDK
down は停止前にワークスペースのスナップショットを取得します。取得に失敗した場合は、cws-agent status [SANDBOX-NAME] を確認し、失敗を解決してから再試行してください。保存されていない変更を破棄できる場合は、down --no-snapshot を使用します。トラブルシューティング
これらのチェックを使用してよくある問題を解決します:- セッションがワーカーを待機している場合、環境 ID、ワーカーログ、および別のタスクがすでにワーカーを占有していないかを確認します。
- ワーカーが認証できない場合、その環境キーを確認します。セッションクライアントが使用する Console APIキーは異なる認証情報です。
- ツールが不足している場合、必要な依存関係を含むイメージをビルドします。例では Python イメージを使用しており、プロジェクト固有のツールチェーンをインストールしていません。