# OpenAI Agent SDKの便利で実践的な使い方
🌍 危険な操作にはブレーキを!
Human-in-the-loopの承認フローを使えば、エージェントが破壊的なアクションを実行する前に人間の確認を挟むことができます。
📌 タイトル:Human-in-the-loop
🔗 URL:
🧩 概要
OpenAI Agent SDKのHuman-in-the-loop機能は、特定のツール呼び出しに承認ステップを追加します。`needs_approval=True`で全呼び出しを承認対象にしたり、関数ベースで条件付き承認にしたりできます。中断された実行は`to_state()`で状態を保存し、承認/却下後に` state)`で再開できます。
🛠 使い方
`
@tool(needs_approval=True)` を付けた `cancel_order(order_id: int)` は全呼び出しで承認が必要です。条件付き承認は `async def requires_review(_ctx, params, _call_id) -> bool` という非同期関数を定義し、`params.get("subject", "").lower()` に `"refund"` が含まれる場合のみ `True` を返します。`
@tool(needs_approval=requires_review)` で `send_email` に適用します。`Agent(name="support", tools=[cancel_order, send_email])` を定義し、`result = await "注文12345をキャンセルして")` で実行します。`result.interruptions` がある場合、各 `interruption` の ` と `interruption.arguments` を表示し、`state = で状態を保存します。人間が承認すれば `state.approve(interruption)`、却下すれば `state.reject(interruption, rejection_message="この操作は許可されていません")` を呼び、`await state)` で再開します。
実行(run)内でポリシーを固定するには、`state.approve(interruption, always_approve=True)` で以降同じツールを自動承認、`state.reject(interruption, always_reject=True)` で自動却下にできます。また、`RunConfig(tool_error_formatter=format_rejection)` のように `ToolErrorFormatterArgs` を受け取る関数(`args.kind == "approval_rejected"` を判定)を渡して、却下時のメッセージをカスタマイズすることも可能です。
🏗 実践的な使い方
本番環境では、破壊的な操作(注文キャンセル、本番DBの削除、返金メール送信など)に`needs_approval=True`を設定するのが基本です。しかし全てのツール呼び出しに承認を求めるとユーザー体験が悪化するため、関数ベースの条件付き承認が実践的です。
例えば、メール送信ツールは件名に「返金」「解約」が含まれる場合のみ承認を要求し、通常の確認メールは自動承認にするといった設計が可能です。
`interruptions`で中断された実行は`to_state()`で状態をシリアライズし、後から` state)`で再開できます。これにより、SlackやWebフォームで承認UIを構築し、非同期に承認/却下を処理できます。
`always_approve=True`/`always_reject=True`は、その実行(run)内で同じツールへのポリシーを固定したい場合に使います。管理者向けのバッチ承認に便利です。
`rejection_message`をカスタマイズすることで、エージェントに却下理由を伝え、代替アクションを提案させることができます。
💡 ユースケース
🛒 ECサイトの注文キャンセル・返金処理の承認
🗄️ 本番データベースへの破壊的クエリ(DELETE/DROP)の承認
📧 顧客への返金・解約メール送信前の確認
💰 一定金額以上の決済処理の承認
⚠️ 注意点
- `to_state()`で保存した状態にはコンテキスト情報が含まれるため、機密データの取り扱いに注意してください
- `always_approve=True`による決定はその実行(run)の残りに適用され、`to_string()`/`from_string()`によるシリアライズをまたいで保持されます。永続的なポリシーはアプリケーション側で管理してください
- 条件付き承認関数は `async def(ctx, params, call_id) -> bool` という非同期関数として呼ばれます。重い処理を入れないでください
✨ 適切な承認フローを設計することで、エージェントの自律性と安全性のバランスを取り、本番環境でも安心して運用できます!
#
OpenAIAgentSDK# #
AIAgent#