Documentation Index
Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
Use this file to discover all available pages before exploring further.
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_id | string | はい | ワークフロー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での並行性制御に使用） |
| フィールド | 型 | 説明 |
|---|
status | string | "reviewing"（入力待ち）または"approved"（計画承認済み） |
round | integer | 現在の会話ラウンド（1から開始） |
version | integer | 楽観的並行性のための単調増加バージョン |
current_plan | string | 最新の実行可能な計画（LLMインテントが"ready"のときに設定）。LLMが質問中の場合は空の可能性あり。 |
rounds | array | 完全な会話履歴 |
rounds[].role | string | "assistant"（LLM）または"user"（人間のフィードバック） |
rounds[].message | string | メッセージ内容 |
rounds[].timestamp | string | RFC 3339タイムスタンプ |
query | string | 元のタスククエリ |
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
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
workflow_id | string | はい | ワークフローID |
ヘッダー
| ヘッダー | 必須 | 説明 |
|---|
X-API-Key | はい | API認証キー |
Content-Type | はい | application/json |
If-Match | いいえ | 楽観的並行性のバージョン番号。提供時、現在のバージョンが一致しない場合409を返します。 |
ボディパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
action | string | はい | "feedback"を指定 |
message | string | はい | フィードバックテキスト（最大10 KB） |
リクエストボディ
{
"action": "feedback",
"message": "オープンソースフレームワークにより注力し、価格比較を含めてください"
}
レスポンス
200 OK
{
"status": "reviewing",
"plan": {
"message": "研究計画を更新しました...",
"round": 2,
"version": 2,
"intent": "ready"
}
}
| フィールド | 型 | 説明 |
|---|
status | string | フィードバックレスポンスでは常に"reviewing" |
plan.message | string | LLMからの更新された計画 |
plan.round | integer | 現在のラウンド番号 |
plan.version | integer | 更新されたバージョン（次のIf-Match用） |
plan.intent | string | "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
パスパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
workflow_id | string | はい | ワークフローID |
ヘッダー
| ヘッダー | 必須 | 説明 |
|---|
X-API-Key | はい | API認証キー |
Content-Type | はい | application/json |
If-Match | いいえ | 楽観的並行性のバージョン番号 |
ボディパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
action | string | はい | "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で記録され、正確なコスト計算が保証されます。
