メインコンテンツへスキップ

​
概要

HITL（Human-in-the-Loop）レビューAPIは、実行開始前にAI生成の研究計画をレビュー、改善、承認するためのエンドポイントを提供します。これらのエンドポイントはRedisに保存されたレビュー状態と対話し、gRPC SignalでTemporalワークフローと連携します。 チュートリアルについてはHuman-in-the-Loopレビューを参照してください。

​
認証

必須：はい ヘッダーにAPIキーを含めてください： 
X-API-Key: sk_test_123456
所有権が強制されます：タスクを送信したユーザーのみがそのレビュー状態にアクセスできます。

​
レビュー状態の取得

GET http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
説明

ワークフローの現在のレビュー会話状態を返します。初期研究計画の取得とレビュー進捗の追跡に使用します。

​
パスパラメータ

パラメータ型必須説明
workflow_idstringはいワークフローID（タスク送信レスポンスから）

​
ヘッダー

ヘッダー必須説明
X-API-KeyはいAPI認証キー

​
レスポンス

​
200 OK

{
  "status": "reviewing",
  "round": 1,
  "version": 1,
  "current_plan": "お問い合わせに基づき、以下を調査することを提案します...",
  "rounds": [
    {
      "role": "assistant",
      "message": "お問い合わせに基づき、以下を調査することを提案します...",
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ],
  "query": "AIエージェントフレームワークの競争状況を調査"
}
レスポンスヘッダー：
ヘッダー説明
ETag現在のバージョン番号（If-Matchでの並行性制御に使用）
レスポンスフィールド：
フィールド型説明
statusstring"reviewing"（入力待ち）または"approved"（計画承認済み）
roundinteger現在の会話ラウンド（1から開始）
versioninteger楽観的並行性のための単調増加バージョン
current_planstring最新の実行可能な計画（LLMインテントが"ready"のときに設定）。LLMが質問中の場合は空の可能性あり。
roundsarray完全な会話履歴
rounds[].rolestring"assistant"（LLM）または"user"（人間のフィードバック）
rounds[].messagestringメッセージ内容
rounds[].timestampstringRFC 3339タイムスタンプ
querystring元のタスククエリ

​
401 Unauthorized

{ "error": "Unauthorized" }

​
403 Forbidden

{ "error": "Forbidden: not the task owner" }

​
404 Not Found

{ "error": "Review session not found or expired" }

​
例

curl -s http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "X-API-Key: $API_KEY" | jq

​
フィードバック送信

POST http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
説明

フィードバックを送信して研究計画を改善します。ゲートウェイがフィードバックをLLMサービスに転送し、ユーザー入力を反映した更新計画を生成します。会話ラウンドとバージョンがインクリメントされます。 分散Redisロックにより、LLM呼び出し中の並行フィードバックリクエストの競合が防止されます。

​
パスパラメータ

パラメータ型必須説明
workflow_idstringはいワークフローID

​
ヘッダー

ヘッダー必須説明
X-API-KeyはいAPI認証キー
Content-Typeはいapplication/json
If-Matchいいえ楽観的並行性のバージョン番号。提供時、現在のバージョンが一致しない場合409を返します。

​
ボディパラメータ

パラメータ型必須説明
actionstringはい"feedback"を指定
messagestringはいフィードバックテキスト（最大10 KB）

​
リクエストボディ

{
  "action": "feedback",
  "message": "オープンソースフレームワークにより注力し、価格比較を含めてください"
}

​
レスポンス

​
200 OK

{
  "status": "reviewing",
  "plan": {
    "message": "研究計画を更新しました...",
    "round": 2,
    "version": 2,
    "intent": "ready"
  }
}
レスポンスヘッダー：
ヘッダー説明
ETag更新されたバージョン番号
レスポンスフィールド：
フィールド型説明
statusstringフィードバックレスポンスでは常に"reviewing"
plan.messagestringLLMからの更新された計画
plan.roundinteger現在のラウンド番号
plan.versioninteger更新されたバージョン（次のIf-Match用）
plan.intentstring"feedback"（LLMが質問中）または"ready"（実行可能な計画が提案済み）

​
400 Bad Request

{ "error": "message is required for feedback" }

{ "error": "message exceeds maximum length (10KB)" }

​
404 Not Found

{ "error": "Review session not found or expired" }

​
409 Conflict

バージョン不一致： 
{ "error": "Conflict: state has been modified" }
別のフィードバックリクエストが進行中： 
{ "error": "Another feedback request is in progress. Please wait." }
最大ラウンド超過： 
{ "error": "Maximum review rounds reached. Please approve the plan." }

​
502 Bad Gateway

{ "error": "Failed to generate updated plan" }

​
例

curl -X POST http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "If-Match: 1" \
  -d '{
    "action": "feedback",
    "message": "価格セクションを追加し、LangGraphを比較に含めてください"
  }'

​
計画の承認

POST http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
説明

現在の研究計画を承認し、ワークフローのブロックを解除して実行を続行します。ゲートウェイが待機中のワークフローにTemporal Signalを送信し、確認された計画とレビュー会話をタスクコンテキストに注入します。

​
パスパラメータ

パラメータ型必須説明
workflow_idstringはいワークフローID

​
ヘッダー

ヘッダー必須説明
X-API-KeyはいAPI認証キー
Content-Typeはいapplication/json
If-Matchいいえ楽観的並行性のバージョン番号

​
ボディパラメータ

パラメータ型必須説明
actionstringはい"approve"を指定

​
リクエストボディ

{
  "action": "approve"
}

​
レスポンス

​
200 OK

{
  "status": "approved",
  "message": "Research started"
}

​
400 Bad Request

承認可能な計画がない： 
{ "error": "No research plan to approve. Please provide feedback to generate a plan first." }

​
409 Conflict

バージョン不一致： 
{ "error": "Conflict: plan has been updated. Please review the latest version." }
フィードバック進行中： 
{ "error": "A feedback request is in progress. Please wait and try again." }

​
502 Bad Gateway

{ "error": "Failed to approve review" }

​
例

curl -X POST http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "If-Match: 2" \
  -d '{"action": "approve"}'

​
動作に関する注意事項

  • Redis TTL：レビュー状態はRedisにレビュータイムアウト + 5分バッファのTTL（デフォルト：20分）で保存されます。有効期限後、レビューセッションにはアクセスできなくなります。
  • 最大ラウンド：10ラウンドのフィードバックが許可されます。最終ラウンドでLLMに確定的な計画を生成するよう指示されます。この制限を超えると承認のみ受け付けられます。
  • 所有権：タスクを送信したユーザーのみがそのレビュー状態にアクセスできます（Redisのowner_user_idで強制）。
  • 並行性：フィードバックと承認の両方が分散Redisロックを取得します。フィードバックリクエストが進行中（ロック保持中）の場合、承認は即座に409で失敗します。
  • SSEイベント：レビューサイクルはRESEARCH_PLAN_READY、REVIEW_USER_FEEDBACK、RESEARCH_PLAN_UPDATED、RESEARCH_PLAN_APPROVEDイベントをRedisイベントストリームに発行します。これらはSSEストリームに表示され、セッション履歴に永続化されます。
  • トークン追跡：レビュー中（フィードバックラウンド）のLLMトークン使用量はRecordTokenUsage gRPCで記録され、正確なコスト計算が保証されます。