チャット完了から Responses API まで: 知っておくべき移行の問題点
エージェントを Chat Completions から Responses API に移行している場合、新しいインターフェイスがテキスト生成、ツール呼び出し、ファイル処理などの複数のエンドポイントを統合していることがすぐにわかりますが、その回復ロジックは簡単ではありません。この記事では、API 呼び出しが失敗した場合に、エージェント リンク全体に影響を与えずに回復する方法という特定の矛盾に焦点を当てます。
回復ワークフローにおける Responses API の役割
Responses API は 2 つの重要な役割を果たします。
- 統合応答コンテナ: モデル出力、ツール呼び出し結果、およびファイル参照を応答オブジェクトにパッケージ化します。複数のエンドポイントの出力をつなぎ合わせるのではなく、この 1 つのオブジェクトを処理するだけで済みます。
- ステータス アンカー: 各応答には一意の ID があり、後続のトレースバック、再試行、またはフォールバックに使用できます。これは、応答 ID を回復チェックポイントとして使用できることを意味します。
しかし、統合には結合リスクも伴います。リクエストにはテキストと複数のツール呼び出しが同時に含まれる可能性があり、サブタスクが失敗すると、応答全体が期待を満たさなくなります。
障害モードのリスト: ワークフローが中断される状況
実際の動作では、次の 3 つの故障モードが最も一般的です。
1. ツール呼び出しのタイムアウトまたは例外
モデルが外部ツール (データベースの検索など) を呼び出すことを決定し、そのツールが指定時間内に結果を返さない場合、応答全体が incomplete としてマークされる場合があります。この状態をキャプチャしないと、エージェントはスタックしてしまいます。
2. 応答の切り捨て (切り捨て)
max_tokens の制限により、モデルの出力が切り捨てられる場合があります。現時点では、応答オブジェクトの truncated フィールドは true ですが、多くの人はこれを無視し、不完全な出力を直接使用して次の決定を下します。
3. コンテンツ フィルタリングのヒット
モデル出力が OpenAI のコンテンツ セキュリティ ポリシーによってブロックされている場合、応答ステータスは filtered になります。この状況は、エージェントがコードまたは機密テキストを生成するときに簡単に発生します。
フォールバック インターフェイスの選択: アシスタント API をいつ使用するか、いつチャット コンプリーションにダウングレードするか
すべての障害に複雑なリカバリが必要なわけではありません。次の戦略に従って採点することをお勧めします。
- タイムアウト/切り捨て → 同じ入力で直接再試行し (最大 3 回)、max_tokens を増やすか、ツールのタイムアウトしきい値を短くします。
- ツール呼び出しの失敗 → ツールが失敗し続ける場合は、そのツールをツール リストから一時的に削除し、エージェントの無限ループを回避するために、プレーン テキストの応答を使用して「ツールが使用できない」ことをユーザーに通知する必要があります。
- コンテンツ フィルタリング/継続的エラー → チャット完了 API にダウングレードします。シンプルなシステム プロンプトのみを使用し、ツール呼び出しは使用せず、少なくとも完全な応答をユーザーに提供できるようにします。
コード図 (Python):
def run_with_recovery(messages, tools):
try:
response = client.responses.create(
model="gpt-4o",
input=messages,
tools=tools
)
if response.status == "incomplete":
# 检查 truncation
if response.truncated:
return retry_with_increased_tokens(messages, tools)
# 检查工具超时
if any(call.status == "failed" for call in response.tool_calls):
return fallback_to_chat(messages)
return response
except Exception:
return fallback_to_chat(messages)
工具调用的恢复陷阱
Responses API 的 tool_calls 数组里每个元素都有 id、type、status。最容易踩的坑是：
- 只检查
status是否为 "completed"，忽略 "failed" 状态。 - 把失败的工具调用结果拼到 conversation history 里，导致模型后续重复尝试相同工具。
正确做法：对失败的工具调用，添加一条 assistant 消息说明“该工具暂时不可用”，并设置 output_tools パラメータは、モデルの再呼び出しを禁止します。
実際のシナリオ: ユーザーがリアルタイムの株式データをクエリする
エージェントが株価 API を呼び出す必要があるとします。
- 通常のプロセス: Responses API はストック ツールを呼び出し、データを返し、エージェントが応答を生成します。
- 障害シナリオ: ストック API タイムアウト (5 秒間の応答なし)。
- 私の回復: ツール呼び出しステータスの失敗を検出 → ツールをツールリストから削除 → チャットコンプリーションを呼び出してダウングレードし、「現在リアルタイム価格を取得できません。後でもう一度お試しください。」と応答。
このプロセスにより、ダウンストリーム インターフェイスの障害によってエージェントが完全にクラッシュすることがなくなります。
再試行を停止してフォールバックを開始するタイミング
無期限に再試行しないでください。私が設定したのは：
- 同じ入力を最大 3 回まで再試行します
- 3回失敗するとダウングレードモードに入る
- ダウングレード モードは 5 分間継続し、その後、元のツール リストが自動的に復元されます。
次のステップ: 普通の開発者からエージェント エンジニアへ
上記のリカバリ設計は出発点にすぎません。運用環境で Responses API を真にマスターするには、コンテキスト ウィンドウ管理、マルチエージェント調整、権限モデルなどをさらに理解する必要があります。これらの内容は、より上級の講座で体系的に解説されています。
コメントはまだありません