ARTICLE

OpenAI Agents SDK実践ガイド|Handoff・ツール定義・ガードレールの設計パターン【2026年版】

2026/9/16 (更新: 2026/9/23)

SHARE

OpenAI Agents SDK実践ガイド。Handoff・ツール定義・ガードレールの設計パターン【2026年版】

Op

OpenAI Agents SDK実践ガイド|Handoff・ツール定義・ガードレールの設計パターン【2026年版】

ARTICLE株式会社renue
renue

株式会社renue

2026/9/16 公開2026/9/23 更新

renueについて

renueは、AIで業務を実装する会社です

AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。

OpenAI Agents SDKとは

OpenAI Agents SDKは、OpenAIが提供するAIエージェント開発のためのオープンソースSDKです。以前の実験的フレームワーク「Swarm」の本番運用向けアップグレードとして位置づけられ、エージェントの定義・ツール連携・Handoff(タスクの受け渡し)・ガードレールを軽量なパッケージで実現します。本記事の仕様説明は、2026年9月23日に確認したPython版openai-agents 0.22.3と公式ドキュメントに基づきます。

2026年現在、AIエージェント開発フレームワークの選択肢は増えていますが、OpenAI Agents SDKはシンプルさと本番対応のバランスが強みです。複雑な連携ロジックを抽象化しつつ、ツール呼び出しや複数エージェントの協調を容易に実装できます。

本記事では、AIエージェント開発者・バックエンド開発者に向けて、OpenAI Agents SDKのコア機能の理解から実装パターンまでを解説します。

Agents SDKの4つのコア概念

概念役割実務での使い方
AgentLLMに指示(システムプロンプト)・ツール・Handoffを持たせた実行単位業務ごとに専門エージェントを定義(FAQ対応、注文処理、分析等)
Toolエージェントが呼び出せる外部機能(Python関数、API呼び出し等)データベース検索、外部API連携、計算処理をエージェントに持たせる
Handoffエージェント間でタスクを受け渡す仕組みトリアージエージェントが適切な専門エージェントにルーティング
Guardrails入力・最終出力を検証する仕組み。入力は最初のエージェントで既定は並行実行、出力は最終応答の生成後に実行不適切な入力の検知、出力の安全性確認

Agent: エージェントの定義

Agentは、Agents SDKの最も基本的な構成要素です。システムプロンプト(instructions)、利用可能なツール、Handoff先の3つで定義します。

設計のポイント

  • 単一責任: 1つのAgentには1つの明確な役割を持たせる。「何でもできるエージェント」は品質が低下する
  • instructionsの具体性: 「丁寧に回答して」ではなく「日本語で、100文字以内で、箇条書きで回答する。不明な場合は『確認いたします』と回答する」のように具体的に
  • モデルの選択: 複雑な判断には上位モデル、単純なルーティングには軽量モデルを選択してコスト最適化

Tool: ツールの定義と活用

Agents SDKでは、Python関数をそのままツールとして登録できます。function_toolは関数シグネチャと型ヒントから引数のJSONスキーマを生成し、docstringから関数説明・引数説明を取り込みます。Google・Sphinx・NumPy形式に対応します。呼び出し引数はPydanticで型や宣言した制約を検証しますが、業務上の妥当性や処理結果の正しさは別に確認する必要があります(公式のツール仕様)。

ツール設計のベストプラクティス

  • 関数名を明確に: get_order_statusのように、何をする関数かが名前だけで分かるようにする
  • docstringを詳しく: LLMには、解析された関数説明と引数説明がツール定義として渡る。標準のdocstring解析ではReturns節だけの内容はツール説明に自動転記されないため、必要な戻り値形式や使用条件は関数説明にも書き、生成された定義を確認する
  • エラーハンドリング: ツール内で例外を適切にキャッチし、LLMが理解できるエラーメッセージを返す
  • 副作用の制御: データを変更するツール(POST/PUT/DELETE)は、権限設計と組み合わせて慎重に管理する

ツールの分類

分類例リスクレベル
読み取り系データベース検索、在庫確認、顧客情報参照低
生成系メール下書き作成、レポート生成、提案書ドラフト中(内容のレビューが必要)
実行系注文処理、設定変更、メール送信高(人間の承認を推奨)

Handoff: エージェント間のタスク受け渡し

Handoffは、Agents SDKの最も特徴的な機能です。あるエージェントが別のエージェントにタスクを委譲する仕組みで、LLMにはツールとして表現されます。公式Handoff仕様では、handoffsにAgentまたはHandoffを登録し、委譲先のエージェントへ制御を渡します。

Handoffの動作原理

  1. エージェントAがHandoffツールを呼び出す(例: transfer_to_refund_agent)
  2. 実行制御がエージェントBに移行し、会話履歴もそのまま引き継がれる
  3. エージェントBが専門知識でタスクを処理
  4. 必要に応じてエージェントAへのHandoffで制御を戻すことも可能

Handoffの3つの活用パターン

パターン1: トリアージ(振り分け)

フロントのトリアージエージェントが問い合わせを分類し、専門エージェントに振り分けます。

トリアージAgent → [FAQ Agent | 注文Agent | 技術サポートAgent]

パターン2: エスカレーション(段階的対応)

一次対応エージェントが対応できない場合に、上位のエージェントにエスカレーションします。Handoff先はエージェントなので、図の最後の人間オペレーターへの引き継ぎには、通知・チケット起票や担当者の応答を受け取る処理を別途用意します。操作承認が必要な場合は、SDKの承認待ち・再開機能を組み合わせます。

一次対応Agent → 二次対応Agent → 人間オペレーター(最終フォールバック)

パターン3: パイプライン(順次処理)

処理の各段階を専門エージェントが担当し、順番にHandoffで受け渡します。

データ収集Agent → 分析Agent → レポート生成Agent

Handoff設計時の注意点

  • 循環Handoffの防止: A→B→A→B...の無限ループが発生しないよう、Runnerのmax_turnsで実行ターン数を制限する。1ターンはツール呼び出しを含む1回のモデル呼び出しで、通常は上限超過でMaxTurnsExceeded例外になる。Handoff専用の回数制限ではないため、委譲回数を制限する場合はon_handoffで共通コンテキストの回数を数え、上限超過で停止する処理を別途実装する
  • コンテキストの肥大化: Handoffのたびに会話履歴が引き継がれるため、長い会話はトークンコストが増大する。input_filterで不要なコンテキストを削減
  • フォールバック設計: どのエージェントも対応できない場合の最終的な受け皿(人間エスカレーション)を必ず用意する。Handoffで直接人間へ制御を渡すのではなく、通知・チケット起票や担当者への受付処理として接続する

Guardrails: 安全性の確保

Guardrailsは入力や最終出力を検証する仕組みです。入力ガードレールは最初のエージェントで動き、既定のrun_in_parallel=Trueではエージェントと並行して実行されます。tripwireが発動すると例外で中断しますが、その前にトークン消費やツール実行が進むことがあります。run_in_parallel=Falseなら、入力検査が通るまでエージェントを開始しません。出力ガードレールは最終応答の生成後に検査するため、既に実行したツールの副作用を巻き戻すものではありません。操作の権限チェックや承認は、実行前の処理として別に組み合わせます(公式Guardrails仕様)。

Guardrailsの実装パターン

パターン用途実装方法
入力ガードレール不適切な入力・攻撃的なプロンプトの検知別のLLM(軽量モデル)で入力を評価
出力ガードレール機密情報の漏洩防止、不適切な応答のブロック出力テキストのパターンマッチング+LLM評価
ツール呼び出しガードレール権限外の操作の防止FunctionToolの実行前に引数・権限を検証し、出力は実行後に検証。設定済みのローカルMCPツールも対象。Handoff自体・ホスト側ツール・ComputerTool等の組込実行ツールはこの経路の対象外

他のフレームワークとの比較

フレームワークHandoff相当機能主に理解する概念制御の組み立て方利用場面の例
OpenAI Agents SDKHandoff(ネイティブ)Agent・Tool・HandoffPythonの条件分岐とSDKの実行ループOpenAIモデル中心のエージェント開発
LangGraphグラフのエッジ遷移状態・ノード・エッジ状態更新と条件付き遷移をグラフで定義複雑な分岐・ループのワークフロー
CrewAICrew内のタスク委譲Agent・Task・Process順次実行やマネージャーによる階層型処理チーム型マルチエージェント
AutoGen会話ベースの委譲AgentChatのチーム・終了条件順番またはモデル選択で次の発言者を決定ディスカッション型マルチエージェント

OpenAI Agents SDKはシンプルさと実用性のバランスが最大の強みです。LangGraphのGraph APIは状態・ノード・エッジで遷移を明示し、Agents SDKはPythonコードとHandoff/Tool/Guardrailsを組み合わせて制御します。上表は習得の速さや柔軟性の順位ではなく、設計時に扱う概念と制御方式の比較です。マルチエージェント設計パターンで整理した5パターンのうち、パイプラインはパターン1、自己改善ループはパターン5に対応します。本記事のトリアージも、専門エージェントへのHandoffで実装できます。

企業実装の設計原則

原則1: エージェントは小さく作る

1つのエージェントに多くの責務を持たせず、専門化した小さなエージェントをHandoffでつなぐ構成にします。デバッグが容易になり、各エージェントの品質を独立して改善できます。

原則2: ツールの副作用を明示する

読み取り専用のツールと副作用のあるツール(データ変更・メール送信等)を明確に区別し、後者には人間の承認フローを組み込みます。

原則3: Handoffの深さを制限する

Handoffチェーンが深くなりすぎると、コンテキストの肥大化とデバッグの困難さを招きます。最大3〜4段階を目安にし、それ以上必要な場合はアーキテクチャを見直します。

原則4: 監視とLLMゲートウェイを併用する

全エージェントのAPI呼び出しをLLMゲートウェイ経由にし、コスト・レイテンシ・エラー率を一元監視します。プロンプト管理と組み合わせて、各エージェントのシステムプロンプトをバージョン管理してください。

導入前チェックリスト

カテゴリチェック項目確認
設計エージェントの役割分担(単一責任)を定義している□
Handoffの構成(トリアージ/エスカレーション/パイプライン)を設計している□
ツールを読み取り系/生成系/実行系に分類し、権限レベルを設定している□
安全性入力/出力ガードレールを実装している□
実行系ツールに人間の承認フローを組み込んでいる□
Handoffの最大深度を制限している(推奨: 3〜4段階)□
運用全エージェントのAPI呼び出しをLLMゲートウェイ経由にしている□
エージェントのシステムプロンプトをGitでバージョン管理している□
フォールバック(人間エスカレーション)を設計している□

まとめ

OpenAI Agents SDKは、Agent・Tool・Handoff・Guardrailsの4概念でエージェント開発の基盤を提供するシンプルかつ実用的なフレームワークです。Handoffによるエージェント間のタスク受け渡しがネイティブに組み込まれている点が最大の差別化ポイントで、カスタマーサポート・業務自動化・データ分析パイプラインなど幅広いユースケースに適用できます。

マルチエージェント設計パターンで全体のアーキテクチャを決め、権限設計でセキュリティを確保し、LLMゲートウェイでコストと品質を監視する——この組み合わせで、本番運用に耐えうるエージェントシステムを構築してください。

あわせて読みたい

AI活用のご相談はrenueへ

renueは自社開発のAIツールを自社運用する「自社実証型」AIコンサルティングファームです。

→ AIコンサルティングの詳細を見る

SHARE

FAQ

よくある質問

OpenAI Agents SDKは、OpenAIが提供するAIエージェント開発のためのオープンソースSDKです。以前の実験的フレームワーク「Swarm」の本番運用向けアップグレードとして位置づけられ、エージェントの定義・ツール連携・Handoff(タスクの受け渡し)・ガードレールを軽量なパッケージで実現します。シンプルさと本番対応のバランスが強みです。

主に、Agent(LLMに指示・ツール・Handoffを持たせた実行単位)、Tool(エージェントが呼び出せる外部機能、Python関数やAPI)、Handoff(エージェント間でタスクを受け渡す仕組み)、Guardrails(入力・最終出力を検証する仕組み。入力は最初のエージェントで既定は並行実行、出力は最終応答の生成後に実行)、です。これらを組み合わせて複雑なエージェントワークフローを構成します。

主に、単一責任(1つのAgentには1つの明確な役割を持たせ「何でもできるエージェント」を避ける)、instructionsの具体性(曖昧な抽象表現ではなく具体的な手順・条件を明示)、モデルの選択(複雑な判断には上位モデル、単純なルーティングには軽量モデルでコスト最適化)、です。役割が明確なほど出力品質が安定します。

主に、トリアージ(フロントのトリアージエージェントが問い合わせを分類し専門エージェントに振り分け)、エスカレーション(一次対応エージェントが対応できない場合に上位エージェントへ段階対応)、パイプライン(処理の各段階を専門エージェントが担当し順次受け渡し)、です。会話履歴も引き継がれるため一貫した対応が可能です。

主に、関数名を明確にする(何をする関数かが名前だけで分かるように)、docstringを詳しく書く(解析された関数説明・引数説明がLLMに渡る。標準解析ではReturns節だけの内容はツール説明に自動転記されないため、戻り値形式や使用条件は関数説明にも含め、生成された定義を確認)、エラーハンドリング(ツール内で例外を適切にキャッチしLLMが理解できるエラーメッセージを返す)、副作用の制御(データ変更系は権限設計と組み合わせる)、です。

renueについて

renueは、AIで業務を実装する会社です

AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。

AI導入・DXの悩みをプロに相談してみませんか?

AIやDXに関する悩みがありましたら、お気軽にrenueの無料相談をご利用ください。renueのAI支援実績、コンサルティングの方針や進め方をご紹介します。

無料資料をダウンロード