セルフホスト型サンドボックス

デフォルトでは、Managed AgentsはAnthropicが管理するクラウドサンドボックス内でツールとコードを実行します。セルフホスト型サンドボックスでは、オーケストレーションはAnthropic側に保持されますが、ツール実行はお客様が管理するインフラストラクチャに移されるため、エージェントのコード、ファイルシステム、ネットワークエグレスがお客様の環境から出ることはありません。

ツール実行はお客様のホスト上に留まります。エージェントが読み書きするファイルシステム、生成するプロセス、到達可能なネットワークはすべてお客様の管理下にあります。ツールの入力と出力は引き続きAnthropicのコントロールプレーン（Claudeが実行される場所）に流れるため、モデルは結果を確認して次に何をすべきかを判断できます。完全なデータフローの境界については、セキュリティモデルを参照してください。



クラウド環境との違い

セルフホスティングは、エージェントがネットワーク境界から出せないデータを操作する必要がある場合、パブリックにルーティングできない内部サービスに到達する必要がある場合、または組織独自のコンプライアンスおよび監査管理の下で実行する必要がある場合に適しています。

Zero Data RetentionおよびHIPAA BAAの適格性については、APIとデータ保持を参照してください。



MCPトンネルと組み合わせるタイミング

セルフホスティングはエージェントのコードがどこで実行されるかを制御します。MCPトンネルはAnthropicがお客様のネットワーク内のMCPサーバーにどのように到達するかを制御します。これらは独立しています。Anthropicのクラウドサンドボックスで実行されているセッションでもトンネル経由でプライベートMCPサーバーに到達でき、セルフホスト型セッションはトンネル経由またはパブリックのMCPサーバーのいずれも使用できます。実行とツールアクセスの両方を境界内に留めたい場合は、両方を使用してください。



環境ワーカー

環境ワーカーは、お客様自身のインフラストラクチャ上で実行するプロセスです。Anthropicからツール実行リクエストを受け取り、ローカルで実行します。self_hosted環境はワークキューとして機能します。セッションが割り当てられると、Anthropicはそのセッションをワークアイテムとしてキューに入れます。ワーカーはそのキューからワークアイテムを取得（クレーム）し、それぞれに対して実行コンテキストを生成し、エージェントのスキル（エージェントにドメイン固有の専門知識を与える、再利用可能なファイルシステムベースのリソース）をダウンロードし、ツール呼び出しを実行して、結果を返送します。

ワークアイテムは環境のキューをポーリングすることでクレームされます。継続的にポーリングする常時稼働ワーカー、またはsession.status_run_startedで起動してポーリングを開始するWebhookトリガー型ハンドラーのいずれかです。

CLIとSDKの両方に、事前構築されたワーカーが付属しています。ant CLIは常時稼働パターンのみをサポートし、SDKは常時稼働とWebhookトリガー型の両方をサポートします。どちらも設定可能です。CLIフラグについてはリファレンスのセルフホスト型ワーカーを、SDKオプションについてはこのページのSDKヘルパーを参照してください。より細かく制御したい場合は、Environments Workエンドポイントを直接呼び出して独自のワーカーを実装してください。



サンドボックスのファイルシステム

• /workspace: ツール実行とスキルダウンロードのためのシステムデフォルトの作業ディレクトリです。CLIの--workdirフラグはデフォルトで現在のディレクトリになります。システムデフォルトに合わせるには--workdir /workspaceを渡してください。スキルは<workdir>/skills/<name>/にダウンロードされます。別の作業ディレクトリを使用する場合は、Claudeがスキルファイルを見つけられるようにエージェントのシステムプロンプトを更新してください。
• /mnt/session/outputs: ワーカーハーネスは、最終的な成果物をここに書き込むようClaudeに指示します。サンドボックスモードでは、このパスにホストディレクトリをマウントして、セッション終了後に出力を取得します。インプロセスモードでは、ワーカーのファイルツールは代わりに作業ディレクトリ配下に書き込むため、このパスは適用されません。



始める前に

以下が必要です。

• 既存のエージェント。 お持ちでない場合は、まずクイックスタートを完了し、そのエージェントIDを控えてください。
• /bin/bashがその正確なパスに存在するLinuxホスト。 ワーカーのbashツールはPATHを参照せずに直接これを呼び出します。TypeScript SDKはさらにPATH上のunzipとtar、およびNode.js 22以降を必要とします。PythonとGoのSDKはアーカイブ展開に標準ライブラリを使用するため、追加のバイナリ要件はありません。
• ant CLIまたはAnthropic SDK（Python、TypeScript、またはGo）がワーカーホスト上にあること。
• 2つの認証情報: 環境キー（以下の手順でConsoleで生成）はワーカーをそのキューに対して認証します。Claude APIキーはワーカーホストの外部からセッションを作成し、キューの統計情報を読み取ります。キーの生成はConsoleのみで行えます。



ワーカーを実行する

最もシンプルなセットアップには常時稼働を選択してください。長時間実行されるプロセスがキューを継続的にポーリングし、アウトバウンドHTTPSのみを必要とします。アイドル状態のポーラーの実行を避けたい場合はWebhookトリガー型を選択してください。これにはAnthropicが到達できるWebhookエンドポイントが必要です（エンドポイントのセットアップと署名検証についてはWebhookを参照してください）。



SDKヘルパー

SDKは、制御レベルの異なる3つのヘルパーを提供します。EnvironmentWorkerはほとんどのユースケースをカバーします。セッションごとに独自のプロセスを起動する必要がある場合や、すでにクレーム済みのセッションに対してツールを実行する必要がある場合は、より低レベルのヘルパーを使用してください。

• EnvironmentWorker: すぐに使えるワーカーです。ポーリング、セットアップ、実行をエンドツーエンドで処理します。
  • .run(): 無期限に実行され、セッションが到着するたびに取得します。
  • .handle_item(): クレーム済みの単一のワークアイテムを処理して終了します。ワーク、セッション、環境の識別子を明示的に渡すか、ant beta:worker poll --on-workが生成するプロセスに設定するANTHROPIC_*変数を読み取らせます。
• work.poller(): ワークキューを代わりにポーリングし、クレームした各セッションを渡します。各セッションに対して何を行うかを自分で決めたい場合（たとえば、インプロセスでツールを実行するのではなくサンドボックスを起動する場合）に使用します。
  • drain: 新しいワークを待つのではなく、キューが空になったらポーリングを停止するかどうか。
  • block_ms: ワークが到着するまで待機する時間（ミリ秒）。1から999の間である必要があります（ポーリングごとの待機時間。ヘルパーは自動的に再ポーリングします）。ノンブロッキングチェックにはnull（PythonではNone、Goではparam.Null[int64]()）を渡します。パラメータを省略するとデフォルトの999ミリ秒のロングポーリングが使用されます。
  • reclaim_older_than_ms: クレームされたが、この時間（ミリ秒）内に確認応答されなかったワークアイテムを再クレームします。
  • auto_stop: ループ本体の処理が終わったら、各ワークアイテムに対して停止シグナルを送信するかどうか。Goのポーラーにはオプトアウトがなく、常に停止シグナルを送信するため、デタッチするのではなく、セッションが完了するまでループ本体内でブロックしてください。
• client.beta.sessions.events.tool_runner(): セッションIDとツールリストを指定して、単一のセッションのツール呼び出しを実行します。すでにワークをクレーム済みで、実行レイヤーのみが必要な場合に使用します。

セッションごとに独自のプロセスを起動したい場合（たとえば、クレームした各セッションに対してサンドボックスを起動する場合）は、ワークポーラーを直接使用してください。

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # 独自のセッションごとのサンドボックスランチャーに置き換えてください。
    # 起動したサンドボックスにはANTHROPIC_ENVIRONMENT_KEYを渡し、
    # APIキーは決して渡さないでください。
    print(f"claimed session {work.data.id}")


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:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

**AgentToolContextはツール呼び出しの実行コンテキストです。作業ディレクトリとパスポリシーを定義し、セッションのスキルをダウンロードできます。beta_agent_toolset_20260401(env)**はAgentToolContextを受け取り、標準のツール実装（bash、read、write、edit、glob、grep）を返します。

EnvironmentWorkerを使用する場合: どちらも自動的に管理されます。ツールリストをカスタマイズするには、toolsファクトリを渡します。

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

work.poller()とtool_runner()を使用する場合: client.beta.sessions.events.tool_runner()にtoolsとしてツールリストを渡します。そのリストを構築するには、AgentToolContextを自分でセットアップし、beta_agent_toolset_20260401(env)を呼び出します。

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # スキルは /workspace/skills/<name>/ にダウンロードされます
    tools = beta_agent_toolset_20260401(env)



ワーカーが接続されていることを確認する

別のシェルから、ANTHROPIC_API_KEYをClaude APIキー（環境キーではありません）に設定した状態で、workers_pollingが1以上であることを確認します。

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

workers_pollingが0のままの場合、ワーカーはキューに到達していません。ワーカーホスト上でANTHROPIC_ENVIRONMENT_KEYとANTHROPIC_ENVIRONMENT_IDが設定されていることを確認してください。完全な統計レスポンスと他の言語の例については、キューの深さを読み取るを参照してください。



セッションを開始する

ワーカーが実行されたら、その環境を対象とするセッションを作成します。AGENT_IDを始める前にで控えたエージェントIDに設定します。セッションは環境のワークキューに入り、ワーカーがクレームするまでそこで待機します。ワーカーが接続されていない場合、セッションは失敗するのではなくキューに留まります。

Anthropicは、セルフホスト型サンドボックスにファイルやGitHubリポジトリをマウントしません。セッション固有のファイルを利用可能にするには、セッションのmetadataフィールドにファイル参照（S3パスやコミットSHAなど）を渡します。スポーンスクリプトまたは--on-workハンドラーは、クレームしたワークアイテムからそのメタデータを読み取り（CLIポーラーはワークアイテムのJSONをスクリプトのstdinにパイプし、SDKハンドラーはEnvironments Workエンドポイントを通じて読み取れます）、ツール実行が始まる前にファイルを作業ディレクトリにステージングします。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

CLIフラグの完全なリストについてはリファレンスのセルフホスト型ワーカーを、SDKヘルパーのオプションについてはSDKヘルパーを参照してください。



モニタリングと運用

これらの呼び出しは、ワーカーフリートを観測・管理するために、Claude APIキーで認証された監視または運用ツールから実行します。クレームとキープアライブのループはワーカーヘルパー内で処理されるため、これらのエンドポイントを直接呼び出す必要はありません。



キューの深さを読み取る

work.statsは環境のキューの状態を返します。

• depthはクレーム待ちのアイテム数です。この値に基づいてワーカーフリートをスケールしたり、バックログのアラートを設定したりします。
• pendingはワーカーがクレームして現在処理中のアイテム数です。
• oldest_queued_atは、まだキューに入っているか処理中の最も古いアイテムのタイムスタンプです。存在しない場合はnullです。
• workers_pollingは過去30秒間にポーリングしたワーカーの数です。死活監視のアラートに使用してください。

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}



セッションを正常に停止する

work.stopを使用して、特定のセッションを処理しているワーカーにクリーンなシャットダウンを要求します。ワーカーは実行中のツール呼び出しを完了し、最終ステータスを送信して、セッションを解放します。現在のツール呼び出しの完了を待たずに即座に中断するには、リクエストボディでforce: trueを渡します（CLIの場合は--forceを渡します）。

これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、ANTHROPIC_WORK_IDは自動的に設定されません。以下の例を実行する前に、対象のワークアイテムのIDに設定してください。ワークアイテムのIDを見つけるには、Environments Workエンドポイントを通じて環境のワークアイテムを一覧表示します。

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)



次のステップ