Todo と clarify
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/todo-and-clarify/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
todo と clarify は、Ankole.Sessions.Tools.Session が所有するコントロールプレーン側の組み込みツールです。セッション Driver が引数を検証し、モデル向けの実行結果を AIGateway に保存したうえで現在の Run の状態へ反映します。
タスクリスト
todo ツールは、タスクリストの読み取り、全体の置き換え、または項目 ID 単位でのマージ更新を行います。各項目のステータスは pending、in_progress、completed、cancelled の 4 種類で、1 回の宣言につき最大 256 項目まで指定できます。システムプロンプトの指示では、3 ステップ以上の複雑な作業で todo を活用し、優先度順に並べること、in_progress を常に 1 項目だけに絞ること、完了したら即座に更新すること、失敗時には軌道修正した項目を追加することが求められます。
タスクリストは Ankole.Sessions.Run に紐づく実行中の作業状態です。障害復旧時には、現在の Run の履歴に記録されている成功済みのツール呼び出しからリストが再構築されます。新しい Session が別の Session のタスクリストを引き継ぐことはありません。Session をまたいで共有すべき知見は Brain に保存します。
1 つの判断質問
clarify ツールは、最終成果物の方向性や次のアクションを決めるためにどうしてもユーザーの確認が必要な場面に限り、それ単体で文脈が伝わる質問を 1 つ提示します。Agent はまず今回の依頼内容と過去の会話履歴を確認し、すでに示されている希望を聞き直さないようにします。また、安全で低リスクな既定値を選べる場合は、作業を止めずにそのまま進めます。
回答形式には、自由記述または互いに重複しない 2〜4 個の選択肢を指定できます。文字数上限は、質問文が 2,000 文字、選択肢ラベルが 200 文字、任意の補足説明が 500 文字です。実行を見送ることができる操作については、「何もしない(見送る)」ための選択肢も含めます。
呼び出しが成功すると、正規化された質問と選択肢が記録され、その時点で現在の Turn が終了します(同じ Turn 内で追加のツール呼び出しや通常の最終応答は出力されません)。ネイティブの Pod Chat では、コントロールプレーンが rich_content["clarify"] にスナップショットを保存して対話型の ChoiceCard として描画し、Delivery のインタラクションチェックポイントが pending -> answered | superseded の状態遷移を管理します(同じ Agent が新しい質問を出すと、未回答だった古い質問は superseded に遷移します)。ルームメンバーは ChoiceCard 上で選択肢をクリックするかテキストを入力して回答でき(先着優先ロックにより、後から競合した回答には HTTP 409 が返されます)、Pod Chat や外部チャットチャネルで通常の自由テキストメッセージを返信した場合も継続 Turn が開始されます。提示された質問と受理された回答は、永続的な会話履歴に記録されます。
構造化フォーム
回答に型付きの値が複数必要な場合、Agent は choices の代わりに fields を渡します。1 つのフォームには 1〜5 個のフィールドを含められます。各フィールドには、snake_case の id、80 文字以内の label、200 文字以内の任意のヒント help、既定値が true の required、任意の初期値 default があり、型は次のいずれかです。text(1 行または multiline。max_length は最大 1,000、既定値は 200)、number(integer、min、max、単位ラベル unit)、date(YYYY-MM-DD。min と max を任意で指定)、select または multi_select(value と label を持つ 2〜10 個の選択肢。multi_select では min_items と max_items も指定可能)、boolean。フォームには必須フィールドが少なくとも 1 つ必要です。ID や選択肢の値が重複している、最小値が最大値を上回る、既定値が無効、必須フィールドが 1 つもない、といった定義はコントロールプレーンが拒否し、Agent が呼び出しを修正できるよう理由を返します。
Pod Chat では、ChoiceCard がフォームを型に応じた入力欄として表示します。コントロールプレーンは送信のたびに改めて検証します。無効な送信では該当フィールドの下にエラーが表示され、質問は未回答のまま残ります。最初の有効な送信で回答が確定します。ルームにはフィールドラベルから組み立てた 1 行の要約が表示され、Agent はその要約と型付きの値(JSON。選択系フィールドは選択肢の value)を受け取ります。自分の言葉で答えたい場合は、引き続きコンポーザーで質問を開いて回答できます。
Feishu/Lark と Microsoft Teams では、返信カードにフォームがそのまま表示され、同じフォームを Pod で開くボタンも付きます。コントロールプレーンはカードからの送信をそのつど検証します。無効な送信では質問は未回答のまま残り、修正が必要なフィールドが Feishu/Lark ではトーストで、Teams では返信で示されます。最初の有効な送信で回答が確定し、Feishu/Lark と Teams ではフォームが回答の要約に置き換わります。そのほかの外部チャットチャネルには、質問、フィールドラベル、Pod へのリンク(/?interaction=<id>)が届きます。リンクを開くとダイアログにフォームが表示されますが、開いただけでは回答になりません。誰かがカードか Pod で有効なフォームを送信するか、チャネルで返信するまで、質問は未回答のまま残ります。
Background Job と運用
ネイティブの Codex Job は、これとは独立した独自の入力要求経路を持っています。人間の判断待ちになった Job は waiting_on_user 状態へ遷移して Worker の実行スロットをいったん解放し、オーナーから返信が届いた時点で処理を再開します。このライフサイクル契約の詳細については、Background Agent Jobs を参照してください。
なお、計画管理や Turn 終了の挙動を Console から切り替える設定フラグはありません。計画の立て方や質問の頻度を調整したい場合は、Agent のシステム指示(AGENTS.md)や有効な能力セットを見直してください。詳しくは Agents および Agent loop を参照してください。