カスタムコンテキスト（state）または Session の直近のコンテキストに基づいて構造化された質問に回答し、タスクの完了判定、業務上の分岐選択、事前定義したレベルによる採点に使用します。
Decision API は現在 Beta 機能です。インターフェイス定義、レスポンス構造、動作は今後のバージョンで変更される可能性があります。ドキュメントの更新を確認し、本番環境で使用する前に互換性を検証してください。
choice）と採点式（score）をサポートします。作成 API は判定を同期的に実行して結果を保存し、その後 ID による照会やページ単位の一覧取得ができます。
エンドポイント
| メソッド | パス | 説明 |
|---|---|---|
POST | /api/v1/forward/decisions | Decision の作成 |
GET | /api/v1/forward/decisions/{decision_id} | Decision の取得 |
GET | /api/v1/forward/decisions | Decisions の一覧取得 |
入力方式の選択
| 方式 | 用途 | 動作 |
|---|---|---|
state（カスタムコンテキスト） | 呼び出し元が提供するテキスト、構造化データなどを判定の根拠にします。 | 空でない JSON オブジェクトを渡します。Session に依存しません。 |
session_id | Session の実行状況や結果を判定します。 | サーバーがその Session の直近の利用可能なコンテキストを抽出します。 |
user.message、agent.message、session.error、agent.artifact_delivered イベントの関連情報のみを使用し、ファイル本文、ツール呼び出しの過程、サブスレッドの履歴は読み取りません。判定は直近の利用可能なコンテキストに基づくため、会話履歴全体を含まない場合があります。
入力が大きすぎる場合は 422 decision_context_too_large を返します。コンテキストや質問を減らして再試行できます。Session に利用可能なコンテキストがない場合は 422 decision_context_unavailable を返します。
Decision オブジェクト
作成成功時のレスポンス、詳細照会、一覧内のレコードは、次の構造を共用します。
| フィールド | 型 | 説明 |
|---|---|---|
| id | string | dec_ で始まる Decision ID。 |
| session_id | string または null | Session 入力の場合は関連する Session ID、明示的な state 入力の場合は null。 |
| source | string | 現在は api 固定です。 |
| status | string | running、completed、または failed。 |
| questions | array | この判定の質問。構造は Decision の作成を参照してください。 |
| answers | array | リクエストの質問順に返す回答。未完了または失敗の場合は []。 |
| context | object | 入力モードとコンテキストの範囲。下表を参照してください。 |
| error | object または null | 失敗時は code と message を含み、それ以外は null。 |
| created_at | string | RFC 3339 形式の作成日時。 |
| completed_at | string または null | RFC 3339 形式の実行終了日時。running の場合は null、成功または失敗で終了すると日時を返します。 |
state や完全な Session 入力スナップショットは含まれません。
回答の構造
| type | 結果フィールド | 説明 |
|---|---|---|
choice | value | 選択された候補の元の文字列または真偽値を、JSON 型を保持して返します。 |
score | score | 選択されたレベルに定義された数値スコアを返します。自由生成された連続値のスコアではありません。 |
name を指定すると、対応する回答にも同名フィールドが返ります。省略した場合は配列内の位置で対応します。
Context フィールド
以下のフィールドは入力モードと実行状況に応じて返されます。実行中や入力準備に失敗した場合は、mode のみを含むことがあります。クライアントは任意フィールドの欠落と今後追加されるフィールドに対応してください。
| フィールド | 型 | 説明 |
|---|---|---|
| mode | string | state または session。 |
| anchor_event_id | string | 今回の読み取り時に確定した最新の候補イベント ID。 |
| first_event_id | string | 実際に判定へ含めた最も古い有効なイベント ID。 |
| last_event_id | string | 実際に判定へ含めた最新の有効なイベント ID。 |
| included_segment_count | integer | 含めたコンテキストセグメント数。Session モードのみで返します。 |
| included_event_count | integer | 含めた有効イベント数。Session モードのみで返します。 |
利用手順
stateまたはアクセス可能なsession_idを用意し、質問と回答候補を定義します。- 作成 API を呼び出します。1 回の論理操作には固定の
Idempotency-Keyを使用することを推奨します。冪等な再試行を参照してください。 answers[].typeに従って選択結果または採点結果を処理します。- Decision ID を保存し、詳細 API または一覧 API で結果を追跡します。作成時のエラーに
error.decision_idが含まれる場合も、その ID で失敗レコードを照会できます。