本文へスキップ
Ankole

Worker

AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/worker-management/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。

すべての Agent は、自分専用の Worker と /workspace 配下の永続 Home を持ちます。Worker プロバイダーの種別、YAML 設定、および別枠で暗号化保存される認証情報は Console から管理します。どのプロバイダーを使うかは Agent の作成時に選択し、後から別のプロバイダーへ変更することはできません。異なるインスタンススペックを使い分けたい場合は、別の Worker プロバイダーを作成します。

WorkerProvider

1 つの WorkerProvider 設定がサイトスコープの計算プロバイダーを 1 つ定義し、プラットフォーム種別、YAML 設定、および個別に暗号化された認証情報を持ちます。異なるテナントの Agent が同じ WorkerProvider を共有することはできますが、実行時には各 Agent が自分専用の Worker インスタンス、永続 Home、キャッシュ、接続用認証情報を独立して保持します。

  1. Console → Settings → Worker providers を開き、New Worker provider を選択します。
  2. プラットフォーム種別を選び、サンプル YAML をもとにイメージ、インスタンス仕様、ストレージ、接続先エンドポイントを設定します。
  3. 専用の認証情報欄にプラットフォームのキーを入力して保存し、接続テストを実行します。
  4. いずれか 1 つの WorkerProvider をサイト既定に設定するか、Agent 作成時に毎回プロバイダーを明示的に選択します(既定プロバイダーがなく作成時にも指定しなかった場合、Agent の作成は拒否されます)。

サイト全体で既定に設定できる WorkerProvider は最大 1 つです。既定プロバイダーを変更しても既存の Agent の割り当ては変わらず、それ以降に新しく作成する Agent にのみ適用されます。スペックやリージョンを分けたい場合は同じ種別のプロバイダーを複数登録できます。なお、一度作成した後はプロバイダー ID、種別、ストレージ保存先、および各 Agent のプロバイダー選択を変更することはできません。また、いずれかの Agent Worker レコードから参照されているプロバイダーは削除できません。

WorkerProvider はあくまで指定プラットフォーム上で専用インスタンスをプロビジョニングするための構成であり、ある Agent の計算環境を別の Agent に使い回すことはありません。Agent の作成手順は Agents を、実行制御と復旧の内部設計は Agent Computer Worker を参照してください。

Agent ごとに 1 台の Worker

Agent を作成すると、選択したプロバイダーと Worker レコードを保存し、バックグラウンドで初回の Worker 起動を要求します。作成リクエストはインスタンスの準備完了を待ちません。アイドル解放後は、対話型の環境ツールまたは Background Agent Job(Codex)が必要になったときに再び Worker を要求します。通常のチャット応答や Workflow のモデル呼び出しはコントロールプレーン、Automation Job の公開済み Applet Action は ankole-function-runtime で実行され、Worker の再起動は必要ありません。

同一 Agent 内の複数 Session や Job は、同じ Worker インスタンスと Home を共有しつつ、/workspace 配下の個別のワークスペースディレクトリを使って動作します。開いている環境ワークスペースと実行中の Codex Turn はそれぞれ Worker スロットを 1 つ消費し、その上限は ANKOLE_MAX_CONCURRENT_SLOTS で決まります。なお、WorkerProvider を増やしたり別の Agent を追加したりしても、既存 Agent 1 体あたりの Worker スロット数や Background Agent Job の同時実行上限が増えるわけではありません。

Worker を表示する

Console → Workers を開くと、各 Agent に紐づくプロバイダー、現在のステータス、負荷状況、最終ハートビート、およびプラットフォームから返された直近のエラー理由を確認できます。

状態 意味
absent 実インスタンスは存在しません。作業が発生した時点で作成されます
starting 新しい世代(generation)を記録し、インスタンスの作成または接続確立を待っています
ready 接続が完了し、Turn の作業を受け付けられる状態です
stale 直前まで確立していた接続が切断された状態です
paused プロセス状態とメモリを保持したまま一時休止しています
draining 進行中の作業を終えて解放または新世代へ入れ替わるのを待っています
deleting インスタンスと専用ストレージの削除完了を待っています

起動がタイムアウトした場合は、同じ世代(generation)のまま再試行されます。プロビジョニング要求の成否が不明な間は待機を続け、書き込み元が二重になる(スプリットブレインを起こす)ような別インスタンスの重複作成は行いません。設定を変更する前に、必ず画面上の Reason 欄を確認してください。

Provider とストレージ

各プラットフォームの細かい制約、必要な認証情報、ネットワーク要件、および SQLite キャッシュの扱いについては、WorkerProvider とキャッシュディスク を参照してください。旧バージョンからの移行手順については、1.0 から 2.0 への更新 を参照してください。

種類 永続 Home の保存先 アイドル時の挙動
Docker Agent ごとのローカルボリューム コンテナを削除
Kubernetes 専用 PVC、または共有 PVC 内のサブディレクトリ Pod を削除
Cloudflare R2 上のディレクトリバックアップ バックアップ完了後にコンテナを削除
Vercel Agent ごとの専用 Drive サンドボックスを削除
Lambda MicroVMs EFS 上の Agent ディレクトリ メモリ状態を保持したまま休止
Function Compute Agent ごとの AgenticSpace または OSS プレフィックス メモリ状態を保持したまま休止

Vercel の sessionTimeoutSeconds は利用アカウントの上限時間内に収めてください(既定値は 86400 秒ですが、上限が 45 分のプランでは 2700 秒に設定します)。AWS Lambda では、稼働中および休止中の Worker に加え、ストレージ削除ヘルパー用のメモリクォータ枠も確保しておく必要があります。Alibaba Function Compute では休止からの再開時に Worker イメージ内の OSS 再接続ヘルパーを使用するため、必ずバージョンを揃えた Worker イメージとコントロールプレーンを組み合わせてデプロイしてください。

永続 Home のデータは、インスタンスの削除やイメージの更新を行っても維持されます。Codex のスレッド履歴は /workspace/.codex に、再構築可能な SQLite キャッシュは /var/cache/ankole/codex に配置され、Worker の明示的な再構築(rebuild)ではキャッシュ側だけが消去されます。なお、Docker のローカルボリュームはホストマシンのディスク障害には耐えられず、Cloudflare では強制停止が発生した場合に前回バックアップ以降の差分が失われる可能性があります。永続 Home と Unified Drive の両方を定期的にバックアップしてください。

解放、置換、削除

  • アイドル回収までの時間はプロバイダー YAML の idleReleaseAfter で指定します(全 6 種別とも既定値は 15m で、自動停止させない never も選択できます)。
  • メモリ保持型の休止に対応したプロバイダーではアイドル状態の Worker を休止させ、それ以外のプロバイダーでは永続ストレージと設定済みキャッシュボリュームを残してインスタンスだけを削除します。
  • コンテナイメージやインスタンススペックの変更は Worker がアイドルになったタイミングで新しい世代へ入れ替わりますが、プロトコルバージョンの変更時は即座に入れ替わります。また、古い構成のまま休止していたインスタンスは、次の作業を再開する前に入れ替えられます。
  • agent_workers.ready_timeout_seconds の既定値は 600 秒です。一度でも稼働を観測できたインスタンスだけを再構築対象とし、作成結果がまだ確定していないリクエストを勝手に終了扱いにすることはありません。
  • Agent を削除すると、稼働中インスタンスの完全終了を確認したうえで Home とキャッシュを消去し、最後にデータベース上の Worker レコードを削除します。

未準備の Worker を調べる

Worker がいつまでも ready にならない場合は、プロバイダーの認証情報、ストレージ設定、クォータ空き容量、および endpoints の到達性を確認してください。種別ごとの主な確認ポイントは、Docker なら ANKOLE_DOCKER_GID、Kubernetes なら RBAC Role・Pod イベント・PVC バインド状態、Cloudflare ならイメージ設定とトークン、Lambda ならビルド状態・ビルド IAM ロール・VPC コネクター・EFS マウント設定です。

手動でコンテナや Pod を停止する際は、プロバイダーが付与したラベルで対象 Agent を慎重に確認し、停止前に必ずログを取得してください。Kubernetes では通常の Pod 削除が完了するのを待ち、ノード障害時に --grace-period=0 などの強制削除で無理に回避しないでください。Docker 環境で手動削除する場合は、先に停止してから削除します。

docker stop CONTAINER_NAME
docker rm CONTAINER_NAME

手動削除した後も Home とキャッシュボリュームはそのまま残り、次に作業が必要になった時点でコントロールプレーンが新しいインスタンスを自動作成します(実行中だった Turn は中断され、それぞれの再試行ルールに従って処理されます)。ステータスが ready なのに作業が待たされる場合は、現在の負荷と同時実行スロットの上限を見比べてください。ANKOLE_MAX_CONCURRENT_SLOTS はプロバイダー YAML 内の環境変数で調整でき、変更後はアイドル時に入れ替わります。詳しくは 性能調整 を参照してください。