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

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

ツール実行はお客様のホスト上に留まります。エージェントが読み書きするファイルシステム、エージェントが生成するプロセス、エージェントが到達できるネットワークは、すべてお客様の管理下にあります。ツールの入力と出力は引き続き Anthropic のコントロールプレーン（Claude が動作する場所）に流れるため、モデルは結果を確認して次に何をすべきかを判断できます。エージェントのスキルと、セッションにアタッチされたメモリストアの内容は Anthropic によって保存され、セッションのためにお客様のサンドボックスにコピーされます。エージェントがメモリファイルに加えた変更はストアに同期されます。データフローの境界の全体像については、セキュリティモデルを参照してください。

クラウド環境との違い

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

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

MCP トンネルと組み合わせる場合

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

環境ワーカー

「environment worker」（環境ワーカー）は、お客様自身のインフラストラクチャ上で実行するプロセスです。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 の指示が省略されるため、最終成果物はエージェントがサンドボックスのファイルシステム内で書き込んだ場所（通常は作業ディレクトリ配下）に置かれます。
• /mnt/memory/: セッションにアタッチされたメモリストアは、SDK ワーカーによってここに実体化されます。ストアごとに 1 つのディレクトリがストアの mount_path（例: /mnt/memory/user-preferences/）に作成されます。ワーカーはセッションを取得したときにこれらのディレクトリを作成し、セッション終了時に削除します。メモリストアを使用するを参照してください。

始める前に

以下が必要です。

• 既存のエージェント。 まだない場合は、先にクイックスタートを完了し、そのエージェント ID を控えておいてください。
• Linux ホスト。/bin/bash がまさにそのパスに存在する必要があります。ワーカーの bash ツールは PATH を参照せずに直接これを呼び出します。TypeScript SDK ではさらに PATH 上に unzip と tar、および Node.js 22 以降が必要です。Python SDK と Go SDK はアーカイブ展開に標準ライブラリを使用するため、追加のバイナリ要件はありません。
• ant CLI または Anthropic SDK（Python、TypeScript、または Go）がワーカーホスト上にあること。
• 認証情報: 環境キー（以降の手順で Console で生成）はワーカーをそのキューに対して認証します。Claude の APIキーは、ワーカーホストの外部からセッションを作成し、キューの統計情報を読み取るために使用します。キーの生成は Console でのみ可能です。取得したワークアイテムには、ワーカーがメモリストアをマウントするために使用するセッションごとの secret も含まれます。これはお客様が生成するものではありませんが、セッションごとのサンドボックスパターンでは、お客様自身がサンドボックスに転送します（セッションごとに 1 つのサンドボックスを実行するを参照）。
• メモリストアを使う場合は、準備済みのホスト。 この環境上のセッションがメモリストアをアタッチする場合は、ワーカーを起動する前にワーカーホスト上で /mnt/memory を準備してください。ホストを準備するを参照してください。

1. 1

   セルフホスト型環境を作成する

   Console で: Workspace > Environments > New > Self-hosted

   または API 経由で:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   environment = client.beta.environments.create(
       name="self-hosted", config={"type": "self_hosted"}
   )
   print(environment.id)

2. 2

   環境キーを生成する

   Console で環境を開き、Generate environment key をクリックします。環境を Console で作成したか API で作成したかにかかわらず、キーの生成は Console でのみ可能です。次に、ワーカーホスト上で環境 ID とキーをエクスポートします。

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   

ワーカーを実行する

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

SDK ヘルパー

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

• EnvironmentWorker: すぐに使えるワーカーです。ポーリング、セットアップ、実行をエンドツーエンドで処理します。
  • .run(): 無期限に実行し、到着したセッションを順次処理します。
  • .handle_item(): 取得済みの単一のワークアイテムを処理して終了します。ワーク、セッション、環境の識別子を明示的に渡すか、ant beta:worker poll --on-work が生成するプロセスに設定する ANTHROPIC_* 変数を読み取らせます。セッションがメモリストアをマウントできるようにするには、ワークアイテムの secret を work_secret（TypeScript では workSecret、Go では WorkSecret）として渡すか、ANTHROPIC_WORK_SECRET を設定してください。ant beta:worker poll --on-work はその変数を設定しないため、セッションごとに 1 つのサンドボックスを実行するに示すように、スクリプトの標準入力に書き込まれるワークアイテム JSON から secret を読み取ってください。
  • memory_sync_interval（TypeScript では memorySyncIntervalMs、Go では MemorySyncInterval）と memory_sync_deletions（memorySyncDeletions、MemorySyncDeletions）: セッション実行中にアタッチされたメモリストアがサーバーと調整する頻度、およびエージェントがローカルで削除したファイルをストアからも削除するかどうか。単位、デフォルト値、メモリサポートを無効にする方法については同期を設定するを参照してください。
• work.poller(): お客様に代わってワークキューをポーリングし、取得した各セッションを渡します。各セッションで何を行うかを自分で決めたい場合、たとえばインプロセスでツールを実行するのではなくサンドボックスを起動する場合に使用します。
  • drain: 新しいワークを待つのではなく、キューが空になったらポーリングを停止するかどうか。
  • block_ms: 戻る前にワークの到着を待つ時間（ミリ秒）。1 から 999 の間である必要があります（ポーリングごとの待機時間。ヘルパーは自動的に再ポーリングします）。ノンブロッキングチェックには null（Python では None、Go では param.Null[int64]()）を渡します。パラメータを省略するとデフォルトの 999 ms のロングポーリングが使用されます。
  • reclaim_older_than_ms: 取得されたがこのミリ秒数以内に確認応答されなかったワークアイテムを再取得します。
  • auto_stop（TypeScript では autoStop、Go では AutoStop）: ループ本体が各ワークアイテムの処理を終えたときに、そのワークアイテムに対して停止シグナルを送信するかどうか。ワークアイテムを実行するものが自ら停止を送信する場合は常にオフにしてください。handle_item() は停止を送信するため、このページの Webhook ハンドラーのように取得したアイテムを handle_item() に渡す場合は false に設定してください。停止呼び出しを担うサンドボックスを起動する場合も同様です。
• client.beta.sessions.events.tool_runner(): セッション ID とツールリストを指定して、単一セッションのツール呼び出しを実行します。すでにワークを取得済みで、実行レイヤーのみが必要な場合に使用します。

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

import asyncio
import os

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

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # `docker run` を独自のサンドボックスランチャーに置き換えてください。環境キー
    # （APIキーは決して渡さない）と作業項目のセッションごとのシークレットを転送します。内部の
    # ワーカーはセッションのメモリストアをマウントするためにシークレットを必要とします。
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-sdk-worker-image", env=env
    )
    await launcher.wait()


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())

サンドボックスを起動するものは何であれ、内部のワーカーがセッションのメモリストアをマウントできるように、取得したワークアイテムの secret を、セッション、ワーク、環境の識別子とともにサンドボックスに転送する必要があります（たとえば ANTHROPIC_WORK_SECRET として）。セッションごとに 1 つのサンドボックスを実行するを参照してください。

AgentToolContext はツール呼び出しの実行コンテキストです。作業ディレクトリとパスポリシーを定義し、セッションのスキルをダウンロードできます。ファイルツール（read、write、edit、glob、grep）は、作業ディレクトリと allowed_roots（TypeScript では allowedRoots、Go では AllowedRoots）に列挙されたディレクトリに制限され、write と edit はさらに read_only_roots（readOnlyRoots、ReadOnlyRoots）配下のパスを拒否します。EnvironmentWorker はセッションのメモリストアディレクトリをこれらのリストに自動的に追加します。この制限はファイルツールのみに対するガードレールであり、サンドボックスではありません。bash は制約されません。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() を使用する場合: ツールリストを tools として client.beta.sessions.events.tool_runner() に渡します。そのリストを構築するには、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 は含まれます。spawn スクリプトまたは --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 ヘルパーを参照してください。

メモリストアを使用する

セルフホスト型環境上のセッションは、クラウド環境上のセッションとまったく同じようにメモリストアをアタッチします。メモリストアをセッションにアタッチするに示すように、セッション作成時に resources に列挙してください。1 つのセッションには最大 8 個のメモリストアをアタッチできます。セルフホスト型環境では、Anthropic のインフラストラクチャではなく SDK ワーカーがエージェントのために各ストアを実体化するため、そこでのメモリストアには Python、TypeScript、または Go SDK の EnvironmentWorker（またはその handle_item() メソッド）が必要です。

ant CLI ワーカー（ant beta:worker poll および ant beta:worker run）はメモリストアをマウントしません。CLI ポーラーとメモリストアを組み合わせるには、セッションごとに 1 つのサンドボックスを実行するで説明するように、セッションごとのサンドボックス内で SDK ワーカーを実行してください。

Claude Platform on AWS 上のセルフホスト型環境のセッションには、メモリストアをアタッチできません。

ワーカーによるメモリの処理方法

メモリストアがアタッチされたセッションのワークアイテムをワーカーが取得すると、ワーカーは次のことを行います。

1. アタッチされた各ストアを、ワークアイテムのセッションごとの secret で認証して、ワーカーホスト上のその mount_path にダウンロードします。mount_path はクラウドセッションが使用するのと同じ /mnt/memory/ 配下のディレクトリ（たとえば「User Preferences」という名前のストアなら /mnt/memory/user-preferences/）で、セッションのシステムプロンプトがエージェントにそれを説明します。
2. それらのディレクトリをファイルツールの許可ルートに追加し、access: "read_only" でアタッチされたストアのディレクトリを読み取り専用ルートに追加します。これにより、エージェントは作業ディレクトリで使用するのと同じ read、write、edit、glob、grep ツールでメモリを操作できます。
3. ツール呼び出しの後、同期間隔（デフォルトで 15 秒）ごとに最大 1 回、ローカルとリモートの変更を調整します。ストアで変更されたメモリはディスクに書き込まれ、エージェントが変更したファイルはストアにアップロードされます。
4. セッション終了時に最終同期を実行し、保留中のアップロードを最大 30 秒間フラッシュしてから、作成したディレクトリを削除します。セッション実行中にキャンセルされたワーカーは最終同期をスキップしますが、終了前に変更されたファイルをアップロードし、ディレクトリを削除します。

Anthropic 側のメモリストアが引き続き信頼できる情報源です。メモリバージョン、リダクション、Console でのメモリの表示や編集はクラウドセッションと同様に機能し、エージェントのメモリの読み書きは通常のツールイベントとしてイベントストリームに表示されます。各ワーカーは一定間隔で同期するため、あるセッションで書き込まれた変更が実行中の別のセッションから見えるようになるのは、両方が同期した後です。デフォルトの間隔では通常 1 分を大きく下回ります。クラウドサンドボックス上のセッションは互いの変更をほぼ即座に確認できます。

各ストアディレクトリには、ディレクトリをそのストアに結び付ける .anthropic-memory-store という名前のマーカーファイルが含まれています。そのままにしておいてください。マーカーが欠落または変更されているディレクトリは、ワーカーによって同期されません。

ホストを準備する

セルフホスト型サンドボックス上のメモリストアには、ワーカーホスト（始める前にの Linux ホスト）上に POSIX ファイルシステムが必要です。ワーカーはメモリファイルを開く際に O_NOFOLLOW を必要とするため、Windows ホストはサポートされません。大文字小文字のみが異なるメモリパスが衝突しないように、大文字小文字を区別するファイルシステムを推奨します。

ワーカーを起動する前に、親ディレクトリを作成し、ワーカーを実行するユーザーが書き込めるようにします。

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

ストアごとのディレクトリを自分で作成しないでください。ワーカーはセッション開始時に各ストアの mount_path ディレクトリ（たとえば /mnt/memory/user-preferences）を作成し、そのパスにすでに何かが存在する場合はセッションのワークの開始を拒否し、セッション終了時にディレクトリを削除します。ここから 2 つの運用ルールが導かれます。

• セッションが同じストアをアタッチする場合は、ファイルシステムごとに 1 つのセッションを実行する。 2 つのセッションは同じパスを必要とするため、1 つのホスト上で同じストアを同時にマウントすることはできません。セッションごとに 1 つのサンドボックスを実行するで説明するように、各セッションに独自のサンドボックスを与えることでこのルールを満たせます。
• ワーカーを正常に停止する。 セッション実行中にワーカーを停止する場合、EnvironmentWorker がセッションの変更されたメモリファイルをアップロードしてストアディレクトリを削除するのは、強制終了ではなくキャンセルされた場合のみです。強制終了されたプロセスはティアダウンを実行せず、ワーカー自身はシグナルハンドラーをインストールしません。ワーカーを実行するプロセスで SIGTERM と SIGINT をキャンセルに結び付けてください。TypeScript ではワーカーに渡す signal を abort し、Go ではコンテキストをキャンセルし、Python では run() または handle_item() を実行するタスクをキャンセルします。このページのスタンドアロンワーカーのようにワーカー自体がプロセスである場合はシグナルハンドラーから、ワーカーが Webhook ハンドラー内で実行される場合はサーバー独自のシャットダウンフックから行ってください（Webhook ハンドラーはサーバーのシグナルを奪ってはなりません）。そのうえで、ワーカーは SIGTERM で停止し、最終アップロードにそれだけの時間がかかる可能性があるため、強制終了する前に少なくとも 30 秒の終了猶予を与えてください。ティアダウンが実行される前にワーカーが強制終了された場合は、そのストアをアタッチする次のセッションの前に、/mnt/memory/ 配下に残ったストアディレクトリを削除してください。同期されていなかった編集内容は失われます。

セッションごとに1つのサンドボックスを実行する

ワーカーを実行するで紹介した sandbox-per-session（セッションごとのサンドボックス）パターンでは、各セッションに新しいファイルシステムが与えられます。これは、複数のセッションが同じストアをアタッチする場合にホストを準備するが求めている条件です。ホスト上のポーラーとしては、引き続き ant beta:worker poll --on-work（またはSDKのワークポーラー）を使用してください。

そこで示した ant beta:worker run エントリポイントはメモリストアをマウントしないため、セッションごとのイメージは代わりにSDKワーカーを中心に構築してください。そのエントリポイントは EnvironmentWorker を構築して handle_item()（TypeScriptでは handleItem、Goでは HandleItem）を呼び出します。このメソッドは、セッション、ワーク、環境の各識別子を ANTHROPIC_* 変数から読み取り、ワークアイテムのセッションごとの secret を ANTHROPIC_WORK_SECRET から読み取ります。シークレットを work_secret（TypeScriptでは workSecret、Goでは WorkSecret）として明示的に渡すこともできます。

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # 引数なしの場合、handle_item() は spawn スクリプトが転送した ANTHROPIC_* 変数を読み取ります。
        # これには ANTHROPIC_WORK_SECRET も含まれます。
        task = asyncio.create_task(worker.handle_item())
        # コンテナ停止時にタスクをキャンセルすることで、ワーカーは終了前に
        # 変更されたメモリファイルをアップロードし、ストアディレクトリを削除できます。
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

ant beta:worker poll --on-work は、起動するスクリプトに対して ANTHROPIC_WORK_SECRET を設定しません。そのため、起動スクリプトは標準入力で受け取るワークアイテムのJSONからシークレットを読み取り、サンドボックスに渡します。

#!/bin/bash
# spawn.sh: 取得した作業項目ごとに1回呼び出されます
# 取得した作業項目はstdin経由でJSONとして渡されます。そのsecretは
# メモリストアのエンドポイントが必要とするセッションごとの認証情報です。
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -e ANTHROPIC_WORK_SECRET \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-sdk-worker-image

代わりにSDKのワークポーラーでワークを取得する場合は、取得した各アイテムの secret を、起動するサンドボックスに同じ方法で渡してください。シークレットはそのセッションを処理するサンドボックスにのみ渡し、決してログに記録しないでください。

サンドボックスイメージには、書き込み可能な /mnt/memory も必要です（ホストを準備するを参照）。各サンドボックスは1つのセッションを処理した後に破棄されるため、残ったディレクトリをクリーンアップする必要はなく、メモリディレクトリをホストにバインドマウントする必要もありません。ワーカーはサンドボックスが終了する前にその内容をストアにアップロードします。セッションが終了する前にコンテナを停止する場合は、コンテナを強制終了するのではなく、エントリポイントがキャンセルに変換するシグナルを送信してください（ホストを準備するを参照）。そうすればアップロードは引き続き実行されます。また、コンテナがアップロードを完了するための時間も確保してください。Dockerはデフォルトで停止シグナルの10秒後にSIGKILLを送信するため、docker run の --stop-timeout またはオーケストレーターの終了猶予期間を使用して、この制限を「ホストを準備する」が求める30秒以上に引き上げてください。

同期を設定する

EnvironmentWorker の2つのオプションがメモリの動作を制御します。

• memory_sync_interval（Pythonでは秒単位。TypeScriptでは memorySyncIntervalMs でミリ秒単位。Goでは MemorySyncInterval でduration）：セッションの実行中に、アタッチされたストアがサーバーと照合する頻度です。デフォルトは15秒で、最小値は5秒です。間隔を短くすると、別のセッションが古いメモリを参照する時間枠が狭まりますが、その代わりにメモリストアへのリクエストが増えます。Pythonでは None、TypeScriptでは null、Goでは負のdurationを指定すると、メモリサポートが完全に無効になります。ワーカーはストアのダウンロードも同期も行わず、メモリストアがアタッチされたセッションは、システムプロンプトにストアの説明が残っていてもストアなしで実行されます。そのため、メモリサポートを無効にするのは、セッションがメモリストアをアタッチしないワーカーに限定してください。メモリサポートが有効な間は、ストアがアタッチされたセッションに対してセッションごとの secret なしで届いたワークアイテムは、メモリなしで実行されるのではなく失敗します（メモリマウントのトラブルシューティングを参照）。
• memory_sync_deletions（TypeScriptでは memorySyncDeletions、Goでは MemorySyncDeletions）：エージェントがローカルで削除したファイルをストアからも削除するかどうかです。値は、PythonとTypeScriptでは "enabled"（デフォルト）、"log_only"、"disabled" のいずれか、Goでは定数 environments.MemorySyncDeletionsEnabled（ゼロ値）、environments.MemorySyncDeletionsLogOnly、environments.MemorySyncDeletionsDisabled のいずれかです。有効な場合、ワーカーは後続の同期でファイルが依然として存在しないことを確認した時点で、そのメモリをストアから削除します。log-onlyモードでは同じチェックを実行しますが、削除するはずだった内容をログに記録するだけです。これにより、enabledモードを信頼する前に、ワーカーが何を削除するかを観察できます。無効な場合、ストアからは一切削除しません。アップロードとダウンロードはこの設定の影響を受けません。

これらのオプションは、ワーカーを構築する場所で設定してください。EnvironmentWorker コンストラクタを使う場合でも、PythonとTypeScriptでwebhookハンドラーが使用する client.beta.environments.work.worker() ファクトリを使う場合でも同様です。

たとえば、10秒ごとに同期し、ワーカーが行うはずだった削除をログに記録するだけにするには、次のようにします。

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

読み取り専用ストアと競合

access: "read_only" でアタッチされたストアの場合、write ツールと edit ツールはそのディレクトリ内のファイルの変更を拒否し、ワーカーはそこから何もアップロードしません。bash を通じた変更、またはサンドボックスから提供するカスタムツールやMCPサーバーを通じた変更は、ローカルではブロックされません。それらはストアに同期されることはなく、そのメモリに対する次のリモート変更によって上書きされます。セッション中にローカルコピー自体を変更されないままにしておく必要がある場合は、そのエージェントの bash ツールを無効にし、サンドボックスのファイルシステムに書き込むカスタムツールを与えないでください。ストアのパスを読み取り専用でマウントしないでください。ワーカー自身がディレクトリを作成し、ダウンロードしたメモリをそこに書き込む必要があるためです。

競合はストア側が優先されて解決されます。セッションが最後に同期した後にストア側でも変更されたメモリファイルをエージェントが変更した場合、ワーカーは次の同期でストアのバージョンを保持し、ローカルファイルをそれで上書きして、警告をログに記録します。write ツールと edit ツール自体は成功し、エージェントにエラーは届きません。エージェントの変更がまだ適用可能であれば、同期後にファイルを再度読み取り、もう一度変更を加えることができます。

メモリマウントのトラブルシューティング

ワーカーは、マウントやバックグラウンド同期の失敗をセッションに報告するのではなく、ログに記録します。エージェントに届くのは読み取り専用による拒否のみで、ツールエラーとして届きます（読み取り専用ストアと競合を参照）。ワーカーがセッションを取得した際にメモリストアをマウントできない場合、ワーカーはそのワークアイテムを失敗させます。セッションはエラーイベントを発行せず、アイドル状態のままになります。

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

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

1. 1

   エージェントでツールを宣言する

   エージェントの tools に、ワーカーが登録するツールと name が一致する custom エントリを追加します。宣言の完全な形式についてはカスタムツールを参照してください。

   {
     "type": "custom",
     "name": "get_order_status",
     "description": "Look up an order in the internal fulfillment system by order ID.",
     "input_schema": {
       "type": "object",
       "properties": {
         "order_id": { "type": "string", "description": "The order ID" }
       },
       "required": ["order_id"]
     }
   }

   
2. 2

   実装をワーカーに登録する

   組み込みツールセットと並べて、ワーカーの tools ファクトリ（SDKヘルパーを参照）を通じてツールを渡します。

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from anthropic import AsyncAnthropic, beta_async_tool
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   
   
   @beta_async_tool
   async def get_order_status(order_id: str) -> str:
       """Look up an order in the internal fulfillment system by order ID."""
       # ワーカーホスト上で実行されます:サンドボックスから到達できるものは何でも呼び出せます。
       return f"Order {order_id}: shipped"
   
   
   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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
           ).run()
   
   
   asyncio.run(main())

ワーカーは、自身に登録されたツールにのみ応答します。エージェントで宣言されているが、どのワーカーにもクライアントにも登録されていないカスタムツールは、何かがその結果を投稿するまで、セッションを 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）を設定してください。

1. 1

   エージェントでサーバーのツールを宣言する

   MCPサーバーのツールを一覧取得し、それぞれを custom ツールとして宣言します。MCPの name、description、inputSchema は、カスタムツールのフィールドに1対1で対応します。サーバーがツール一覧をページ分割する場合は、すべてのページを宣言してください。ワーカーも同じページを一覧取得する必要があります。

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   from typing import Any, cast
   from anthropic import AsyncAnthropic
   from anthropic.types.beta import BetaManagedAgentsCustomToolParams
   from mcp import ClientSession, types
   # mcp >= 1.24 が必要です（streamablehttp_client が streamable_http_client に改名されました）。
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
       # MCPのフィールドはカスタムツール宣言に1対1で対応します。cast は
       # スキーマ辞書をそのままSDKの型付きパラメータに渡します。
       return {
           "type": "custom",
           "name": tool.name,
           "description": tool.description or tool.name,
           "input_schema": cast(Any, tool.inputSchema),
       }
   
   
   async def main() -> None:
       # これはワーカーホストではなく、エージェントを作成する場所で実行してください。
       # Claude APIキー（ANTHROPIC_API_KEY）で認証します。
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write) as mcp_session,
           AsyncAnthropic() as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           agent = await client.beta.agents.create(
               name="Internal tools agent",
               model="claude-opus-5",
               tools=[
                   {"type": "agent_toolset_20260401"},
                   *[to_custom_tool(tool) for tool in listed.tools],
               ],
           )
           print(agent.id)
   
   
   asyncio.run(main())

2. 2

   ワーカーからツールを提供する

   起動時に同じMCPサーバーに接続し、MCPヘルパーでそのツールを変換して、組み込みツールセットと並べて登録します。ワーカーの存続期間中、1つのMCPセッションを開いたままにしてください。

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from datetime import timedelta
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   from anthropic.lib.tools.mcp import async_mcp_tool
   from mcp import ClientSession
   # mcp >= 1.24 が必要です(streamablehttp_client が streamable_http_client に改名されました)。
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   async def main() -> None:
       environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
       environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
       # 起動時に一度だけ MCP サーバーに接続し、ワーカーの存続期間中は
       # セッションを開いたままにします。タイムアウトにより、ハングしたツール呼び出しは
       # 停止したままになるのではなくエラー結果として返されます。
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
           AsyncAnthropic(auth_token=environment_key) as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
           ).run()
   
   
   asyncio.run(main())

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

• ツールは宣言するものであり、実行時に検出されるものではありません。 ワーカーは起動時にMCPサーバーのツールを一度だけ一覧取得し、実行中のセッションにツールを追加することはできません。サーバーのツールが変更された場合は、エージェント上で、またはエージェント設定の更新を通じてアイドル状態のセッション上で再度宣言し、ワーカーを再起動してください。
• 名前と説明はManaged Agents APIに適合する必要があります。 カスタムツール名はエージェントごとに一意で、英字、数字、アンダースコア、ハイフンを使用します（1〜128文字）。空でない説明が必須です。また、エージェントの 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 になります。ワーカーの確認を待たずにワークアイテムを即座に stopped とマークするには、リクエストボディで 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)

次のステップ