本文へスキップ
Ankole

Worker CLI の機能

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

Ankole の機能の中には、モデルに直接公開するツール定義ではなく、Agent Computer 上のシェルコマンド(CLI)として提供されているものがあります。Agent は kubectl を使うのと同じ感覚でシェルからこれらを呼び出します。ankole-pod(pages.*、base.*、applet build|publish|pull、jobs.*)、ankole-files、ankole-browser、および Webhook エンドポイント操作コマンドはいずれもこの形態をとっています。

このページでは、どのような機能を CLI として実装すべきかという基準と、ツール登録・Skill インデックス・システムプロンプトへの常駐記述なしに Agent が機能を正確に見つけて使えるようにする「段階的開示アーキテクチャ」について説明します。

CLI が正しい形態である場合

次の条件をすべて満たす機能は、モデルツールではなく CLI として提供するのに適しています。

  • より大きなシェルワークフローの中で他のコマンドと組み合わせて使われ、スクリプトや Background Agent Job からも同じように呼び出せる必要があること。
  • 特定の判断経路に入ったときにだけ必要になること(たとえば Webhook を一度も作成しない Agent は、create-webhook-cli の存在すら知る必要がありません)。
  • 複雑な JSON スキーマをモデルに埋めさせる必要がなく、いくつかのコマンドラインフラグだけで入力を渡せること。

モデルに直接見せるツール定義は、使われない Turn でも毎回コンテキストウィンドウを消費します。一方、CLI であれば Agent が該当する作業経路に入るまでコンテキストを一切消費しません。

開示アーキテクチャ

ツール登録や Skill インデックスの代わりに、次の 3 つのルールで発見性と正確性を担保します。

1. --help 自体を正式な仕様書にする。 CLI の --help 出力には、その機能を正しく使うために Agent が知るべき情報をすべて盛り込みます(機能の概要、信頼モデル、動作保証、そのまま参考にできる完全な実行例)。ヘルプはバイナリと一緒に配布されるため、呼び出し元はその実装バージョンに同梱された説明を読めます。前提知識のない読み手を想定し、細かな内部手順ではなく「目的と制約」を明確に記述してください。実装例としては create-webhook-cli --help が参考になります。

2. 意思決定の分岐点に一文のポインタを置く。 Agent がその機能の必要性に気づけるよう、関連する判断を行う場所(隣接ツールの説明文、特定の外部サービス連携 Skill、あるいは別 CLI の --help など)に一文だけの案内ポインタを置きます。各ポインタには、特定の手法へ誘導する表現は入れず、「どのような条件のときに関係するか」と「どの --help を読めばよいか」だけを中立に記します。CLI 形態で提供するすべての機能には、関連タスクの途中で Agent が必ず通る箇所に最低 1 つのポインタが必要です。つまり、「どういう場面でその機能が意味を持つか」という経路そのものから、ポインタを置くべき場所が自ずと決まります。

共通の仕様は --help、外部サービスの知識はプラグイン Skill に記述します。 CLI 全体に適用する規則は --help にまとめます。Skill は外部サービスの操作仕様を説明し、必要に応じてプラットフォーム機能を案内します。たとえば Toolkit のアップロード操作には Pod ファイル参照が必要なため、Skill は pod-content を使って Worker のファイルを先にアップロードするよう案内します。

Automation Jobs

Automation Job は Function Runtime で公開済み Applet Action を実行します。Agent は ankole-pod applet で Applet をビルド・公開し、ankole-pod (jobs.*) で Action の確認、Job の作成・設定、スケジュールと Webhook の管理、Run の確認を行います。使用前に ankole-pod --help を参照してください。

サーバーは {routes, actions} を公開します。Action がハンドラー、冪等性、同時実行方針を宣言し、ctx.signal と ctx.job.config を読み、ctx.state で状態を保存します。continueSlice() で同じ Run の処理を分割できます。外部呼び出しは AnkoleRuntime.mcp、チーム権限では AnkoleRuntime.admin.mcp を使います。

自動化パネルと SDK の useAppletJobs()・useJobSources(jobID) も同じ操作を提供します。テスト配信後は Run の入力、結果、エラー、ログを確認してください。Automation Jobsに権限と復旧方法を説明しています。

新しい CLI 機能の要件

新しく CLI 機能を追加する際は、次のルールに従ってください。

  • 実装コードは app/agent_computer/src/cli/ 配下に、コマンドファミリごとに 1 ディレクトリずつ配置します。
  • --help および -h 指定時は、アクティブな Turn やネットワーク接続に一切依存せず、完全な仕様ドキュメントを標準出力へ出して終了コード 0 で終了します。コマンドラッパーが先頭にサブコマンドを付与する場合があるため、引数配列のどの位置にヘルプフラグがあっても検出できるようにしてください。
  • 引数エラー時には仕様全文ではなく、簡潔な usage 文字列だけを返します。
  • その機能が必要になる各意思決定箇所に案内ポインタを 1 文追加します。特定の選択へ誘導する表現は避け、適用条件と参照すべき --help コマンドだけを明記してください。
  • プラグイン Skill でその CLI を特定の外部サービスと組み合わせる場合は、Skill の冒頭で --help を案内し、Skill 本文には外部サービス固有の差分だけを記述します。