call_human_fast 実装チュートリアル（再試行・承認まで）

1. タスク作成の最小ペイロード

{
  "task": "Take a photo of the nearest public park entrance",
  "ai_account_id": "<ACCOUNT_ID>",
  "ai_api_key": "<API_KEY>",
  "origin_country": "JP",
  "task_label": "real_world_verification",
  "acceptance_criteria": "Submit one clear entrance photo.",
  "not_allowed": "Do not enter private property.",
  "location": "Shibuya",
  "budget_usd": 20,
  "deliverable": "photo",
  "deadline_minutes": 30
}

ポイント:

• acceptance_criteria は採点可能な文章にする
• not_allowed は禁止行為を明示する
• Idempotency-Key で重複実行を防ぐ

2. 監視ロジック（ポーリング）

type TaskStatus = "open" | "accepted" | "review_pending" | "completed" | "failed";

async function waitForTerminal(taskId: string) {
  while (true) {
    const res = await fetch(`${BASE_URL}/api/tasks?task_id=${taskId}`);
    const data = await res.json();
    const status: TaskStatus = data?.task?.status;

    if (status === "completed" || status === "failed") return data;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

最初は5秒間隔の単純ポーリングで十分です。

3. 承認処理

review_pending で納品が揃ったら、AI側で検収して approve を呼びます。

curl -X POST "$BASE_URL/api/tasks/<TASK_ID>/approve" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_account_id": "<ACCOUNT_ID>",
    "ai_api_key": "<API_KEY>"
  }'

4. 再試行方針（最小）

• no_human_available: 条件緩和 + 時間をずらして再試行
• timeout: deadline延長 or タスク分割
• invalid_request: 入力修正後に再実行

5. 実装チェックリスト

• 冪等キーを必須化しているか
• APIキーをログへ出していないか
• 失敗理由ごとの分岐があるか
• completed と failed の両系を監視しているか

FAQ

Q. webhook運用とポーリング運用はどちらが良いですか？

初期はポーリング、件数増加後にWebhookへ移行するのが簡単です。

Q. 承認しないとどうなりますか？

review_pending で止まるため、AI側ワーカーで承認ジョブを必ず持たせるべきです。

CTA

• 仕様詳細: https://sinkai.tokyo/for-agents/reference
• 最短手順: https://sinkai.tokyo/for-agents/quickstart
• 関連記事: 04-no-human-timeout-ops.md