Workflow
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/workflows/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Workflow は、メイン Agent が有限で決定論的な編成プログラムを実行し、独立した複数のサブタスクをサブエージェントへ並行委譲するための機能です。多数の候補の並列レビュー、決まった情報源セットからの定型項目抽出、独立した複数視点での評価比較、あるいは最終統合前の検証ステップなどに適しています。
Workflow は現在のチャット会話から開始され、即座に run_id を返します。裏側でサブタスクが動いている間も、同じ会話でそのままやり取りを続けられます。Workflow が完了(または失敗)すると Ankole が元の会話を起こし、メイン Agent が集約結果を受け取って後続の作業を進めます。
適切な実行形態を選ぶ
| やりたいこと | 適した機能 | 理由 |
|---|---|---|
| 現在の会話の文脈だけで完結する短い作業 | メイン Agent の Turn | 会話コンテキストとメイン Turn の全ツールセットをそのまま使えます。 |
| 件数の決まった独立チェックの並列実行、または定型の多段階分析 | Workflow | 境界の明確なサブエージェントタスクを並列実行し、1 つの集約結果にまとめます。 |
| ファイル操作、専用ワークスペース、途中の対話、人間の追加入力を伴う長時間タスク | Background Agent Job | 一時停止や再開が可能な永続的な Codex スレッドとワークスペースを持てます。 |
| スケジュールや Webhook をきっかけに動く機械的なチェック処理 | Automation Job | モデルの推論判断が不要な場面で、モデル Turn を回さずに Function Runtime で Applet Action を実行できます。 |
Workflow の編成プログラムは固定されており、サブエージェントが外部 Webhook を購読したり、clarify を直接呼び出したりすることはできません。メイン Agent の判断が必要な場合は attention: true を付けて sleep し、タスクメッセージで回答を受け取れます。編集可能なワークスペースと対話的な実行スレッドが必要な作業には Background Agent Job を使ってください。
Agent に Workflow を開始させる
依頼する際は、「有限の入力対象」「各サブタスクで行うこと」「完了条件」「最終出力の形式」を具体的に伝えます。たとえば次のように指示します。
Run this as a Workflow. Review these 40 proposals in parallel against the five
criteria below. Return one JSON result with every verdict, the failed reviews,
and a final shortlist. Do not expand beyond these 40 proposals.
ユーザーが自分で JavaScript コードを書いたり API を叩いたりする必要はありません。メイン Agent が編成プログラムを組み立てて実行を開始します。その際、Agent は Run あたりの同時実行数上限、サブエージェント呼び出し総数の上限、および Run 全体の既定 model_profile(解決可能な light・primary・heavy ティアまたは名前付きカスタムプロファイル。省略時は primary)を指定でき、さらに個々の agent(prompt, options) 呼び出しでも options.model_profile で段階ごとにティアを切り替えられます。
開始ツールは run_id と初期ステータス running を返します。メイン Agent はポーリングで完了を待ち続けてはならず、いったん Turn を終えて通常の会話を続けられる状態を保ち、必要に応じて後から進捗を確認します。
編成の実行方法
編成プログラムは不変の JSON 引数 args を受け取り、agent(prompt, options) 関数を呼び出してサブエージェントを起動します。Promise.all で束ねた呼び出しは並列に実行され、通常の JavaScript の条件分岐を使って、前段の結果が出揃ってから後段の検証ステップや統合ステップへ進むといった構成も組めます。なお、すべてのコレクション操作とループには、コード上で明確に確認できる有限の上限が必要です。
次の簡略化した例では、最大 20 件の項目を並列レビューし、失敗した呼び出し(null)を除外したうえで成功分だけを最終要約にまとめています。
const items = args.items.slice(0, 20)
const reviews = await Promise.all(
items.map(item =>
agent(`Review this item: ${JSON.stringify(item)}`, {
label: `review-${item.id}`,
schema: {
type: 'object',
properties: {
id: { type: 'string' },
verdict: { type: 'string', enum: ['accept', 'reject'] },
reason: { type: 'string' }
},
required: ['id', 'verdict', 'reason'],
additionalProperties: false
}
})
)
)
const successful = reviews.filter(review => review !== null)
const summary = await agent(`Summarize these reviews: ${JSON.stringify(successful)}`, {
label: 'summary'
})
return { reviews, summary }
プログラム本体と args は Run 開始後に変更できません。コントロールプレーンは編成ステップを進めるたびに、ステートレスな ankole-function-runtime サービスの POST /v1/program/run を呼び出します。各ステップはネットワーク、ファイルシステム、環境変数、サブプロセス、FFI の権限をすべて遮断したクリーンなワーカー上で実行され、Math.random() や Date.now() にも決定論的な固定シード値が使われます。サブエージェントの応答を待っている間、関数ランタイムのワーカーが常駐し続けることはありません。
コントロールプレーンが再起動した場合でも、6 MiB の永続メモ(memo)予算の範囲内で保存済みの完了タスク結果を使って編成プログラムを最初からリプレイし、続きから再開します。すでに成功して記録されたタスクが再実行されることはありませんが、リプレイ時に agent() の呼び出し順序や引数が前回と食い違った場合は Run 全体がエラー終了します。なお、実行途中で中断された未完了タスクは再試行されることがあるため、サブタスクの処理を「厳密に 1 回だけ(exactly-once)」とみなさないでください。
各サブエージェントが使えるもの
各 agent() 呼び出しは、Agent Computer Worker のスロットを消費せず、コントロールプレーン上の独立した会話コンテキスト(wf_task:<call_id>)として実行されます。サブエージェントに渡されるのは、親 Agent の識別情報・AGENTS.md とそのタスク用のプロンプトだけです。編成プログラム側で明示的にプロンプトへ埋め込まないかぎり、元のチャット履歴や他の並列タスクの結果が見えることはありません。
Workflow タスクは Web ツール(web_search / web_fetch)と、Brain が有効な場合の読み取り専用ツール(recall および entity)を利用できます。シェル、ファイル操作、MCP、Skill、Brain への書き込み、スケジュールの各ツールは直接公開されず、サブエージェントの中からさらに別の Workflow をネスト起動することもできません(編成のネスト深度は 1 固定です)。
どうしてもワークスペース上での作業や数時間規模の処理が必要な場合は、タスク内から Background Agent Job(create_background_job、show_background_job_details、send_message_to_background_job、stop_background_job)へ作業を委譲し、sleep(1 分〜48 時間、1 呼び出しあたり最大 16 回)を使って同時実行スロットを解放したまま休眠できます。休眠中のタスクは、委譲先 Job のライフサイクルイベント、親からのメッセージ送信、または指定期限の到来によって再起動します。sleep 時に attention: true を指定するとメイン Agent へ通知が飛び、休眠メモの確認と返信を促せます。作業がすべて完了したら、submit_result を呼んで結果を提出します。
1 回の起動区間(wake 区間)につき、各呼び出しは最大 3 回までタスクを試行できます。正常に提出された呼び出しはその提出値に解決され、試行回数を使い切った呼び出しは null に解決されます。そのため、1 つのサブタスクが失敗しても Workflow 全体が即座に失敗することはなく、編成プログラム側で失敗分を記録して残りの処理を続行したり、最終結果に未完了の理由を添えて返したりできます。
構造化結果を必須にする
agent() のオプションで結果の JSON Schema を宣言すると、Ankole は生成した submit_result ツールを Provider の strict モードで送信し、提出された値をコントロールプレーン側でも再検証します。スキーマ違反で拒否された場合でもタスクは終了せずそのまま継続するため、サブエージェントはその場で出力を修正して再提出できます。
使用できるスキーマは OpenAPI 3 JSON Schema の厳格なサブセットに限定されます。ルートおよび各要素には object、array、string、number、integer、boolean のいずれか単一の非 null 型を指定します。ネストされたものも含め、すべての object では必ず properties を定義し、全プロパティ名を required に列挙し、かつ additionalProperties: false を設定しなければなりません。省略可能なオブジェクトフィールド、nullable 値、ユニオン型、$ref、および oneOf / anyOf / allOf はサポートされていません。
スキーマ指定を省略した場合、各タスクは文字列(string)を返します。編成プログラムの末尾では必ず最終的な集約結果を return してください(文字列ならそのまま最終テキストになり、それ以外の JSON 値はシリアライズされた JSON 文字列として返されます)。
Run の表示、メッセージ送信、一覧、キャンセル
進行中や完了済みの Run を操作したいときは、メイン Agent に依頼して次のツールを実行させます。
show_workflow:現在のステータス、タスク件数、最大 32 件の実行中タスク(休眠時のnote、attention、再起動期限を含む)、最大 10 件の失敗サマリー、および終了エラーを返します。完了した最終結果はバイトオフセット0から最大8,000UTF-8 バイト単位のセグメントで読み取れます。send_message_to_workflow_task:run_idとcall_seqで指定した実行中タスクへ非同期メッセージを送り、休眠中のタスクを即座に起こしたり、attention: trueで待機しているタスクへ指示を返したりします。list_workflows:その Agent の実行中または終了済み(completed、failed、cancelled)の Run を 1 回につき最大 32 件まで一覧取得します。cancel_workflow:べき等なキャンセル操作です。新規サブタスクの起動や遅延到着した結果による Run の復活を防ぎ、実行中のタスク Turn と委譲先の Background Agent Job に停止を要求します(進行中のモデル呼び出しが完全に止まるまでには少し時間がかかる場合があります)。
正常完了またはエラー終了した Run は元の会話を自動的に起こしますが、手動キャンセルした Run は完了イベントを発火しません。キャンセル後の最終状態を確認したい場合は、Agent に状態照会を依頼してください。
また、Console ホーム画面のバックグラウンドアクティビティ欄でも、読み取り専用の Workflow 稼働状況(site_console:agent:<agent_uid>:workflow 権限にもとづく実行中 call、ステータス別件数、休眠メモ、期限、attention フラグ、エラーサマリー)を確認できます。Run の新規開始、タスクへのメッセージ送信、完全な結果の取得、およびキャンセル操作には、メイン Agent の Workflow ツールを使用します。
コストと容量を制御する
各サブタスクの 1 試行ごとに 1 回分の完全なモデル Turn が回り、必要に応じて従量課金の Web ツール呼び出しも発生します。同時実行数の上限を変えても変化するのは完了までの所要時間だけで、呼び出し総数が減るわけではありません。必ず有限の入力件数から呼び出し上限を見積もり、各サブタスクに渡すプロンプトと返却データのサイズをコンパクトに保ってください。
| 制限項目 | 既定値 | ハード上限 |
|---|---|---|
| 1 Run あたりの同時実行タスク数 | 8 | 32 |
| 1 Agent あたりの実行中 Workflow タスク総数 | 8 | 64 |
| 1 Run に含まれるサブエージェント呼び出し総数 | 32 | 1,024 |
| 各 wake 区間での最大試行回数 | 最大 3 | 3 |
| 1 サブエージェント呼び出しあたりの最大休眠回数 | — | 16 |
| 1 回あたりの休眠時間 | — | 1 分〜48 時間 |
| 保存される編成プログラムのサイズ | — | 256 KiB |
保存される args のサイズ |
— | 64 KiB |
| 1 回の呼び出し引数オブジェクトのサイズ | — | 8 KiB |
| 1 通の親タスクメッセージのサイズ | — | 8 KiB |
| 1 回の提出結果データのサイズ | — | 24 KiB |
| 永続メモ(memo)の合計予算 | — | 6 MiB |
| 最終集約結果のサイズ | — | 1 MiB |
表の先頭 3 項目については、管理者が AppConfigure からインスタンス既定値を調整できます(有効な範囲内の同時実行数・呼び出し数は、保存時に設定上限までに抑えられます。ハード上限の範囲外にある値は拒否されます)。なお、Workflow 単位での一括トークン上限や金額上限はなく、各サブタスクに対して通常の Turn ごとの反復回数・出力トークン数・無通信タイムアウトの上限が個別に適用されます。コスト面の管理については コスト管理 も参照してください。
もしデータサイズの上限に達する場合は、並列展開数(fanout)を絞るか、各サブタスクから返す要約をより短くするか、あるいは入力データを複数の Workflow Run に分割してください。編成プログラムや入力 args を変更したい場合は、新しい Run として作り直します(失敗した Run のコードを後から書き換えて途中再開することはできません)。