Q9.エージェント向けのAPI設計で、押さえるべき原則は?
回答
冪等性、明確なエラーコード、タイムアウト、部分結果の返却、人間承認用のフックを最初から入れます。LLM向けに「自然言語だけのAPI」は避け、スキーマを固定します。
エージェントはツールを連続呼び出すため、APIは予測可能である必要があります。各操作にidempotency-key、レート制限、最大実行時間を設け、失敗時はリトライ可能か(POSTの二重実行)を定義します。レスポンスは、成功・業務エラー・権限不足・一時障害を機械判読できるコードで返し、LLMが次の行動を選びやすくします。長時間処理は同期で待たず、ジョブIDとポーリング/Webhookを用意します。高リスク操作(送金、削除、外部メール送信)は、human-in-the-loop用のpending状態と承認エンドポイントを分離します。OpenAPI等でスキーマを公開し、ツール説明と実装のズレをCIで検知すると、ハルシネーションによる誤呼び出しが減ります。
- ●信頼性: 冪等性、タイムアウト、構造化エラー、レート制限
- ●非同期: ジョブ化、部分結果、Webhook
- ●安全: 高リスク操作の承認フロー、スキーマの機械検証