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

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

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



クラウド環境との違い

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

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



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

セルフホスティングはエージェントのコードがどこで実行されるかを制御します。MCPトンネルはAnthropicがお客様のネットワーク内のMCPサーバーにどのように到達するかを制御します。これらは独立しています。Anthropicのクラウドサンドボックスで実行されるセッションでもトンネル経由でプライベートMCPサーバーに到達でき、セルフホスト型セッションでもトンネル経由または公開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がスキルファイルを見つけられるようにエージェントのシステムプロンプトを更新してください。
• 出力: セルフホスト型環境では、セッションのシステムプロンプトからAnthropicが管理するサンドボックスで使用される/mnt/session/outputsの指示が省略されるため、最終的な成果物はエージェントがサンドボックスのファイルシステム内に書き込んだ場所（通常は作業ディレクトリ配下）に配置されます。



始める前に

以下が必要です。

• 既存のエージェント。 まだない場合は、まずクイックスタートを完了し、そのエージェント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など）を渡します。クレームされたワークアイテムにはセッションのメタデータは含まれませんが、セッションIDは含まれます。スポーンスクリプトまたは--on-workハンドラーがセッションを取得（GET /v1/sessions/{session_id}）してmetadataフィールドを読み取り、ツール実行が始まる前にファイルを作業ディレクトリにステージングします。

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

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



サンドボックスからカスタムツールを提供する

カスタムツールは、お客様自身のコードが実行するツールです。エージェントはagent.custom_tool_useイベントを発行し、対応するuser.custom_tool_resultを待ちます。ワーカーがそのコードになることができ、サンドボックス内で実行されるため、ツールはサンドボックスに設定した内部サービス、認証情報、ネットワークの外向き通信にのみ到達できます。環境キーがカスタムツール結果の送信を認可するため、Claude APIキーをワーカーホストに置く必要はありません。

ワーカーは、登録されたツールにのみ応答します。エージェントに宣言されているがワーカーにもクライアントにも登録されていないカスタムツールは、何かがその結果を送信するまで、セッションをrequires_action停止理由で一時停止状態のままにします。イベントフローについてはカスタムツール呼び出しの処理を参照してください。



MCPサーバーをカスタムツールとしてラップする

MCPコネクタはAnthropic側からMCPサーバーに接続するため、サーバーは直接またはMCPトンネル経由でAnthropicが到達できるHTTPエンドポイントを公開する必要があります。お客様のネットワークからのみ到達可能なサーバーを使用するには、代わりにワーカーをMCPクライアントにし、サーバーのツールをカスタムツールとして宣言します。MCPサーバーはネットワーク外部からの受信接続を必要としません。Anthropicが受け取るのは、エージェントに宣言したツール定義、各呼び出しの入力、ワーカーが返送する結果のみです。実行時には、モデルはラップされたツールを他のカスタムツールと同様に呼び出します。

1. エージェントがagent.custom_tool_useイベントを発行します。
2. サンドボックス内のワーカーが、開いているMCPセッションを介して、ネットワーク上のサーバーに呼び出しを転送します。
3. ワーカーがサーバーのレスポンスをuser.custom_tool_resultとして送信します。

SDKのクライアントサイドMCPヘルパーは、サーバーのツールをワーカーが受け入れる実行可能なツールに変換します。Anthropic SDKと一緒にMCP SDKをインストールしてください（pip install "anthropic[mcp]" "mcp>=1.24"、npm install @modelcontextprotocol/sdk、go get github.com/modelcontextprotocol/go-sdk）。例では認証なしで接続しています。認証情報を送信するには、MCPトランスポートに渡すHTTPクライアントまたはリクエストオプション（Pythonではhttp_client、TypeScriptではrequestInit、GoではHTTPClient）を設定してください。

MCPサーバーをラップする際は、以下の点に注意してください。

• ツールは宣言されるものであり、実行時に検出されるものではありません。 ワーカーは起動時に一度だけMCPサーバーのツールを一覧表示し、実行中のセッションにツールを追加することはできません。サーバーのツールが変更された場合は、エージェント上で、またはアイドル状態のセッションに対してエージェント設定の更新を通じて再度宣言し、ワーカーを再起動してください。
• 名前と説明はManaged Agents APIに適合する必要があります。 カスタムツール名はエージェントごとに一意で、英字、数字、アンダースコア、ハイフンを使用します（1〜128文字）。説明は必須です（1〜4,096文字）。エージェントのtools配列は最大128エントリです（ラップされた各ツールが1エントリ、組み込みツールセットがさらに1エントリ）。APIは、ツール名を再利用する宣言、bashやreadなどの組み込みエージェントツールと同じ名前のカスタムツール、予約済みのmcp__プレフィックスを使用する宣言を拒否します。MCPヘルパーはサーバーの名前と説明をそのまま保持するため、必要に応じて名前を変更したり短縮したりしてください。2つのサーバーが同じツール名を公開している場合は、プレフィックス付きの名前でラッパーを自分で定義し、サーバーの元のツール名を呼び出すようにしてください。
• ほとんどのスキーマは変更なしで通過します。 APIは、additionalPropertiesやtitleなど、MCPサーバーが一般的に出力するJSON Schemaキーワードを受け入れます。カスタムツールのinput_schema内のどこにあっても$refなどの参照キーワードは拒否されるため、pydanticなどのジェネレータが$defsに分離するスキーマはインライン化してください。また、トップレベルのoneOf、anyOf、allOf、および英字、数字、アンダースコア、ドット、ハイフン以外のプロパティ名（1〜64文字）も拒否されます。
• ツールの失敗はエラーツール結果として表面化します。 MCPサーバーがツールエラーを報告すると、ワーカーはモデルが対応できるエラーツール結果を送信します。オーディオブロックやリソースリンクなど、ツール結果に相当するものがないMCPコンテンツもエラーとして表面化します。Pythonワーカーの例がread_timeout_secondsで行っているように、MCPクライアントにタイムアウトを設定すると、より速く明確に失敗します。タイムアウトがない場合、ハングした呼び出しは、TypeScript MCP SDKのデフォルトのリクエストタイムアウト（約1分）が発火するか、ワーカー自身のバックストップ（Pythonでは約2分半、Goでは2分。Goではワーカーが120秒のデフォルトを超えたツール呼び出しをキャンセルしてエラー結果を送信します）が発火したときにのみエラー結果になります。
• 運用している、または信頼しているサーバーをラップしてください。 ラップされたツールの名前、説明、結果は、他のツールと同様にモデルのコンテキストに入ります。これは、ワーカーホスト上のbashを含む他のツールでエージェントが何をするかに影響を与える可能性のある、信頼できない入力です。エージェントに使用させる意図のあるツールのみを宣言してください。
• 権限ポリシーはカスタムツールには適用されません。 権限ポリシーは組み込みおよびMCPツールセットを管理します。ワーカーはモデルが行うすべてのラップされたツール呼び出しを実行するため、承認ステップは独自のツールコードに組み込んでください。



モニタリングと運用

これらの呼び出しは、ワーカーフリートを観察および管理するために、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 を使用して、特定のセッションを処理しているワーカーにシャットダウンを要求します。デフォルトでは、ワークアイテムは stopping に移行します。ワーカーは次のリースハートビートでこれに気づき、セッションの実行中のツール呼び出しをキャンセルし、シャットダウンを確認します。その時点でワークアイテムは stopped になります。リクエストボディで force: true を渡す（CLIの場合は --force を渡す）と、ワーカーの確認を待たずにワークアイテムを即座に stopped としてマークします。

これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、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)



次のステップ