セルフホストワーカーリファレンス
セルフホスト型サンドボックスワーカーのリファレンス:ant CLIフラグ、環境変数、ホスト要件、ファイルシステムパス、SDKヘルパーオプション。
このページでは、self_hosted環境を処理する事前構築済みのワーカーについて説明します。タスク指向のガイドについては、まずセルフホスト型サンドボックスとセルフホストワーカーをデプロイするを参照してください。
CLIコマンドとフラグ
| コマンド | 説明 |
|---|---|
ant beta:worker poll | 環境のキューからワークアイテムを取得し、各セッションをプロセス内で実行します。--on-workを指定すると、代わりにワークアイテムごとにスクリプトを呼び出します。 |
ant beta:worker run | 取得済みの1つのセッションを処理して終了します。セッションごとのサンドボックスのエントリポイントとして使用します。 |
| フラグ | 説明 |
|---|---|
--environment-id | ワークをポーリングする環境。ANTHROPIC_ENVIRONMENT_IDからも読み取ります。 |
--environment-key | この環境に対してワーカーを認証します。ANTHROPIC_ENVIRONMENT_KEYからも読み取ります。 |
--workdir | ワーカーがスキルをダウンロードし、ツールがファイルを読み書きするディレクトリ。デフォルトは.(カレントディレクトリ)です。ワーカーの起動前にこのディレクトリが存在している必要があります。 |
--on-work | ツールをプロセス内で実行する代わりに、取得したワークアイテムごとに呼び出すスクリプト。セッションの詳細を環境変数として、ワークアイテムをJSONとして標準入力で受け取ります。 |
--max-idle | セッションがアイドル状態の間、ant beta:worker runが終了する、またはant beta:worker pollが次のワークアイテムに移るまでワーカーが待機する時間。requires_actionの停止理由によるアイドル時間はカウントされません。デフォルトは60sです。タイムアウトを無効にするには0に設定します。--on-workスクリプトを使用する場合、ant beta:worker pollはこのフラグを無視します。代わりに、スクリプトが起動するant beta:worker runコマンドにこのフラグを渡してください。 |
--log-format | ログの出力形式。構造化ログの取り込みにはjsonを使用します。デフォルトはtextです。 |
環境変数
| 変数 | 説明 | 設定者 |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | ワーカーが処理するキューを持つ環境。 | お客様がワーカーホスト上で設定します。ポーラーはこれを--on-workスクリプトに渡します。 |
ANTHROPIC_ENVIRONMENT_KEY | ワーカーをそのキューに対して認証します。 | お客様がワーカーホスト上で設定します。ポーラーはこれを--on-workスクリプトに渡します。 |
ANTHROPIC_SESSION_ID | 取得したワークアイテムが表すセッション。 | ポーラーが--on-workスクリプト用に設定します。 |
ANTHROPIC_WORK_ID | 取得したワークアイテム。 | ポーラーが--on-workスクリプト用に設定します。 |
ANTHROPIC_WORK_SECRET | ワークアイテムの、そのセッション用のシークレット。 | お客様が設定します。ポーラーは設定しません。ワークアイテムのシークレットを転送するを参照してください。 |
ANTHROPIC_BASE_URL | デフォルトのAPIエンドポイントを上書きします。省略可能です。 | お客様がワーカーホスト上で設定します。 |
ANTHROPIC_WEBHOOK_SIGNING_KEY | 受信したWebhookペイロードを検証します。 | お客様がWebhookハンドラーホスト上で設定します。 |
ホスト要件
| ワーカー | 要件 |
|---|---|
| すべてのワーカー | /bin/bash がまさにそのパスに存在するLinuxまたはmacOSホスト。ワーカーのbashツールは PATH を参照せずに直接これを実行します。macOSでは、これはシステムのBash 3.2です。 |
| TypeScript SDK | PATH上のunzipとtar、およびNode.js 22以降。 |
| PythonおよびGo SDK | 追加のバイナリは不要です。これらのSDKはアーカイブの展開に標準ライブラリを使用します。 |
メモリストアには独自の要件が追加されます。
macOSではルートボリュームが読み取り専用であるため、mkdir で /workspace を作成できません。ワーカーの作業ディレクトリを、ホームディレクトリ内の workspace ディレクトリなど、書き込み可能なディレクトリに設定してください。macOSでメモリストアを使用するには、まずmacOSホストを準備してください。
サンドボックスのファイルシステム
| パス | 内容 |
|---|---|
/workspace | セルフホスト型サンドボックスの各ページのサンプルで使用している作業ディレクトリ。これはワーカーのデフォルトではありません。--workdirまたはworkdirを設定しない限り、ワーカーはカレントディレクトリを使用します。Anthropicのクラウドサンドボックスでは、スキルとリポジトリを/workspaceに保持します。別の作業ディレクトリを使用する場合は、Claudeがスキルファイルを見つけられるようにエージェントのシステムプロンプトを更新してください。 |
<workdir>/skills/<name>/ | エージェントのダウンロード済みスキル。 |
/mnt/memory/<store>/ | アタッチされた各メモリストアのローカルコピーで、ストアごとに1つのディレクトリ。APIは、セッションのメモリストアリソースのmount_pathフィールドで各ディレクトリのフルパスを返します(例:/mnt/memory/user-preferences/)。 |
ワーカーはセッションを取得したときにメモリストアのディレクトリを作成します。そのセッションの処理を終えたとき、またはワーカーを正常に停止したときに、これらのディレクトリを削除します。削除されるのはローカルコピーのみで、メモリはストアに残ります。
スキルには、エージェントが直接実行できる実行可能ファイルを含めることができます。CLIおよびSDKのワーカーは、スキルバンドルを展開する際に、バンドルに記録された実行権限を保持します。スキルを自分でダウンロードする場合は、実行権限も自分で設定してください。
ワーカーがセッションの処理を終えるタイミング
ワーカーは、次のいずれかの場合にセッションの処理を終えます:
- セッションが終了した場合。
- セッションのワークアイテムを停止した場合。
- セッションがワーカーのアイドル制限の間アイドル状態のままだった場合。セッション自体は開いたままです。その後、ユーザーメッセージなどの新しいイベントを送信すると、同じワーカーまたは別のワーカーがセッションを取得します。そのワーカーはストアを再度ダウンロードします。
アイドル制限はデフォルトで60秒です。変更するには、ant CLIワーカーの場合は--max-idleを、EnvironmentWorkerの場合はmax_idleを使用します。cma-sandboxes Helmチャートは、代わりに30分の制限でワーカーを起動します。この制限を変更するには、チャートのsandbox.idleTimeout設定を変更してください。
最終成果物
セルフホスト型サンドボックスには/mnt/session/outputsディレクトリがありません。Anthropicのクラウドサンドボックスでは、セッションのシステムプロンプトがエージェントに最終成果物をそこへコピーするよう指示します。セルフホスト環境では、システムプロンプトからその指示が省略されます。最終成果物はエージェントが書き込んだ場所(通常は作業ディレクトリ配下)に残り、ワーカーはそれらをアップロードしません。
最終成果物を1か所に集めるには、エージェントのシステムプロンプトでディレクトリのフルパスを指定してください。ワーカーのファイルツールが書き込めるディレクトリを選択してください:
- 作業ディレクトリ内: たとえば、作業ディレクトリが
/workspaceの場合は/workspace/outputs。 - その他の場所(SDKワーカーのみ): ディレクトリを
allowed_rootsに追加します。AgentToolContextとエージェントツールセットを参照してください。
SDKヘルパー
Python、TypeScript、Go SDKは、制御レベルの異なる3つのヘルパーを提供します:
| ヘルパー | 機能 | 使用する場面 |
|---|---|---|
EnvironmentWorker | ポーリング、セットアップ、ツールの実行をエンドツーエンドで処理します。 | ほとんどの場合。 |
work.poller() | ワークキューをポーリングし、取得した各セッションを渡します。 | 各セッションの処理方法を自分で決定する場合。たとえば、ツールをプロセス内で実行する代わりにサンドボックスを起動する場合など。 |
client.beta.sessions.events.tool_runner() | セッションIDとツールリストを受け取り、単一セッションのツール呼び出しを実行します。 | すでにワークを取得済みで、ツールの実行のみが必要な場合。 |
EnvironmentWorker
| メソッド | 説明 |
|---|---|
run() | 無期限に実行され、到着したセッションを順次処理します。 |
handle_item() | ポーラーによってすでに取得された単一のワークアイテムを処理します。ポーラーはant beta:worker poll --on-workでも独自のコードでもかまいません。このメソッドは、ワーカーがそのアイテムのセッションの処理を終えたときに戻ります。work_id、session_id、environment_id、work_secretを渡すことができます。省略したものについては、メソッドが対応するANTHROPIC_*変数を読み取ります。 |
| オプション | 説明 |
|---|---|
tools | セッションのAgentToolContextを受け取り、ツールリストを返すファクトリ。デフォルトは標準のエージェントツールセットです。 |
max_idle | セッションの処理を終えるまでに、セッションがアイドル状態の間ワーカーが待機する時間。requires_actionの停止理由によるアイドル時間はカウントされません。デフォルトは60秒です。5分間待機するには、300に設定します。制限を無効にするには、Noneに設定します。 |
memory_sync_interval | セッション実行中に、アタッチされたメモリストアを同期する間隔の最短時間。ワーカーはタイマーではなく、サンドボックス内で実行されるツールの呼び出しのたびに間隔を確認します。デフォルトは15秒です。同期間隔を参照してください。 |
memory_sync_deletions | エージェントがローカルで削除したファイルをストアからも削除するかどうか。削除を参照してください。 |
EnvironmentWorkerはAgentToolContextとツールセットを自動的に管理します。ツールリストをカスタマイズするには、toolsファクトリを渡します:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool
@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:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
# エージェントが呼び出せるすべてのツールを列挙します。ワーカーはそれ以外のツールには応答しません。
tools=lambda env: [beta_bash_tool(env), get_order_status],
)
task = asyncio.create_task(worker.run())
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())ワークポーラー
| オプション | 説明 |
|---|---|
drain | 新しいワークを待たずに、キューが空になった時点でポーリングを停止するかどうか。 |
block_ms | 各ポーリングが戻るまでにワークの到着を待機する時間(ミリ秒単位)。1から999の間である必要があります。ヘルパーは自動的に再ポーリングします。非ブロッキングのチェックを行うには None を渡します。デフォルトは999msのロングポーリングです。 |
reclaim_older_than_ms | 取得されたものの、このミリ秒数以内に確認応答されなかったワークアイテムを再取得します。 |
auto_stop | ループ本体が各ワークアイテムの処理を終えた時点で、ポーラーがそのワークアイテムの停止シグナルを送信するかどうか。デフォルトはTrueです。この表の後に示す2つの場合はFalseに設定します。 |
次の2つの場合は、auto_stopをFalseに設定します:
- ループが
handle_item()を呼び出す場合。このメソッドは自ら停止を送信します。 - ループがアイテム用にサンドボックスを起動して次に進む場合。そのサンドボックス内のワーカーは、
ant beta:worker runやhandle_item()と同様に、セッションのワークが終了したときに停止を送信する必要があります。
完全な例については、SDKポーラーからサンドボックスを起動するを参照してください。
セッションツールランナー
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)AgentToolContextとエージェントツールセット
AgentToolContextはツール呼び出しの実行コンテキストです。作業ディレクトリとパスポリシーを定義し、セッションのスキルをダウンロードできます。
| オプション | 説明 |
|---|---|
allowed_roots | 作業ディレクトリに加えて、ファイルツール(read、write、edit、glob、grep)がアクセスできるディレクトリ。 |
read_only_roots | writeとeditがパスを拒否するディレクトリ。 |
EnvironmentWorkerは、セッションのメモリストアのディレクトリを自動的にallowed_rootsに追加し、access: "read_only"でアタッチされたストアのディレクトリをread_only_rootsに追加します。
この制限はファイルツールのみに対するガードレールであり、サンドボックスではありません。bashは制限されません。
beta_agent_toolset_20260401(env)はAgentToolContextを受け取り、標準のツール実装(bash、read、write、edit、glob、grep)を返します。
このページは役に立ちましたか?