サンドボックスでエージェントを実行する

CoreWeave 上にWorkspaceを用意して、エージェントがコードの編集、テストの実行、結果の保存を行えるようにしましょう。この概要では、インテグレーションの選び方と、長時間のセッション、サブエージェント、ツール実行に対応した環境の設定方法を説明します。スクリーンショット、マウス入力、キーボード入力を通じてグラフィカルなデスクトップを操作するエージェントについては、サンドボックスでコンピューター操作エージェントを実行するを参照してください。ベンチマークに基づくエージェントの評価については、CoreWeave のサンドボックスで評価を実行するを参照してください。 Claude Code クラウドセッションの例では、claude.ai/code でセッションを開始するたびに、サンドボックス上でホストされたオーケストレーターがワーカーサンドボックスをオンデマンドでプロビジョニングします。ワーカーは解放されると停止します。

対話型コーディングエージェントと自律型エージェント

対話型コーディングエージェントでは、エージェントと協力しながら作業します。ターミナル、ブラウザー、またはモバイルアプリから質問したり、編集内容を確認したり、action を承認したりします。たとえば、Claude Code を使用して失敗しているテストを調査し、ユーザーが変更の方向性を指示します。自律型エージェントでは、タスクを委譲し、後で結果を受け取ります。たとえば、リポジトリの移行を割り当て、テストの実行と変更の修正をエージェントに任せてから、結果を確認します。作業を開始する前に、エージェントの権限、認証情報、停止条件を設定してください。なお、必要に応じてエージェントが一時停止し、ユーザーの入力を求めることもあります。これらは作業スタイルの違いであり、サンドボックスのタイプが異なるわけではありません。1 つのコーディングハーネスで両方をサポートできます。ハーネスは、エージェントループ、モデルのコンテキスト、ツールの選択、委譲を管理します。CoreWeave は、ツールを実行するためのコンピュートとファイルシステムを提供します。サンドボックスのライフタイムを長くすればエージェントの実行時間は延びますが、会話の圧縮やタスクの復旧が可能かどうかはハーネスによって決まります。

インテグレーションを選択する

以下のインテグレーションは、いずれも CoreWeave のサンドボックス内でコマンドを実行します。ただし、エージェントループが実行される場所と操作に使用するインターフェースはそれぞれ異なります。

ガイド	エージェントループの実行場所	操作方法	用途
Claude Code	サンドボックス	アタッチしたターミナル、Claude のモバイルアプリまたはデスクトップアプリ、または claude.ai/code	ターミナルからリポジトリで作業する、または別のデバイスから Remote Control を使用する。
Cursor	サンドボックス	アタッチしたターミナルまたはスクリプト	リポジトリをインタラクティブに編集する、または無人でコーディングタスクを実行する。
OpenCode CLI	サンドボックス	アタッチしたターミナルまたはコマンド	Serverless Inference または別のモデルプロバイダーでコーディングタスクを実行する。
Muse Code	サンドボックス	Sandboxes SDK	リポジトリに対して CLI タスクを実行し、結果を取得する。
Pi	サンドボックス	アタッチしたターミナル	Serverless Inference を含む任意のモデルプロバイダーを使用して、リポジトリで作業する。
Claude Managed Agents	Anthropic のマネージドサービス	Managed Agents API	セルフホストのワーカーをマネージドなエージェントセッションに接続する。
Codex	サンドボックス	サンドボックス内の Codex CLI、Codex App Server に接続したローカル CLI、またはデスクトップアプリとペアリングしたモバイルアプリ	Codex を使用してリモートリポジトリで作業する。
Devin Outposts	Devin Cloud	Devin Cloud	アウトポストのワーカーを介して、Devin のコマンドをサンドボックス内で実行する。
OpenAI Agents API	OpenAI のマネージドサービス	Agents API を介したアプリケーション	セルフホストのサンドボックスで、エージェントのツールとサブエージェントによる分析を実行する。

Claude Code と Pi の例では、お客様が管理するWorkspaceで対話型エージェントを起動します。Cursor の例では、対話的な作業と無人タスクの両方に対応しています。Muse Code の例では、対話型ターミナルを使わずにタスクを実行します。Managed Agents と Devin Outposts の例では、キューに追加された複数のセッションでサンドボックスを使い回すワーカーを起動します。プロバイダー側のセッションを 1 つ終了しても、そのワーカーのサンドボックスは停止しません。モデルの推論は、引き続きエージェントに設定されたプロバイダー側で行われます。ツールをサンドボックスで実行しても、エージェントがプロンプト、ファイルの内容、ツールの出力をそのプロバイダーに送信しなくなるわけではありません。Workspaceを接続する前に、プロバイダーのデータ処理要件を確認してください。

独自のインテグレーションを構築する

Sandboxes SDK を使用すると、独自のハーネスから環境の作成、ツール呼び出しの実行、結果の収集、コンピュートの停止を行えます。まずはコマンド実行、ファイル操作、クリーンアップパターンのガイドをご覧ください。

cws-agent を使ってみる

cws-agent は、サンドボックスの作成、エージェントのインストール、Workspaceの管理を自動化するツールです。ほとんどのインテグレーションガイドには、このツールを使用するクイックスタート手順が含まれています。一方、Sandboxes SDK を使用してサンドボックスを直接設定するガイドもあります。両方の手順が記載されているガイドでは、どちらの手順を使用してもかまいません。インストール手順に従ってインストールしたら、インテグレーションガイドを選択してください。汎用的な cws-agent の例では、サンドボックスへのアクセスに CoreWeave API アクセストークンを使用します。エージェントのプロバイダーへの認証は別途行ってください。

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

トークンには Sandbox User ロールが必要です。認証情報の選択と取得を参照してください。SDK の例では、サポートされている場合は Forge の認証情報を明示的に渡しています。各ガイドの認証情報のセットアップ手順に従ってください。従来の環境変数を必要とするインテグレーションについては、Forge APIキーをどのようにマッピングすればよいかを各ガイドで説明しています。設定のインポート、並列セッション、Workspaceの保存とリストアについては、cws-agent のドキュメントを参照してください。ハーネスを直接統合する場合は、cws-agent は不要です。

サンドボックスの実行場所を選択する

サーバーレス配置では、CoreWeave が運用するキャパシティを使用します。これらのガイドでは、まずサーバーレス配置を前提として説明します。独自のクラスター配置とサンドボックスポリシーが必要な場合は、CoreWeave Kubernetes Service (CKS) 配置を使用します。この場合、管理者がランナーをデプロイし、ネットワークとリソースの制約を設定します。エージェントには、利用するプロバイダーのほか、使用するパッケージホストやソースホストへのアウトバウンドアクセスが必要です。

長時間のセッションを実行する

有効期間は起動時間を含む実時間ベースの上限であり、作成後に延長することはできません。また、有効期間を設定しても、エージェントが処理を完了することや、中断から復旧することが保証されるわけではありません。サーバーレスサンドボックスでは、max_lifetime_seconds を省略すると、有効期間はデフォルトで 10 分になります。CKS ランナーでは、ポリシーによって別のデフォルト値が指定される場合があります。作成時に有効期間を明示的に設定し、セットアップとタスクに十分な時間を確保してください。

サーバーレスサンドボックスのライフタイムを設定する

SDK のインストールと認証を完了したら、次の作成リクエストで有効期間が 24 時間のサンドボックスを作成します。これらの例では FORGE_API_KEY を読み取り、クライアントに明示的に渡します。

Python
TypeScript

import os
from cwsandbox import AuthHeaders, Sandbox

forge_auth = AuthHeaders(
    headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
    strategy="wandb_api_key",
)

sandbox = Sandbox.run(
    auth=forge_auth,
    placement_mode="serverless",
    container_image="python:3.12-slim",
    resources={"cpu": "4", "memory": "8Gi"},
    max_lifetime_seconds=24 * 60 * 60,
)
print(f"Sandbox ID: {sandbox.sandbox_id}")

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
});
const sandbox = await client.create({
  containerImage: "python:3.12-slim",
  resources: { cpu: "4", memory: "8Gi" },
  maxLifetimeSeconds: 24 * 60 * 60,
  waitUntilRunning: false,
});
console.log(`Sandbox ID: ${sandbox.sandboxId}`);

出力された ID は、SDK で再接続する際に必要になるため保存しておいてください。この ID は作成リクエストが受け付けられたことを示すものであり、起動の完了を示すものではありません。インテグレーションガイドに従って準備完了を待ってからエージェントをインストールして起動するか、必要なツールをあらかじめインストールしたイメージを指定してください。どちらのスタンドアロン作成 Call でも、スクリプトの終了後もサンドボックスは実行されたままになります。TypeScript の withSandbox() では、コールバックの完了時にサンドボックスが停止します。with Sandbox.run(...) ブロックでは、ブロックを抜けた時点でサンドボックスが停止します。SDK の Session を通じて作成したサンドボックスは、そのセッションが閉じられたときに停止します。プロセス終了時のクリーンアップによってセッションが閉じられた場合も同様です。 cws-agent をインストールして認証を済ませている場合は、Claude Code の起動時に同じ有効期間を設定できます。[SANDBOX-NAME] は、Workspace 用の cws-agent セッション名に置き換えてください。名前は 1～40 文字の英小文字、数字、ハイフンで構成し、先頭は英小文字または数字にする必要があります。

cws-agent launch [SANDBOX-NAME] --lifetime 24h --cpu 4 --memory 8Gi --permission-mode native

ターミナルを閉じた後も対話型エージェントを動作させ続けるには、ターミナルマルチプレクサー内でエージェントを実行します。デタッチと再接続の手順については、tmux ガイドを参照してください。デタッチされたセッションでも、承認やログインの待機は継続されます。

CKS の配置とポリシーを設定する

CKS に配置するには、SANDBOX_USER IAM action を持つ CoreWeave API アクセストークンが必要です。独自のコンピュートを使用するの手順に従ってください。Python では、auth=AuthStrategy.COREWEAVE_API_KEY を設定し、max_lifetime_seconds はそのまま使用して、placement_mode="cks" と runner_ids=["[RUNNER-ID]"] を設定します。[RUNNER-ID] はお使いのクラスターのランナー ID に置き換えてください。TypeScript では、@coreweave/cwsandbox/node エントリポイントを使用し、maxLifetimeSeconds はそのまま使用します。CKS を選択するには runnerIds: ["[RUNNER-ID]"] を設定します。ランナーにはポリシーが設定されている必要があります。また、リソースの上限は作成リクエストを満たす値にする必要があります。その他の制約や、既存のワークロードに必要な高めの上限はそのまま維持してください。ポリシーを書き込むとドキュメント全体が置き換えられ、変更は新しく作成されるサンドボックスにのみ適用されます。有効期間を省略したリクエストのデフォルトを 24 時間にするには、管理者に CoreWeave Intelligent CLI で既存のポリシーを編集してもらいます。

cwic sandbox runner policy edit [RUNNER-ID]

以下のフィールドを既存の constraints オブジェクトにマージしてください。これはポリシーの一部分であり、ドキュメント全体を置き換えるものではありません。

{
  "constraints": {
    "lifecycle": {
      "defaultLifetimeSeconds": 86400
    },
    "resources": {
      "maxCpu": "4",
      "maxMemory": "8Gi"
    }
  }
}

リクエストで明示的に指定した有効期間は、defaultLifetimeSeconds より優先されます。プラットフォームの上限は 30 日です。ポリシーには、この上限を引き上げるための maxLifetimeSeconds フィールドはありません。プロバイダーへの接続を許可するには、ネットワークの外向き通信も設定してください。allowedEgress はリクエストで指定された送信先を許可し、defaultEgress はリクエストで外向き通信のルールが省略された場合に適用されるアクセスを提供します。許可リストに含めるだけでは、アクセスは付与されません。

実行時間と会話の状態を分けて管理する

ツールコマンドの timeout_seconds は、サンドボックスのライフタイムとは別に設定されます。時間のかかるビルドやテストには、適切なコマンドタイムアウトを設定してください。無人で実行するタスクでは、ハーネスがサポートするバックグラウンド実行や復旧の機能を使用し、中間結果を保存するようにしてください。詳しくは、コマンドのタイムアウトとサンドボックスのライフサイクルを参照してください。

サブエージェントに作業を委譲する

サブエージェントはハーネス側で設定します。サンドボックス作成時のフラグでサブエージェントを有効にすることはできません。たとえば、Claude Code にはサブエージェントが組み込まれています。インタラクティブセッションで、互いに独立した調査を分割して進めるよう指示します。

別々のサブエージェントを使用して、API とそのテストを並行して調査してください。
各サブエージェントには、何も編集せずに、関連するファイルと検出結果を報告させてください。
各サブエージェントの検出結果をまとめて、実装計画を作成してください。

再利用できるスペシャリストを定義するには、Claude Code を起動する前に、サンドボックスの project 内に次のファイルを作成します。

.claude/agents/test-reader.md

---
name: test-reader
description: Inspect tests and report coverage gaps without editing files.
tools: Read, Grep, Glob
---
Find tests relevant to the requested change. Summarize coverage gaps and
cite the test files. Do not modify files.

特定のタスクに test-reader を使用するよう Claude に依頼します。委譲はデフォルトで有効です。親エージェントの Agent ツールに対して permissions.deny ルールを設定すると、委譲がブロックされます。ツールの権限やその他のオプションについては、Claude Code サブエージェントの設定を参照してください。同じサンドボックスを使用するサブエージェントは、そのサンドボックスのコンピュートとファイルシステムを共有します。同時に実行されるツールを考慮して CPU とメモリのサイズを決め、同じファイルを同時に編集しないようにしてください。ワーカーごとに独立した認証情報や分離が必要な場合は、サンドボックスを分けてください。独立したコーディングタスクには、cws-agent の並列セッションを使用すると、1 つのサンドボックス内でそれぞれ別の Git ワークツリーを利用できます。これらは互いに独立したセッションであり、ハーネスが管理するサブエージェントではなく、セキュリティ境界も分離されません。

ツールを効率的に使用する

エージェントがタスクそのものに時間を使えるよう、環境を準備します。

繰り返し使用する依存関係はイメージにインストールします。 作成時に準備済みの container_image を渡すと、セッションごとに同じテストツールやランタイムをインストールせずに済みます。サンドボックスの設定を参照してください。
タスクに必要なツールを選択します。 ハーネスでスキルと Model Context Protocol (MCP) サーバーを設定します。cws-agent で管理される CLI セッションの場合は、ローカルの設定をプレビューし、選択した項目をそのサンドボックスにインポートします。
cws-agent config preview [SANDBOX-NAME] --verbose cws-agent config sync [SANDBOX-NAME]
Claude Managed Agents のワーカーでは、設定のインポートは利用できません。sync コマンドを実行すると、項目の選択と確認を求められます。変更を読み込むには、エージェントを再起動してください。必要な実行ファイルはサンドボックスにインストールし、ローカルマシンでしか使えないパスは置き換えてください。スキルと MCP のインポートを参照してください。
要点を絞った結果を返します。 ツールがデータをモデルに返す前に、サンドボックス内でフィルタリングまたは要約するようにします。たとえば、テストの出力全体はファイルに保存し、失敗したテスト名と簡潔な失敗の概要だけを返します。後から調査できるよう、ファイルは残しておいてください。
独立した操作を並列化します。 リソースに余裕がある場合は、互いに独立したチェックを同時に実行します。依存関係のあるステップは、前提となる処理が完了してから実行します。コマンドを開始して結果を収集する方法については、SDK 実行ガイドを参照してください。

ツールのディスカバリー、コンテキストの圧縮、呼び出すツールの判断は、引き続きハーネス側の機能です。CoreWeave が担うのは、コマンドの実行とそのファイルの保存です。

結果を保持してコンピュートを停止する

エージェントを終了したり、プロバイダーのセッションを終了したりしても、サンドボックスが停止するとは限りません。インテグレーションガイドのクリーンアップステップに従い、コンピュートの作成時には有効期間を設定してください。停止する前に、結果をコピーして取り出す、変更をリポジトリにプッシュする、またはスナップショットボリュームを設定してファイルシステムスナップショットを使用する、のいずれかを行ってください。スナップショットで保持されるのはファイルのみで、実行中のプロセスは保持されません。プロバイダーの会話履歴は、これとは別のライフサイクルで管理されます。