OpenAI Agents SDK 実践教科書 — Agents API 増補版

SDKの第0〜16章は5つのブロックで構成しています。第17章は用語集、第18章はAgents APIの増補です。SDKから学ぶ方は上から、新APIとの違いを知りたい方は第18章から読み進められます。

• 基礎(第 0〜5 章): 全員必読です。以降のすべての章がここで学ぶ部品を前提とします。
• 連携(第 6〜10 章): 外部ツール・データ・他社モデルとの接続方法です。必要な章だけの拾い読みも可能です。
• 実践アプリ(第 11〜13 章): 基礎の部品が実アプリでどう組み合わさるかを通読で体感します。
• 音声・リアルタイム(第 14〜15 章): 音声デバイスが必要なため、環境が整ってから取り組むことを推奨します。
• 発展(第 16 章): サンドボックス実行という最前線のトピックです。Docker があると学習効率が上がります。

• 各章は「概念の解説 → コードの読み解き → 実行手順 → 理解度チェック」という共通の構成です。まず概念をつかみ、コードで裏を取り、必ず手元で実行して確かめてください。読むだけと動かすのとでは定着度がまったく違います。
• 実行時の前提（追加 extras・環境変数・外部ツール）は各章冒頭と本ページ各カードの「要件」にまとめています。実行前に確認してください。
• つまずいたら第 1 章のトラブルシューティングと用語集に戻るのが近道です。

第0章 はじめに — AIエージェントと Agents SDK の世界

目次に戻る | 次章: 第1章 環境構築 →

本書は、OpenAI が公開している OpenAI Agents SDK（Python 版、本書の確認バージョンは v0.22.2）の公式リポジトリに含まれる examples（サンプルコード集）を、1 章ずつ動かしながら学ぶ教科書です。対象読者は「Python の基本文法は分かるが、LLM や AI エージェント開発は初めて」という方です。

この章ではコードをほとんど書きません。その代わり、これから 17 章かけて学ぶ世界の全体地図を手に入れます。

この章で学ぶこと

• AI エージェントとは何か。普通のチャットボットと何が違うのか
• LLM・トークン・プロンプト・API という基礎用語の意味
• Agents SDK の設計思想と、7 つの基本部品（Agent / Runner / function tool / handoff / guardrail / session / tracing）
• 世界一短いエージェントプログラム（Hello World）の読み方
• 本書全体の構成マップと、おすすめの学習順序
• 学習にかかる費用（API 利用料）の注意点

0.1 AI エージェントとは何か — チャットボットとの違い

まず「エージェント」という言葉を、身近な比喩で押さえましょう。

チャットボットは「物知りな電話相談員」です。あなたが「大阪でおすすめの観光地は？」と聞けば、知識をもとに答えてくれます。しかし相談員は電話口から一歩も動けません。「じゃあ新幹線とホテルを予約しておいて」と頼んでも、「予約サイトの使い方をご案内しますね」と説明が返ってくるだけです。質問に答えることはできても、行動はできないのです。

一方、AI エージェントは「旅行代理店の担当者」です。「来週大阪に出張するので手配をお願いします」と目的だけを伝えれば、担当者は自分で判断して動きます。空席検索システムで新幹線を調べ、予約端末を操作し、ホテルの空室を確認し、条件が合わなければ代替案を考え、最後に「手配が完了しました」と結果だけを報告してくれます。

この比喩を技術用語に置き換えると、AI エージェントの定義が見えてきます。

つまり AI エージェントとは、LLM が自分でツールを使い、状況を判断し、複数ステップのタスクを最後まで遂行するプログラムです。「1 回の質問に 1 回答えて終わり」のチャットボットとの本質的な違いは、この「自律的に複数ステップを進める」点にあります。

0.2 LLM の基礎のおさらい

エージェントの頭脳である LLM について、本書を読むのに必要な最小限だけ確認します。

LLM（Large Language Model、大規模言語モデル） とは、膨大なテキストから言葉のつながりを学習した AI モデルです。文章を入力すると、その続きとして最も自然な文章を生成します。OpenAI の GPT シリーズが代表例です。

トークンとは、LLM が文章を処理するときの最小単位です。LLM は文章を文字単位ではなく、「単語や文字のかたまり」に区切って扱います。分割のされ方はモデル・言語・文章によって異なり、文字数から一定比率では換算できません。実際の使用量はレスポンスの usage で確認します。後述する API の利用料金は、このトークン数に応じた従量課金で計算されるため、コスト管理の観点でも重要な概念です。

プロンプトとは、LLM に与える入力文のことです。プロンプトには大きく 2 種類あります。

• システムプロンプト（指示）: 「あなたは親切なアシスタントです」のように、LLM の役割や振る舞いを定める文。Agents SDK では instructions という引数で指定します
• ユーザー入力: 「大阪の観光地を教えて」のような、利用者からの実際の質問や依頼

API（Application Programming Interface）呼び出しとは、プログラムからインターネット越しに OpenAI のサーバーへプロンプトを送信し、LLM の応答を受け取ることです。ChatGPT の画面をブラウザで操作する代わりに、Python コードで同じことを行うイメージです。API を使うには API キー（利用者を識別する秘密の文字列）が必要で、使ったトークン数に応じて料金が発生します（詳しくは 0.8 節）。

ここで重要なのは、LLM の API は 1 回の呼び出しで「テキストを受け取り、テキストを返す」ことしかできないという点です。ファイルを開くことも、Web を検索することも、それ単体ではできません。この「1 往復のテキスト処理」を部品として、「ツールを使い、結果を見て、次の行動を決める」というループを組み上げたものがエージェントです。そして、そのループを自分でゼロから書かなくて済むようにしてくれるのが Agents SDK です。

0.3 Agents SDK の設計思想

OpenAI Agents SDK は、エージェント型 AI アプリケーションを構築するための軽量なフレームワークです。公式ドキュメントは、設計を支える原則を 2 つ挙げています。

1. 使う価値がある十分な機能を備えつつ、すばやく学べるだけの少数の基本部品に抑えること
2. そのままでも優れた動作をしつつ、必要なら何が起こるかを正確にカスタマイズできること

この思想の中核がエージェントループです。SDK は「LLM を呼ぶ → ツール呼び出しがあれば実行して結果を LLM に返す → 別のエージェントへの handoff があれば切り替える → 最終出力が出たら終了する」という繰り返しを組み込みで提供します。開発者はループの中身を自分で書く必要がなく、「どんなエージェントを、どんなツールとともに用意するか」の設計に集中できます。

もうひとつの特徴は Python ファーストであることです。エージェント同士の連携や条件分岐に独自の設定言語を覚える必要はなく、普通の Python の関数・クラス・制御構文で表現します。「Python が書ければエージェントが書ける」ことを目指した設計です。

また、SDK は OpenAI 専用ではなく、他社の LLM を含む 100 以上のモデルに対応しています（第9章で扱います）。

このエージェントループを図で表すと、2 箇所の分岐と 2 本の周回で成り立っていることが分かります。

0.4 基本プリミティブ — 7 つの部品

Agents SDK は少数の基本部品（プリミティブ）の組み合わせでできています。ここでは 7 つを順に紹介します。名前だけでも覚えておくと、以降の章がぐっと読みやすくなります。

Agent（エージェント）

Agent は SDK の主役となるクラスで、「instructions（指示）とツールを備えた LLM」を表します。name（名前）と instructions（システムプロンプト）を渡すだけで最小のエージェントが完成し、必要に応じてツール、handoff 先、guardrail、使用するモデルなどを追加していきます。本書のすべての章に登場しますが、基本形は第2章で、実践的な構成は第11〜13章で詳しく学びます。

Runner（実行エンジン）

Runner は、Agent を実際に動かすための実行エンジンです。前節で説明したエージェントループ（LLM 呼び出し → ツール実行 → 繰り返し）を担当するのが Runner で、Runner.run()（非同期版）、Runner.run_sync()（同期版）、Runner.run_streamed()（ストリーミング版）の 3 つの実行方法があります。ストリーミングとは、応答の全文が完成するのを待たず、生成された端から少しずつ受け取る方式のことです（ChatGPT の画面で文字がパラパラと表示されるのと同じ仕組みです）。Runner の使い分けは第2章で学びます。

function tool（関数ツール）

function tool は、普通の Python 関数をエージェントのツールに変換する仕組みです。関数に @tool（従来名 @function_tool。v0.19.0 で追加された短縮エイリアスで実体は同じ）というデコレータ（関数に機能を追加する Python の記法）を付けるだけで、SDK が関数の引数や説明文（docstring）を自動で読み取り、LLM が「この関数をこの引数で呼びたい」と判断できる形式に変換してくれます。天気の取得、データベース検索、社内 API の呼び出しなど、あらゆる処理をエージェントの「手足」にできます。基本は第2章で、Web 検索やコード実行などの OpenAI 提供の組み込みツールは第3章で学びます。

handoff（ハンドオフ）

handoff は、あるエージェントから別の専門エージェントへ会話を引き継ぐ仕組みです。たとえば受付役の「振り分けエージェント」が質問内容を見て、歴史の質問なら歴史専門エージェントへ、数学の質問なら数学専門エージェントへ会話ごと委任する、といった構成が作れます。1 つの万能エージェントを作るより、専門特化した小さなエージェントを連携させるほうが品質を保ちやすい、というのがマルチエージェント設計の基本的な考え方です。第5章で詳しく学び、第11章の実践アプリで本格的に活用します。

guardrail（ガードレール）

guardrail は、エージェントへの入力やエージェントからの出力を検証する安全装置です。名前のとおり道路のガードレールのように、「宿題の代行依頼は拒否する」「個人情報を含む出力を止める」といったチェックをエージェント本体の処理と並行して実行し、違反を検知したら即座に処理を打ち切ります。本番運用に耐えるエージェントには欠かせない部品です。第4章（設計パターン）で学びます。

session（セッション / メモリ）

LLM の API 呼び出しは 1 回ごとに独立しており、そのままでは前の会話を覚えていません。session は、会話履歴を自動で保存・復元してくれる記憶装置です。実行前に履歴を読み込み、実行後に新しいやり取りを保存する処理を SDK が肩代わりするため、「さっきの続きだけど」が通じるエージェントを簡単に作れます。保存先も SQLite（ファイルベースの軽量データベース）や Redis などから選べます。第8章で詳しく学びます。

tracing（トレーシング）

tracing は、エージェントの実行記録を自動で収集し、可視化する仕組みです。エージェントは内部で複数回の LLM 呼び出しやツール実行を行うため、「なぜこの答えになったのか」が外から見えにくくなりがちです。SDK は各ステップを自動で記録しており、OpenAI ダッシュボードの Trace viewer（https://platform.openai.com/traces ）で「どのエージェントが、どのツールを、どんな引数で呼んだか」を時系列で確認できます。デバッグ（不具合調査）の強力な味方として、第2章以降のあらゆる場面で活用します。

7 つの部品を Agent を中心に配置すると、それぞれの役割の違いが見渡せます。

0.5 最小コード例 — 世界一短いエージェント

理屈はこのくらいにして、実際のコードを見てみましょう。公式ドキュメントの冒頭に掲載されている Hello World の例です。

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

わずか 4 行の実行文です。1 行ずつ読み解きます。

• 1 行目 from agents import Agent, Runner — SDK のパッケージ名は agents です（インストール時の名前は openai-agents ですが、import では agents と書きます）。主役の Agent と実行エンジンの Runner を読み込みます。
• 3 行目 agent = Agent(name="Assistant", instructions="You are a helpful assistant") — エージェントを定義します。name は人間が識別するための名前（tracing の画面にも表示されます）、instructions はシステムプロンプト、つまり「あなたは親切なアシスタントです」というエージェントの役割設定です。この時点では API 呼び出しは発生しません。設計図を作っただけです。
• 5 行目 result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") — ここで初めてエージェントが動きます。第 1 引数に実行したいエージェント、第 2 引数にユーザー入力（「プログラミングの再帰について俳句を書いて」）を渡します。run_sync は同期版の実行メソッドで、エージェントループが完了するまでこの行で待機します。裏側では SDK が OpenAI の API を呼び出しています。
• 6 行目 print(result.final_output) — 実行結果は RunResult というオブジェクトで返され、その final_output 属性に最終出力（この例では英語の俳句）が入っています。
• 8〜10 行目のコメント — 実行したときの出力例です。LLM の出力は毎回変わるため、手元で実行すると別の俳句になります。

この例にはツールも handoff も登場しませんが、「Agent を定義し、Runner で実行し、final_output を受け取る」という流れは、本書に登場するすべての examples に共通する基本形です。

なお、リポジトリの examples に収録されている同等のコード examples/basic/hello_world.py は、run_sync の代わりに非同期版を使っています。非同期（async/await）とは、待ち時間の長い処理（API 応答待ちなど）の間に他の処理を進められる Python の仕組みで、examples の大半はこのスタイルで書かれています。

import asyncio

from agents import Agent, Runner


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)
    # Function calls itself,
    # Looping in smaller pieces,
    # Endless by design.


if __name__ == "__main__":
    asyncio.run(main())

環境構築（第1章）を終えたあとであれば、リポジトリのルートで次のように実行できます。実行には環境変数 OPENAI_API_KEY の設定が必要です（設定方法も第1章で解説します）。

export OPENAI_API_KEY=sk-...
uv run python examples/basic/hello_world.py

0.6 この教科書の構成マップ

本書は全 17 章と用語集で構成されています。各章は公式リポジトリの examples ディレクトリのカテゴリに対応しており、「解説を読む → 実際に動かす」を繰り返しながら進みます。難易度は ★（入門）〜★★★（応用）の 3 段階です。

この構成マップを 5 ブロックの一本道として図にし、急いでいる方向けの最短ルートも合わせて示します。

難易度で俯瞰すると、17 章は ★1〜★3 の 3 段に分かれます。

0.7 推奨学習順序

はじめて学ぶ方は、次の 5 ブロックの順に進むことをおすすめします。

1. 基礎（第0〜5章） — まずここを順番に。エージェントの基本形（Agent / Runner / function tool）から、マルチエージェントの入り口（設計パターン・handoff）までを一気通貫で身につけます。本書の背骨にあたるブロックです。
2. 連携（第6〜10章） — エージェントを外の世界とつなげます。MCP による外部ツール接続、会話の記憶（session）、他社モデルの利用、推論モデルの活用と、実用化に必要な周辺技術を学びます。興味のある章からのつまみ食いも可能です。
3. 実践アプリ（第11〜13章） — 基礎と連携で学んだ部品が、実際のアプリケーションでどう組み合わさるかを 3 つの題材で確認します。「部品は分かったが、どう組み立てればよいか分からない」という段階を抜け出すためのブロックです。
4. 音声・リアルタイム（第14〜15章） — テキストから音声へ。追加の依存関係やオーディオ機器が必要になるため、テキストベースのエージェントに慣れてから取り組むのが安全です。
5. 発展（第16章） — 隔離環境でファイルやコマンドを扱うサンドボックスエージェントです。SDK の中でも新しく発展中の領域なので、最後の挑戦として位置づけています。

急いでいる方向けの最短ルートは「第1章 → 第2章 → 第4章 → 第5章 → 第11章」です。ただし途中の章で登場した用語につまずいたら、用語集（17_用語集.md）と該当章に立ち戻ってください。

0.8 学習にかかる費用の注意

本書の examples を動かすには OpenAI の API キーが必要で、API の利用は従量課金です。ChatGPT の有料プラン（ChatGPT Plus など）とは別の契約であることに注意してください。ChatGPT に加入していても、API は API として使った分だけ課金されます。

料金は「入力トークン数 + 出力トークン数 × モデルごとの単価」で決まります。単価はモデルによって大きく異なり、改定されることもあるため、必ず公式の料金ページ（https://openai.com/api/pricing/ ）で最新情報を確認してください。そのうえで、学習コストの感覚として次の点を押さえておくと安心です。

• 小さな examples でも料金は一定ではありません。モデル、入力履歴、推論量、ツール、反復回数によって変わるため、実行後の usage と公式料金表を照合します
• 第11〜13章の実践アプリは、1 回の実行で多数の LLM 呼び出しを行います。特にリサーチ系（第12・13章）は検索とレポート生成を繰り返すため、1 回で数十円規模になることがあります
• 第14〜15章の音声・リアルタイム系は、音声の入出力分だけテキストより割高になる傾向があります
• Web 検索などの組み込みツール（第3章）には、トークン課金とは別にツール利用料が設定されている場合があります

安全に学習を進めるために、最初に次の 2 つを設定しておくことを強くおすすめします。

1. 支出通知と強制上限の設定 — 支出通知だけではAPIは停止しません。組織またはプロジェクトの Limits → Spend で月額を設定し、停止させたい場合は Enforce a hard limit を有効にします。反映には遅延があり少額の超過が起こり得るため、アプリ側でも反復回数を制限します。公式：Spend limits
2. 使用量ダッシュボードの定期確認 — 章をひとつ終えるごとに使用量ページを見る習慣をつけると、「どの example がどれくらい消費するか」の感覚が身につきます

本書でも、費用が大きくなりがちな example には各章で個別に注意書きを入れています。

まとめ

• AI エージェントとは、LLM が自分でツールを使い、判断し、複数ステップのタスクを遂行するプログラムです。「答えるだけ」のチャットボットとの違いは自律的な行動にあります
• Agents SDK は「少数の部品 + 組み込みのエージェントループ」という設計思想で、Agent / Runner / function tool / handoff / guardrail / session / tracing の組み合わせでエージェントを構築します
• 最小のエージェントは「Agent を定義し、Runner で実行し、final_output を受け取る」の 4 行で書けます
• 学習は「基礎 → 連携 → 実践アプリ → 音声・リアルタイム → 発展」の順がおすすめです
• API は従量課金です。利用上限の設定と使用量の確認を習慣にしましょう

次章では、examples を実際に動かすための環境（Python、uv、リポジトリのクローン、API キー）を整えます。

目次に戻る | 次章: 第1章 環境構築 →

第1章 環境構築 — 公式 examples を動かす準備

この章では、OpenAI Agents SDK（openai-agents v0.22.2、Python 3.10 以上）の公式リポジトリに含まれる examples（サンプルコード集）を、自分のパソコンで実際に動かせる状態にします。手を動かしながら 1 ステップずつ進めれば、最後には最初のエージェントが動きます。

この章のゴール:

• [ ] Python 3.10 以上が使える
• [ ] uv がインストールされている
• [ ] リポジトリを clone して依存関係をインストールした
• [ ] OpenAI API キーを取得し、環境変数に設定した
• [ ] examples/basic/hello_world.py が動いた

この 5 つのゴールは、次の一本道で繋がっています。

1. Python 3.10 以上を用意する

OpenAI Agents SDK は Python 3.10 以上 を必須としています（リポジトリの pyproject.toml に requires-python = ">=3.10" と定義されています）。v0.22.2 時点でサポート対象として明記されているのは 3.10 / 3.11 / 3.12 / 3.13 / 3.14 です。

1-1. バージョンを確認する

1. ターミナル（macOS は「ターミナル」、Windows は「PowerShell」、Linux は任意のシェル）を開きます。
2. 次のコマンドを実行します。

python --version

3. Python 3.10.0 以上（例: Python 3.12.4）と表示されれば OK です。python コマンドが見つからない場合や 2.x 系が表示される場合は、python3 --version も試してください。

1-2. Python をインストールする（バージョンが足りない場合）

macOS:

1. Homebrew が入っていれば brew install python を実行します。
2. または python.org のダウンロードページ から最新版のインストーラを取得して実行します。

Windows:

1. python.org のダウンロードページ からインストーラを取得します。
2. インストール時に 「Add python.exe to PATH」のチェックを必ず入れて ください（これを忘れると python コマンドが認識されません）。
3. winget install Python.Python.3.12 でもインストールできます。

Linux:

1. Ubuntu 22.04 以降であれば標準の Python が 3.10 以上です。sudo apt install python3 python3-venv で不足分を導入します。
2. それ以前のディストリビューションの場合は、後述の uv で Python 自体を導入するのが簡単です（uv python install 3.12）。

2. uv をインストールする

2-1. uv とは何か

uv は、Rust 製の高速な Python パッケージマネージャです。パッケージマネージャとは、ライブラリ（他人が作った再利用可能なコード）のインストールやバージョン管理を自動化してくれるツールのことです。uv は従来の pip（インストール）と venv（仮想環境 = プロジェクトごとに独立したライブラリ置き場）の役割を 1 つにまとめ、しかも非常に高速に動作します。

OpenAI Agents SDK のリポジトリは uv を公式の開発ツールとして採用しており、依存関係を固定した uv.lock ファイルが同梱されています。そのため examples を動かすなら uv を使うのが最も確実 です。

2-2. インストール手順（公式手順）

1. OS に応じて次のコマンドを実行します。

   macOS / Linux:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Windows (PowerShell):

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. ターミナルを開き直し、インストールを確認します。

   uv --version

   バージョン番号が表示されれば成功です。詳細は uv 公式ドキュメント を参照してください。

3. リポジトリを clone して uv sync する（推奨ルート）

本書と同じサンプルを再現できるように v0.22.2 タグを指定します。別のバージョンを使うときは、そのリリースの変更点を確認してください。

examples をすべて動かすための推奨ルートです。以降の章のコマンドはすべて「この手順を完了し、リポジトリのルートディレクトリにいる」前提で書かれています。

1. Git がインストールされていることを確認します（git --version）。入っていない場合は macOS なら xcode-select --install、Windows なら Git for Windows、Linux なら sudo apt install git などで導入します。

2. リポジトリを clone（リモートのソースコード一式を手元に複製）します。

   git clone --branch v0.22.2 https://github.com/openai/openai-agents-python.git
   cd openai-agents-python

3. 依存関係をインストールします。

   uv sync

   uv sync は、uv.lock に記録された正確なバージョンのライブラリ群を、プロジェクト専用の仮想環境（.venv ディレクトリ）に自動で構築するコマンドです。Python の仮想環境を手動で作成・有効化する必要はありません。以降は uv run <コマンド> と打つだけで、この仮想環境の中でコマンドが実行されます。

補足: リポジトリの Makefile には make sync というターゲットがあり、これは uv sync --all-extras --all-packages --group dev を実行して追加依存（後述の extras）を含むすべてを一括インストールします。まずは素の uv sync で十分です。音声などの extras は必要になった章で追加します（本章の第 7 節参照）。

4. OpenAI API キーを取得して設定する

エージェントの頭脳である LLM（Large Language Model: 大規模言語モデル。文章を理解・生成する AI モデル）は OpenAI のサーバー上で動きます。手元のコードからそれを呼び出すために API キー（あなたのアカウントを識別する秘密の文字列）が必要です。

4-1. アカウントを作成する

1. ブラウザで platform.openai.com を開きます。
2. 「Sign up」からアカウントを作成します（Google アカウント等でも登録できます）。
3. 注意: ChatGPT の有料プラン（ChatGPT Plus など）と API の課金は完全に別物 です。ChatGPT に課金していても API は使えません。API 用に別途課金設定が必要です。

4-2. API キーを発行する

1. ログイン後、ダッシュボードの API keys ページ を開きます。
2. 「Create new secret key」をクリックし、任意の名前（例: agents-sdk-learning）を付けて作成します。
3. sk- で始まる文字列が表示されます。この画面を閉じると二度と表示されない ので、パスワードマネージャ等の安全な場所に控えてください。
4. キーは他人に見せない・コードに直接書かない・Git にコミットしないのが鉄則です。漏洩するとあなたのアカウントで課金され続けます。

4-3. 課金設定と使用上限

1. Billing ページ で支払い方法を登録し、クレジット（前払い残高。最低 5 ドル程度から）を購入します。残高がゼロだと API 呼び出しはエラーになります。
2. API は 従量課金 です。料金はトークン（token: LLM が文章を処理する最小単位。文字数との比率はモデル・文章により異なる）の消費量に応じて発生します。費用はモデル・履歴・推論量・ツール・反復回数で変わります。実行前に公式料金表を確認し、実行後は usage を記録します。
3. 事故防止のため、Limits ページ の Spend で月額を設定します。通知だけなら到達後もAPIは続きます。停止を必要とする場合は Enforce a hard limit を有効にします。組織・プロジェクトの強制上限到達時は 429 と organization_spend_limit_exceeded / project_spend_limit_exceeded が返ります。反映遅延による少額の超過はあり得ます。公式：支出制御

4-4. 環境変数 OPENAI_API_KEY を設定する

SDK は 環境変数（OS がプログラムに渡す設定値）OPENAI_API_KEY から自動的にキーを読み取ります。

注意: このリポジトリの examples は .env ファイル（環境変数をファイルに書いておく仕組み）を読み込まない構成です。必ず環境変数として直接設定してください。

macOS / Linux（現在のターミナルセッションのみ有効）:

export OPENAI_API_KEY=sk-...

ターミナルを閉じると消えるので、毎回設定するのが面倒な場合はシェルの設定ファイル（zsh なら ~/.zshrc、bash なら ~/.bashrc）に同じ行を追記し、source ~/.zshrc などで再読み込みします。

Windows PowerShell（現在のセッションのみ有効）:

$env:OPENAI_API_KEY = "sk-..."

Windows（永続的に設定する場合）:

setx OPENAI_API_KEY "sk-..."

setx で設定した値は 新しく開いたターミナルから 有効になります。実行中のウィンドウには反映されない点に注意してください。

設定できたか確認する:

# macOS / Linux
echo $OPENAI_API_KEY

# Windows PowerShell
echo $env:OPENAI_API_KEY

sk- で始まる文字列が表示されれば OK です。

5. 最初の実行 — hello_world.py

いよいよ最初のエージェントを動かします。リポジトリのルート（openai-agents-python ディレクトリ）で次を実行してください。

uv run python examples/basic/hello_world.py

uv run は「このプロジェクトの仮想環境の中でコマンドを実行する」という意味です。仮想環境の有効化（activate）を意識する必要はありません。

実行されるコードは次のとおりです（examples/basic/hello_world.py）。

import asyncio

from agents import Agent, Runner


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)
    # Function calls itself,
    # Looping in smaller pieces,
    # Endless by design.


if __name__ == "__main__":
    asyncio.run(main())

Agent（エージェントの定義: 名前と instructions = 指示文を持つ）を作り、Runner（エージェントを実際に実行するクラス）で「プログラミングの再帰について教えて」と依頼しています。async / await は非同期処理（ネットワーク応答などの待ち時間に他の処理を進められる Python の仕組み）の構文で、SDK の基本スタイルです。詳しくは次章で解説します。

期待される出力例（コード中のコメントにある例）:

Function calls itself,
Looping in smaller pieces,
Endless by design.

instructions で「俳句（haiku）でのみ答える」と指示しているため、英語の三行詩が返ってきます。LLM の出力は毎回変わるので、コメントと一言一句同じにはなりません。三行の俳句らしきテキストが表示されれば 環境構築は成功 です。エラーが出た場合は本章末尾のトラブルシューティングを参照してください。

6. 代替ルート: pip + venv で自作スクリプトを動かす

「リポジトリは clone せず、自分のプロジェクトに SDK を入れて書きたい」という pip 派の方は、公式 README にあるとおり次の手順でも始められます。

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python -m pip install "openai-agents==0.22.2"

1. python -m venv .venv で仮想環境を作成します。
2. source .venv/bin/activate（Windows は .venv\Scripts\activate）で有効化します。
3. python -m pip install "openai-agents==0.22.2" で SDK をインストールします。
4. 前節の hello_world.py と同じ内容のファイルを作成し、python hello_world.py で実行します。

音声機能など追加依存が必要な場合は python -m pip install 'openai-agents[voice]==0.22.2' のように角括弧付きで指定します。

ただし、本書のように公式 examples を一通り動かすのが目的なら、第 3 節の「clone + uv sync」ルートを推奨 します。examples にはリポジトリ内のヘルパーモジュール（後述の examples/auto_mode.py など）を import するものがあり、単体のファイルコピーでは動かないためです。

7. 追加依存（extras）一覧 — どの章で何が必要になるか

SDK 本体は軽量に保たれており、音声やデータベース連携などの機能は extras（オプションの追加依存グループ）として分離されています。pyproject.toml の [project.optional-dependencies] に定義されており、必要なものだけ次のように追加インストールします。

# 例: voice extra を追加してインストール
uv sync --extra voice

# 複数指定する場合
uv sync --extra voice --extra litellm

# すべての extras を一括で入れる場合（Makefile の make sync と同等）
uv sync --all-extras --all-packages --group dev

本書の章立て（examples のカテゴリ）との対応は次のとおりです。basic・handoffs・agent_patterns など大半の章は extras なしの uv sync だけで動きます。

各章の冒頭でも「この章で必要な extras」を明記するので、今すべて覚える必要はありません。「エラーで ModuleNotFoundError が出たら extras の入れ忘れを疑う」とだけ覚えておいてください。

この対応関係を図にすると、次のようになります。

主要な依存ライブラリのバージョン（v0.22.2 時点）

uv sync を使う限り意識する必要はありませんが、既存プロジェクトへ組み込むときに衝突しやすいので挙げておきます。

example をまとめて流す（make examples-run）

v0.22.0 のリポジトリには examples/README.md が追加され、example 群の一括実行はリポジトリのランナーと Make ターゲットが担当することが明記されました。1 本ずつ動かす本書の進め方とは別に、全体をまとめて回したいときはこちらを使えます。

# 前景で一括実行
make examples-run

# 対象を絞る / サーバー・音声系も含める
make examples-run EXAMPLES_ARGS="--filter basic"
make examples-run EXAMPLES_ARGS="--include-server --include-audio"

# バックグラウンド実行とその管理
make examples-run-background
make examples-status
make examples-stop
make examples-logs
make examples-tail

既定では自動入力・自動承認が有効で、対話的 example は含まれますが、サーバー系・音声系・外部サービス系は明示的に選択しない限り除外されます。実行ログは .tmp/examples-start-logs/ の下に、全体ログと example ごとのログとして残ります。

なお、このランナーは各 example を python -m <モジュールパス> の形式で起動します。from examples.web_search_utils import ... のようにリポジトリ内の共通モジュールを import する example があるためです。本書でも該当する example では -m 付きの実行コマンドを示します。

8. examples ディレクトリの歩き方

examples/ 配下は機能カテゴリごとのサブディレクトリ（basic、tools、handoffs、agent_patterns、mcp、memory、model_providers、voice、realtime、research_bot など）に分かれています。本書は第2章以降、このカテゴリを 1 つずつ順番に解説していきます。

ディレクトリ直下には example 本体のほかに、実行を補助する 2 つのファイルがあります。

8-1. run_examples.py — examples の一括実行ランナー

examples/run_examples.py は、examples 配下のスクリプトをまとめて実行・検証するためのランナーです。主な機能は次のとおりです。

• if __name__ == "__main__": ガードを持つ example ファイルを自動検出して順に実行する
• 対話入力が必要なもの・サーバーとして動き続けるもの・マイク/スピーカーが必要なもの・Redis 等の外部サービスが必要なものは、既定ではスキップする（--include-interactive / --include-server / --include-audio / --include-external で個別に含められます）
• 実行ログを .tmp/examples-start-logs/ に example ごとに保存し、失敗したものの再実行リストを .tmp/examples-rerun.txt に書き出せる
• 環境変数 EXAMPLES_UV_EXTRAS（空白区切りで extras 名を指定）を設定すると、各 example を uv run --extra <名前> ... 付きで起動する

使い方の例:

# 何が実行対象になるかコマンドだけ確認する（API は呼ばれない）
uv run python examples/run_examples.py --dry-run

# パスに "basic" を含む example だけ実行する
uv run python examples/run_examples.py --filter basic

# 対話プロンプトに自動応答しながら実行する（auto mode）
uv run python examples/run_examples.py --auto-mode --filter basic

課金注意: フィルタなしの一括実行は多数の API 呼び出しを発生させます。学習中はまず --dry-run で対象を確認し、--filter で範囲を絞って使ってください。

8-2. auto_mode.py — 対話 example を自動応答させるヘルパー

examples/auto_mode.py は直接実行するファイルではなく、対話型 example が import するヘルパーモジュールです。環境変数 EXAMPLES_INTERACTIVE_MODE=auto が設定されていると、input_with_fallback()（キーボード入力の代わりに既定値を返す）や confirm_with_fallback()（承認プロンプトに自動で Yes/No を返す）が働き、人間の入力なしで example を最後まで走らせられます。前述の run_examples.py --auto-mode は、内部的にこの環境変数を設定して動いています。

本書で「この example は対話型です」と出てきたら、手で入力して試すか、EXAMPLES_INTERACTIVE_MODE=auto を付けて自動実行するかを選べる、と覚えておいてください。

どちらの実行コマンドを使うかは、その example がリポジトリ内の共通モジュールを import しているかどうかで決まります。

9. トレーシング — エージェントの動きを可視化する

SDK には tracing（トレーシング: プログラムの実行過程を記録・可視化する仕組み）が標準で組み込まれており、追加設定なしで有効になっています。

1. hello_world.py などの example を実行します。
2. ブラウザで platform.openai.com/traces を開きます。
3. 直近の実行が一覧に表示され、クリックすると「どのエージェントが」「どんな入力を受けて」「LLM を何回呼び、どのツールを使い、何を出力したか」がタイムラインで確認できます。

エージェントは内部で複数ステップを自律的に実行するため、「なぜこの答えになったのか」を追うにはトレースが不可欠です。以降の章で handoff（エージェント間の引き継ぎ）やツール呼び出しが登場すると、このトレース画面の価値が実感できるはずです。example を動かしたら traces ページを見る、という習慣をつけることをお勧めします。

10. トラブルシューティング

10-1. 「api_key を設定せよ」というエラーが出る

症状: 実行時に次のようなエラーで停止する。

openai.OpenAIError: The api_key client option must be set either by passing
api_key to the client or by setting the OPENAI_API_KEY environment variable

原因: 環境変数 OPENAI_API_KEY が現在のターミナルに設定されていません。

対処:

1. echo $OPENAI_API_KEY（Windows PowerShell は echo $env:OPENAI_API_KEY）で値を確認します。
2. 空なら第 4-4 節の手順で設定し直します。export はターミナルを閉じると消えること、Windows の setx は新しいターミナルでのみ有効になることを思い出してください。

10-2. 401 Unauthorized（認証エラー）

症状: Error code: 401 や invalid_api_key を含むエラー。

原因: キーの値が間違っている、失効している、またはコピー時に余分な文字が混入しています。

対処:

1. 設定した値の先頭が sk- で始まっているか、前後に空白や引用符が紛れ込んでいないかを確認します。
2. API keys ページ でキーが削除・無効化されていないか確認し、必要なら新しいキーを発行して設定し直します。

10-3. 429 Too Many Requests（レート制限 / クレジット不足）

症状: Error code: 429。429 には原因が 2 種類あるので、エラーメッセージ本文で見分けます。

• rate_limit_exceeded を含む場合: レート制限（一定時間あたりの API 呼び出し回数・トークン量の上限）に達しています。数十秒待って再実行するか、run_examples.py の一括実行なら対象を絞ります。アカウントの利用実績に応じて上限は自動的に引き上がっていきます。
• insufficient_quota や You exceeded your current quota を含む場合: クレジット残高が不足 しています。Billing ページ で残高を確認し、クレジットを追加購入してください。新規アカウントで一度も課金設定をしていない場合もこのエラーになります。

10-4. モデルが見つからない / アクセス権がない

症状: model_not_found や、指定モデルへのアクセスがない旨の 404 / 403 エラー。

原因: SDK がモデル未指定時に使う既定モデル（v0.22.2 では gpt-5.6-luna。v0.20.0 で gpt-5.4-mini から変更されました）に、あなたのアカウントがまだアクセスできない場合があります。新しいモデルは組織の認証状態や利用実績によって開放時期が異なります。

対処:

1. Limits ページ 等で自分のアカウントが使えるモデルを確認します。

2. 環境変数 OPENAI_DEFAULT_MODEL で既定モデルを差し替えられます。例:

   export OPENAI_DEFAULT_MODEL=gpt-4.1-mini
   uv run python examples/basic/hello_world.py

3. コード側で Agent(name=..., instructions=..., model="gpt-4.1-mini") のように明示指定する方法は次章で扱います。

10-5. 社内プロキシ環境で接続できない

症状: 会社のネットワークで Connection error、接続タイムアウト、または SSL 証明書エラー（certificate verify failed 等）が出る。

原因: 社内プロキシ（外部通信を中継・検査するサーバー）経由でないと外部に出られない環境では、プロキシ設定と社内 CA 証明書の指定が必要です。

対処:

1. プロキシの URL を環境変数で指定します。

   export HTTPS_PROXY=http://proxy.example.com:8080
   export HTTP_PROXY=http://proxy.example.com:8080

2. SSL 検査を行うプロキシの場合は、社内 CA 証明書のパスを SSL_CERT_FILE / REQUESTS_CA_BUNDLE に設定します（証明書ファイルの入手先は社内のネットワーク管理者に確認してください）。
3. そもそも api.openai.com への通信が許可されているかをネットワーク管理者に確認してください。許可されていない場合、設定では解決できません。

ここまでの 5 パターンを早見表にすると、次のようになります。

まとめ

• Python 3.10 以上と uv を用意し、git clone + uv sync で examples 実行環境を構築しました
• API キーは platform.openai.com で発行し、環境変数 OPENAI_API_KEY に設定します（従量課金のため使用上限の設定を推奨）
• uv run python examples/basic/hello_world.py で最初のエージェントが動くことを確認しました
• 追加機能は extras（uv sync --extra voice 等）で必要な章ごとに導入します
• 実行後は platform.openai.com/traces でエージェントの内部動作を確認できます

次章からは examples/basic/ のコードを 1 本ずつ読み解きながら、Agent と Runner の基礎、ストリーミング、ツール呼び出しといった SDK の基本機能を学んでいきます。

第2章 基礎機能（basic）

前提知識

• 第1章（環境構築）: リポジトリのクローン、uv sync による依存関係のインストール、OPENAI_API_KEY の設定が済んでいることを前提とします。この章のコマンドはすべてリポジトリのルートディレクトリ（openai-agents-python/）で実行します
• Python の基本文法（関数、クラス、デコレータ、型ヒント）を読めること
• async / await の構文を見たことがあること（詳しい意味はこの章の概念解説で補足します）

概念解説

エージェントとは「指示書を持った新人アシスタント」

OpenAI Agents SDK における Agent は、LLM（Large Language Model: 大量のテキストから学習した、文章を生成する AI モデル）に「名前」と「指示書（instructions）」を与えたものです。日常の比喩で言えば、Agent は「業務マニュアルを渡された新人アシスタント」です。マニュアル（instructions）に「返答はすべて俳句で」と書けば俳句で答えますし、「あなたは丁寧なサポート担当です」と書けばその役割を演じます。

そして Runner は、そのアシスタントに仕事を依頼して結果を受け取る「マネージャー」役です。Runner.run(agent, "質問文") と呼び出すと、SDK 内部で次の エージェントループ が回ります。

1. 現在の Agent の指示と入力を LLM に送る
2. LLM が最終的な回答を返したらループ終了
3. LLM が「ツールを使いたい」と言えばツールを実行して結果を LLM に戻し、ループ続行
4. LLM が「他の Agent に任せたい」と言えば handoff（ハンドオフ: 担当エージェントの交代）してループ続行

この章の examples は、このループの入口（Hello World）から、途中経過の観察（ストリーミング・フック）、道具の持たせ方（ツール）、渡せる入力の種類（画像・ファイル）までを一つずつ体験するものです。

非同期処理について

examples のほとんどは async def main() と asyncio.run(main()) という形をしています。非同期処理とは、「LLM からの返事を待っている間、プログラムが他の作業もできるようにする仕組み」です。LLM の応答には数秒かかることが多いため、SDK は非同期を基本としています。書き方としては「await を付けて結果を待つ」「async def の関数は asyncio.run() で起動する」の 2 点を押さえれば examples は読めます。同期版の Runner.run_sync() も用意されています。

ストリーミングについて

ストリーミングとは、LLM が文章を最後まで生成し終えるのを待たず、生成中のテキストを断片（デルタ）として順次受け取る仕組みです。手紙が完成してから郵送してもらうのが通常の Runner.run()、電話口で相手が話すそばから聞き取るのがストリーミング（Runner.run_streamed()）だとイメージしてください。チャット UI で文字がパラパラと表示されるのはこの仕組みによるものです。

実行コマンドの前提

この章のコマンドはすべて、第1章で準備したリポジトリのルートで実行します。ほとんどの example は環境変数 OPENAI_API_KEY が設定されている必要があります（例外は Ollama を使う hello_world_gpt_oss.py）。

なお、一部の example は examples/auto_mode.py という共通モジュールを from examples.auto_mode import ... の形で import しています。これらは Python のパッケージとして実行する必要があるため、uv run python -m examples.basic.<モジュール名> 形式で起動します。それ以外の単独スクリプトは uv run python examples/basic/<ファイル名>.py で起動できます。各 example の実行手順に個別に明記します。

また、対話入力を求める example は、環境変数 EXAMPLES_INTERACTIVE_MODE=auto を設定すると既定値で自動実行できます（CI などで人手の入力なしに走らせるための仕組みです）。

各 example の解説

2.1 Hello World と最初の一歩

まずは「Agent を作って Runner で走らせる」という SDK の最小サイクルを体験します。あわせて、モデルの切り替え・指示（システムプロンプト）の動的生成・プロンプトテンプレートという「最初の一歩の応用」もここで扱います。

hello_world.py

SDK の最小構成です。俳句でしか答えない Agent を作り、1 回だけ実行して結果を表示します。

import asyncio

from agents import Agent, Runner


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)
    # Function calls itself,
    # Looping in smaller pieces,
    # Endless by design.


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• Agent(name=..., instructions=...): Agent の定義はこれだけです。instructions はいわゆるシステムプロンプト（LLM に対して会話全体の前提として与える指示文）に相当します。model を指定していない点に注目してください。省略時は SDK の既定モデル（本バージョン v0.22.2 では gpt-5.6-luna。v0.20.0 で gpt-5.4-mini から変更されました。環境変数 OPENAI_DEFAULT_MODEL で変更可能）が使われます
• await Runner.run(agent, "..."): 第 1 引数に開始 Agent、第 2 引数にユーザー入力（文字列）を渡します。戻り値は RunResult オブジェクトです
• result.final_output: 実行結果のうち「最後の Agent が出した最終回答」を取り出すプロパティです。output_type（後述）を指定していない場合は文字列になります

実行手順

1. OPENAI_API_KEY が設定されていることを確認します（echo $OPENAI_API_KEY）
2. リポジトリルートで次を実行します

uv run python examples/basic/hello_world.py

期待される動作・出力例

再帰（recursion）についての俳句が 1 つ表示されます。コード中のコメントにある通り、例えば次のような出力です。

Function calls itself,
Looping in smaller pieces,
Endless by design.

つまずきポイント

• OPENAI_API_KEY 未設定だと認証エラーになります。API キーは「SDK が OpenAI クライアントを最初に作った時点」で読み込まれるため、実行前にシェルで export しておく必要があります
• 出力は LLM の生成結果なので、実行のたびに内容は変わります。コメントの出力例と一字一句同じにはなりません

hello_world_gpt_5.py

モデルを明示指定し、ModelSettings で推論の深さ（reasoning effort）と回答の冗長さ（verbosity）を調整する example です。

import asyncio

from openai.types.shared import Reasoning

from agents import Agent, ModelSettings, Runner


async def main():
    agent = Agent(
        name="Knowledgeable GPT-5 Assistant",
        instructions="You're a knowledgeable assistant. You always provide an interesting answer.",
        model="gpt-5.6-sol",
        model_settings=ModelSettings(
            reasoning=Reasoning(effort="low"),  # "none", "low", "medium", "high", "xhigh"
            verbosity="low",  # "low", "medium", "high"
        ),
    )
    result = await Runner.run(agent, "Tell me something about recursion in programming.")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• model="gpt-5.6-sol": Agent 単位でモデル名を文字列指定できます
• ModelSettings(reasoning=..., verbosity=...): モデル呼び出し時のパラメータをまとめるオブジェクトです。reasoning.effort は「回答前にどれだけ考えるか」、verbosity は「回答をどれだけ詳しく書くか」の調整で、いずれも reasoning 系モデル（回答前に内部で思考を行うモデル）向けの設定です
• ファイル冒頭のコメントには、Responses API ではなく Chat Completions API（従来型の OpenAI API）を使いたい場合に OpenAIChatCompletionsModel を作って Agent に渡す方法が示されています

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/hello_world_gpt_5.py

期待される動作・出力例

再帰に関する「興味深い」説明が、verbosity="low" のため比較的簡潔に表示されます。

つまずきポイント

• 指定したモデル（ここでは gpt-5.6-sol）が自分の API アカウントで利用できない場合はエラーになります。その場合は model を利用可能なモデル名に変更してください

hello_world_gpt_oss.py

OpenAI のクラウドではなく、ローカルマシンの Ollama（オープンソースの LLM 実行ツール）で動く gpt-oss モデルを使う example です。「OpenAI 互換 API を持つ別のサーバー」に SDK を接続する基本パターンでもあります。

import asyncio

from openai import AsyncOpenAI

from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled

set_tracing_disabled(True)

gpt_oss_model = OpenAIChatCompletionsModel(
    model="gpt-oss:20b",
    openai_client=AsyncOpenAI(
        base_url="http://localhost:11434/v1",
        api_key="ollama",
    ),
)


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You're a helpful assistant. You provide a concise answer to the user's question.",
        model=gpt_oss_model,
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• set_tracing_disabled(True): トレーシング（実行履歴を OpenAI のダッシュボードに送って可視化する機能）を無効化します。トレーシングは OpenAI の API キーを使ってアップロードされるため、OpenAI API を使わない構成では切っておくのが定石です
• AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="ollama"): 接続先を Ollama のローカルサーバーに向けています。Ollama は API キーを検証しないため、api_key はダミー文字列で構いません
• OpenAIChatCompletionsModel(model=..., openai_client=...): Chat Completions 形式でモデルを呼び出すラッパーです。これを Agent の model にオブジェクトとして渡します

実行手順

1. Ollama をインストールし、起動します
2. モデルを取得します: ollama pull gpt-oss:20b（約 13GB のダウンロードと相応のメモリが必要です）
3. 次を実行します（OPENAI_API_KEY は不要です）

uv run python examples/basic/hello_world_gpt_oss.py

期待される動作・出力例

ローカルモデルによる再帰の簡潔な説明が表示されます。クラウドのモデルより応答に時間がかかることがあります。

つまずきポイント

• Ollama が起動していない、またはモデル未取得だと接続エラーになります
• コード中のコメントにある通り、gpt-oss 系モデルでは独自の output_type（構造化出力）がうまく動かないことがあります。既定のテキスト出力で使うのが無難です

hello_world_jupyter.ipynb

Jupyter Notebook（ブラウザ上でコードを対話的に実行できる環境）で SDK を動かす example です。ノートブックのセルは次の 1 つだけです。

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

# Intended for Jupyter notebooks where there's an existing event loop
result = await Runner.run(agent, "Write a haiku about recursion in programming.")  # type: ignore[top-level-await]  # noqa: F704
print(result.final_output)

コード解説

• 通常のスクリプトでは asyncio.run(main()) が必要でしたが、Jupyter にはあらかじめイベントループ（非同期処理を回す仕組み）が動いているため、セル内で直接 await が書けます。asyncio.run() を使うと逆に「イベントループが既に動いている」というエラーになります

実行手順

1. Jupyter を追加して起動します（リポジトリの依存には含まれないため --with で一時追加します）

uv run --with jupyter jupyter lab examples/basic/hello_world_jupyter.ipynb

2. OPENAI_API_KEY が Jupyter 起動時のシェルに設定されていることを確認し、セルを実行します

期待される動作・出力例

再帰についての俳句が出力されます（ノートブックには実行済みの出力例が保存されています）。

つまずきポイント

• 普通の .py ファイルにこのコードをコピーすると「トップレベル await は使えない」という構文エラーになります。スクリプトでは asyncio.run() を使ってください

dynamic_system_prompt.py

instructions を固定文字列ではなく関数として渡し、実行時の状況（コンテキスト）に応じてシステムプロンプトを動的に切り替える example です。

@dataclass
class CustomContext:
    style: Literal["haiku", "pirate", "robot"]


def custom_instructions(
    run_context: RunContextWrapper[CustomContext], agent: Agent[CustomContext]
) -> str:
    context = run_context.context
    if context.style == "haiku":
        return "Only respond in haikus."
    elif context.style == "pirate":
        return "Respond as a pirate."
    else:
        return "Respond as a robot and say 'beep boop' a lot."


agent = Agent(
    name="Chat agent",
    instructions=custom_instructions,
)

async def main():
    context = CustomContext(style=random.choice(["haiku", "pirate", "robot"]))
    print(f"Using style: {context.style}\n")

    user_message = "Tell me a joke."
    print(f"User: {user_message}")
    result = await Runner.run(agent, user_message, context=context)

    print(f"Assistant: {result.final_output}")

コード解説

• コンテキストとは、実行中のツールやフックなど「自分の Python コード側」で共有したいデータの入れ物です。ここでは CustomContext という dataclass に応答スタイルを入れています。重要な性質として、コンテキストオブジェクトは LLM には送信されません。あくまでローカルのデータ共有用です
• instructions=custom_instructions: 関数を渡すと、LLM 呼び出しの直前に毎回この関数が呼ばれ、戻り値の文字列がシステムプロンプトとして使われます。関数は RunContextWrapper（コンテキストを包む SDK のラッパー）と Agent を受け取ります
• Runner.run(agent, user_message, context=context): context= で自作オブジェクトを実行に持ち込みます

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します（結果が変わるので何度か実行してみてください）

uv run python examples/basic/dynamic_system_prompt.py

期待される動作・出力例

3 スタイルからランダムに 1 つ選ばれ、そのスタイルでジョークが返ります。

Using style: robot

User: Tell me a joke.
Assistant: Beep boop! Why was the robot so bad at soccer? Beep boop... because it kept kicking up a debug! Beep boop!

つまずきポイント

• 1 回の実行に関わる Agent・ツール・フックはすべて同じ型のコンテキストを使う必要があります。型がバラバラだと型チェックエラーや実行時の混乱の元になります

prompt_template.py

OpenAI プラットフォーム上に保存した「プロンプトテンプレート」（変数を埋め込める再利用可能なプロンプト定義）を Agent から使う example です。instructions を書く代わりに、ダッシュボードで管理しているプロンプトの ID を参照します。

async def static_prompt(prompt_id: str):
    agent = Agent(
        name="Assistant",
        prompt={
            "id": prompt_id,
            "version": "1",
            "variables": {
                "poem_style": "limerick",
            },
        },
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)

動的版では、prompt にも関数を渡せます。

async def _get_dynamic_prompt(data: GenerateDynamicPromptData):
    ctx: DynamicContext = data.context.context
    return {
        "id": ctx.prompt_id,
        "version": "1",
        "variables": {
            "poem_style": ctx.poem_style,
        },
    }


async def dynamic_prompt(prompt_id: str):
    context = DynamicContext(prompt_id)

    agent = Agent(
        name="Assistant",
        prompt=_get_dynamic_prompt,
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.", context=context)
    print(result.final_output)

コード解説

• prompt={"id": ..., "version": ..., "variables": {...}}: プラットフォーム側で定義したテンプレートの ID・バージョン・変数の値を指定します。テンプレート本文（例: Write a poem in {{poem_style}}）はダッシュボード側にあり、コードには含まれません
• 動的版は GenerateDynamicPromptData を受け取る関数を渡し、実行のたびに変数（ここではランダムに選んだ詩の形式）を差し替えます

実行手順

このファイル冒頭の NOTE にある通り、そのままでは動きません。コードに書かれた既定のプロンプト ID はあなたのプロジェクトには存在しないためです。

1. https://platform.openai.com/playground/prompts を開きます
2. プロンプト変数 poem_style を作成します
3. システムプロンプト本文を Write a poem in {{poem_style}} として保存し、発行されたプロンプト ID（pmpt_...）を控えます
4. OPENAI_API_KEY を設定し、次を実行します

# 静的テンプレート版
uv run python examples/basic/prompt_template.py --prompt-id pmpt_あなたのID

# 動的テンプレート版
uv run python examples/basic/prompt_template.py --dynamic --prompt-id pmpt_あなたのID

期待される動作・出力例

静的版では limerick（五行戯詩）形式で、動的版では limerick / haiku / ballad のいずれかの形式で、再帰についての詩が出力されます。動的版は [debug] DynamicContext initialized with poem_style: haiku のようなデバッグ行が先に表示されます。

つまずきポイント

• --prompt-id を渡し忘れると既定 ID が使われ、「プロンプトが見つからない」エラーになります
• プロンプトテンプレートは OpenAI Responses API 専用の機能です

2.2 ストリーミング

Runner.run_streamed() は RunResultStreaming を返し、stream_events() を async for で回すことでイベントを受信します。イベントには粒度の異なる 3 種類があります。

• raw_response_event: LLM から届く生イベント（トークン単位のテキスト差分など）。トークンとは LLM が文章を処理する最小単位（おおよそ単語や文字の断片）のことです
• run_item_stream_event: 「メッセージが 1 件完成した」「ツールが呼ばれた」などアイテム単位の高レベルイベント
• agent_updated_stream_event: handoff などで現在の Agent が切り替わったことの通知

stream_text.py

もっとも基本的な「テキストを 1 トークンずつ表示する」example です。全文引用します。

import asyncio

from openai.types.responses import ResponseTextDeltaEvent

from agents import Agent, Runner


async def main():
    agent = Agent(
        name="Joker",
        instructions="You are a helpful assistant.",
    )

    result = Runner.run_streamed(agent, input="Please tell me 5 jokes.")
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="", flush=True)


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• Runner.run_streamed(...) には await を付けません。戻り値の RunResultStreaming から stream_events() を async for で消費することで実行が進みます
• ResponseTextDeltaEvent は OpenAI Responses API の「テキスト差分」イベント型です。event.data.delta に新しく生成された数文字が入っています
• print(..., end="", flush=True): 改行せず、バッファリングもせずに即座に画面へ出すことで「タイプライターのように文字が流れる」表示になります

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/stream_text.py

期待される動作・出力例

5 つのジョークが、少しずつ画面に流れながら表示されます。

つまずきポイント

• ストリーミング実行は stream_events() のイテレータが終わるまで完了しません。途中で break すると後処理（セッション保存など）が済まないことがあるため、基本は最後まで消費します
• result.final_output はストリーム完了後にはじめて値が入ります

stream_items.py

トークン単位ではなく「ツールが呼ばれた」「メッセージが完成した」というアイテム単位でイベントを受け取る example です。ジョークの数をツールで決めてから、その数だけジョークを言う Agent を使います。

@tool
def how_many_jokes() -> int:
    """Return a random integer of jokes to tell between 1 and 10 (inclusive)."""
    return random.randint(1, 10)


async def main():
    agent = Agent(
        name="Joker",
        instructions="First call the `how_many_jokes` tool, then tell that many jokes.",
        tools=[how_many_jokes],
    )

    result = Runner.run_streamed(
        agent,
        input="Hello",
    )
    print("=== Run starting ===")
    async for event in result.stream_events():
        # We'll ignore the raw responses event deltas
        if event.type == "raw_response_event":
            continue
        elif event.type == "agent_updated_stream_event":
            print(f"Agent updated: {event.new_agent.name}")
            continue
        elif event.type == "run_item_stream_event":
            if event.item.type == "tool_call_item":
                print(f"-- Tool was called: {getattr(event.item.raw_item, 'name', 'Unknown Tool')}")
            elif event.item.type == "tool_call_output_item":
                print(f"-- Tool output: {event.item.output}")
            elif event.item.type == "message_output_item":
                print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}")
            else:
                pass  # Ignore other event types

    print("=== Run complete ===")

コード解説

• @tool: Python 関数をエージェントの道具（function tool）に変換するデコレータです。v0.19.0 で追加された agents.decorators モジュールの短縮エイリアスで、実体は従来からある function_tool と同一です（tool = function_tool）。公式 examples は v0.19.0 以降この短い書き方に統一されましたが、from agents import function_tool と書く従来のコードもそのまま動きます。詳細は 2.4 節で扱います
• raw_response_event は continue で読み飛ばし、高レベルイベントだけを処理しています。UI で「ツール実行中…」のような進捗表示を出したい場合はこの粒度が便利です
• ItemHelpers.text_message_output(item): メッセージアイテムからテキスト部分だけを取り出すヘルパーです

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/stream_items.py

期待される動作・出力例

=== Run starting ===
Agent updated: Joker
-- Tool was called: how_many_jokes
-- Tool output: 4
-- Message output:
 Sure, here are four jokes for you:
 ...
=== Run complete ===

ツールが返した数（1〜10 のランダム）だけジョークが並びます。

stream_function_call_args.py

LLM がツールを呼ぶときの引数そのものが JSON として少しずつ生成される様子をストリーミングで観察する example です。ファイル作成や設定生成のようにツール引数が長くなるケースで、「いま何を作ろうとしているか」をリアルタイム表示できます。

主要部分を引用します。

    async for event in result.stream_events():
        if event.type == "raw_response_event":
            # Function call started
            if event.data.type == "response.output_item.added":
                if getattr(event.data.item, "type", None) == "function_call":
                    function_name = getattr(event.data.item, "name", "unknown")
                    call_id = getattr(event.data.item, "call_id", "unknown")

                    function_calls[call_id] = {"name": function_name, "arguments": ""}
                    current_active_call_id = call_id
                    print(f"\n📞 Function call streaming started: {function_name}()")
                    print("📝 Arguments building...")

            # Real-time argument streaming
            elif isinstance(event.data, ResponseFunctionCallArgumentsDeltaEvent):
                if current_active_call_id and current_active_call_id in function_calls:
                    function_calls[current_active_call_id]["arguments"] += event.data.delta
                    print(event.data.delta, end="", flush=True)

            # Function call completed
            elif event.data.type == "response.output_item.done":
                if hasattr(event.data.item, "call_id"):
                    call_id = getattr(event.data.item, "call_id", "unknown")
                    if call_id in function_calls:
                        function_info = function_calls[call_id]
                        print(f"\n✅ Function call streaming completed: {function_info['name']}")

コード解説

• response.output_item.added イベントで「ツール呼び出しが始まった」ことを検知し、call_id（呼び出しごとの識別子）をキーに引数を蓄積する辞書を用意します
• ResponseFunctionCallArgumentsDeltaEvent が引数 JSON の差分です。{"filename": "main.py", ...} のような JSON が数文字ずつ届きます
• response.output_item.done で 1 つのツール呼び出しの引数生成が完了したと分かります
• ツール定義側では Annotated[str, "Name of the file"] のように型ヒントへ説明を添えています。これはツールのパラメータ説明として LLM に伝わります

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/stream_function_call_args.py

期待される動作・出力例

「FastAPI プロジェクトを作って」という入力に対し、write_file や create_config の引数 JSON が流れながら表示され、最後に全ツール呼び出しのサマリと最終回答が表示されます。

📞 Function call streaming started: create_config()
📝 Arguments building...
{"project_name":"my-app","version":"1.0.0","dependencies":["fastapi","uvicorn"]}
✅ Function call streaming completed: create_config

つまずきポイント

• この example のツールは実際にはファイルを作りません（文字列を返すだけのダミーです）。ストリーミングの観察が目的です

stream_ws.py

この章で最も高機能な example です。OpenAI Responses API を WebSocket（サーバーと接続を張りっぱなしにして双方向通信する仕組み。リクエストごとに接続し直す HTTP より低遅延）経由で使い、次の要素を一度に実演します。

• responses_websocket_session() による接続の再利用
• 通常の function tool（lookup_order）
• Agent.as_tool(...) で別の Agent を「ツールとして」呼び出すパターン
• @tool(needs_approval=True) による HITL（Human-in-the-loop: 人間の承認を挟む）フロー
• previous_response_id による 2 ターン目の会話継続

ファイル冒頭の docstring に必要な環境変数がまとまっています。

"""Responses websocket streaming example with function tools, agent-as-tool, and approval.

...

Required environment variable:
- `OPENAI_API_KEY`

Optional environment variables:
- `OPENAI_MODEL` (defaults to `gpt-5.6-sol`)
- `OPENAI_BASE_URL`
- `OPENAI_WEBSOCKET_BASE_URL`
- `EXAMPLES_INTERACTIVE_MODE=auto` (auto-approve HITL prompts for scripted runs)
"""

承認が必要なツールの定義と、エージェントの組み立て部分を見てみます。

@tool(needs_approval=True)
def submit_refund(order_id: str, amount: float, reason: str) -> dict[str, Any]:
    """Create a refund request. This tool requires approval."""
    ticket = "RF-1001" if order_id == "ORD-1001" else f"RF-{order_id[-4:]}"
    return {
        "refund_ticket": ticket,
        "order_id": order_id,
        "amount": amount,
        "reason": reason,
        "status": "approved_pending_processing",
    }

    support_agent = Agent(
        name="SupportAgent",
        instructions=(
            "You are a support agent. For refund requests, do this in order: "
            "1) call lookup_order, 2) call refund_policy_specialist, 3) if the user "
            "asked to proceed and the order is eligible, call submit_refund. "
            "When asked for only the refund ticket, return only the ticket token "
            "(for example RF-1001)."
        ),
        tools=[
            lookup_order,
            policy_agent.as_tool(
                tool_name="refund_policy_specialist",
                tool_description="Check refund eligibility and explain the policy decision.",
            ),
            submit_refund,
        ],
        model=model_name,
        model_settings=ModelSettings(
            max_tokens=200,
            reasoning=Reasoning(effort="medium", summary="detailed"),
        ),
    )

承認の待ち受けとレジューム（再開）はこう書かれています。

        if not result.interruptions:
            break

        state = result.to_state()
        for interruption in result.interruptions:
            question = f"Approve {interruption.name} with args {interruption.arguments}?"
            if ask_approval(question):
                state.approve(interruption)
            else:
                state.reject(interruption)

        result = ws.run_streamed(agent, state)

コード解説

• async with responses_websocket_session() as ws: で WebSocket 対応のセッションを開き、ws.run_streamed(...) で実行します。複数ターンや agent-as-tool の入れ子呼び出しでも同じ接続を温存でき、毎回の再接続を避けられます
• policy_agent.as_tool(...): handoff（担当交代）と違い、呼び出し元の Agent が主導権を持ったまま、別の Agent を 1 つのツールとして実行して結果だけ受け取ります
• needs_approval=True のツールが呼ばれそうになると、ストリームがいったん終わり result.interruptions に「承認待ち」が入ります。result.to_state() で実行状態（RunState）を取り出し、approve / reject した上で ws.run_streamed(agent, state) に渡すと続きから再開されます
• 2 ターン目は previous_response_id=first_response_id を渡すことで、1 ターン目の会話をサーバー側の記録から引き継ぎます（詳細は 2.7 節の previous_response_id.py 参照）
• trace("Responses WS support example") で 2 ターンを 1 つのトレース（実行履歴のまとまり）として記録しています

実行手順

1. OPENAI_API_KEY を設定します（任意で OPENAI_MODEL も）
2. examples.auto_mode を import しているため、モジュール形式で実行します

uv run python -m examples.basic.stream_ws

3. 実行中に [approval] Approve submit_refund with args {...}? [y/N]: と聞かれたら y を入力します。対話なしで流したい場合は EXAMPLES_INTERACTIVE_MODE=auto uv run python -m examples.basic.stream_ws とします（自動承認されます）

期待される動作・出力例

推論サマリ（Reasoning:）と回答（Assistant:）が流れ、[tool call] lookup_order(...) → [tool call] refund_policy_specialist(...) → 承認プロンプト → [tool call] submit_refund(...) と進み、1 ターン目の最終出力として返金チケット RF-1001 が表示されます。2 ターン目では「さっき作ったチケットは？」に対し、履歴を再送せずに RF-1001 と答えます。

つまずきポイント

• WebSocket トランスポートはアカウント/モデルによっては未開放のことがあります。その場合、この example は「Websocket mode closed before sending events. This usually means the feature is not enabled for this account/model yet.」と表示して終了します
• ストリームを消費し終える前に async with を抜けると、共有接続が強制切断されることがあります

2.3 ライフサイクルとフック

フック（hook）とは、「実行の節目（開始・終了・ツール実行・handoff など）に自動で呼ばれる自作の関数群」です。ホテルに例えると、客の到着・チェックイン・チェックアウトのたびに通知を受け取るコンシェルジュのようなものです。ログ記録、監視、デバッグに使います。

フックには 2 段階あります。

• AgentHooks: 特定の Agent に取り付け、その Agent に関するイベントだけを受け取る（agent.hooks に設定）
• RunHooks: 実行（run）全体 に取り付け、すべての Agent・LLM 呼び出し・ツールのイベントを受け取る（Runner.run(..., hooks=...) に渡す）

agent_lifecycle_example.py

AgentHooks を継承したクラスで、Agent ごとのイベント（開始・終了・ツール開始/終了・handoff）を数えながら表示する example です。乱数を生成し、奇数なら別の Agent に handoff して 2 倍にする、という 2 エージェント構成です。

フック定義の中心部分を引用します。

class CustomAgentHooks(AgentHooks):
    def __init__(self, display_name: str):
        self.event_counter = 0
        self.display_name = display_name

    async def on_start(self, context: AgentHookContext, agent: Agent) -> None:
        self.event_counter += 1
        # Access the turn_input from the context to see what input the agent received
        print(
            f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} started with turn_input: {context.turn_input}"
        )

    async def on_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None:
        self.event_counter += 1
        print(
            f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} ended with output {output}"
        )

    async def on_handoff(self, context: RunContextWrapper, agent: Agent, source: Agent) -> None:
        self.event_counter += 1
        print(
            f"### ({self.display_name}) {self.event_counter}: Agent {source.name} handed off to {agent.name}"
        )

エージェントの組み立てはこうです。

multiply_agent = Agent(
    name="Multiply Agent",
    instructions="Multiply the number by 2 and then return the final result.",
    tools=[multiply_by_two],
    output_type=FinalResult,
    hooks=CustomAgentHooks(display_name="Multiply Agent"),
)

start_agent = Agent(
    name="Start Agent",
    instructions="Generate a random number. If it's even, stop. If it's odd, hand off to the multiply agent.",
    tools=[random_number],
    output_type=FinalResult,
    handoffs=[multiply_agent],
    hooks=CustomAgentHooks(display_name="Start Agent"),
)

コード解説

• hooks=CustomAgentHooks(...): Agent ごとに別インスタンスを渡しているため、イベントカウンタも Agent ごとに独立します
• on_start の第 1 引数 AgentHookContext からは context.turn_input（その Agent がそのターンに受け取った入力）を参照できます
• handoffs=[multiply_agent]: Start Agent が「奇数だったら」Multiply Agent に担当を交代できるようにしています。handoff が起きると、引き継ぎ先 の on_handoff フックが呼ばれます
• output_type=FinalResult: Pydantic モデル（データの型と検証を定義する Python ライブラリのクラス）を指定すると、最終出力が自由文ではなく FinalResult(number=74) のような構造化データになります
• ソース中のコメントにある通り、on_tool_start / on_tool_end はローカルの function tool のみが対象で、OpenAI サーバー側で実行される hosted tool（WebSearchTool など。第3章参照）では呼ばれません
• ツール random_number には auto mode（EXAMPLES_INTERACTIVE_MODE=auto）のとき決定的な奇数を返す分岐が入っています。デモで必ず handoff まで進むようにするための工夫です

実行手順

1. OPENAI_API_KEY を設定します
2. examples.auto_mode を import しているため、モジュール形式で実行します

uv run python -m examples.basic.agent_lifecycle_example

3. Enter a max number: と聞かれたら適当な整数（例: 250）を入力します。対話なしなら EXAMPLES_INTERACTIVE_MODE=auto を付けて実行します（既定値 50 が使われます）

期待される動作・出力例（ファイル末尾の docstring より）

Enter a max number: 250
### (Start Agent) 1: Agent Start Agent started
### (Start Agent) 2: Agent Start Agent started tool random_number
### (Start Agent) 3: Agent Start Agent ended tool random_number with result 37
### (Start Agent) 4: Agent Start Agent handed off to Multiply Agent
### (Multiply Agent) 1: Agent Multiply Agent started
### (Multiply Agent) 2: Agent Multiply Agent started tool multiply_by_two
### (Multiply Agent) 3: Agent Multiply Agent ended tool multiply_by_two with result 74
### (Multiply Agent) 4: Agent Multiply Agent ended with output number=74
Done!

つまずきポイント

• 乱数が偶数だと handoff は起きず、Start Agent がそのまま終了します。handoff のログを見たい場合は何度か実行してください（または auto mode を使ってください）

lifecycle_example.py

同じ 2 エージェント構成を題材に、今度は RunHooks（実行全体のフック） を主役にした example です。AgentHooks との併用と、各イベント時点での累積トークン使用量の表示が見どころです。

RunHooks 側の抜粋です。

class ExampleHooks(RunHooks):
    def __init__(self):
        self.event_counter = 0

    def _usage_to_str(self, usage: Usage) -> str:
        return f"{usage.requests} requests, {usage.input_tokens} input tokens, {usage.output_tokens} output tokens, {usage.total_tokens} total tokens"

    async def on_agent_start(self, context: AgentHookContext, agent: Agent) -> None:
        self.event_counter += 1
        print(
            f"### {self.event_counter}: Agent {agent.name} started. turn_input: {context.turn_input}. Usage: {self._usage_to_str(context.usage)}"
        )

    async def on_llm_start(
        self,
        context: RunContextWrapper,
        agent: Agent,
        system_prompt: str | None,
        input_items: list[TResponseInputItem],
    ) -> None:
        self.event_counter += 1
        print(f"### {self.event_counter}: LLM started. Usage: {self._usage_to_str(context.usage)}")

ツールフックでは ToolContext へのキャストにより呼び出しメタデータを取得しています。

    async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
        self.event_counter += 1
        # While this type cast is not ideal,
        # we don't plan to change the context arg type in the near future for backwards compatibility.
        tool_context = cast(ToolContext[Any], context)
        print(
            f"### {self.event_counter}: Tool {tool.name} started. name={tool_context.tool_name}, call_id={tool_context.tool_call_id}, args={tool_context.tool_arguments}. Usage: {self._usage_to_str(tool_context.usage)}"
        )

実行時に hooks= として渡します。

        await Runner.run(
            start_agent,
            hooks=hooks,
            input=f"Generate a random number between 0 and {max_number}.",
        )

コード解説

• RunHooks は on_agent_start / on_agent_end / on_llm_start / on_llm_end / on_tool_start / on_tool_end / on_handoff を持ち、実行全体を横断して呼ばれます。Agent 個別の AgentHooks（この例では LoggingHooks）と併用できます
• context.usage: どのフックでも、その時点までの累積使用量（Usage）を参照できます。LLM 呼び出しが終わるたびに requests とトークン数が増えていく様子が観察できます
• on_tool_start / on_tool_end に渡されるコンテキストは実際には ToolContext で、tool_name / tool_call_id / tool_arguments（LLM が指定した引数の JSON 文字列）が取れます
• on_handoff は RunHooks では from_agent / to_agent の 2 つを受け取る形で、AgentHooks 版（agent / source）と引数構成が異なる点に注意してください

実行手順

1. OPENAI_API_KEY を設定します
2. モジュール形式で実行します

uv run python -m examples.basic.lifecycle_example

3. Enter a max number: に整数を入力します（auto mode 可）

期待される動作・出力例（ファイル末尾の docstring より抜粋）

### 1: Agent Start Agent started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens
### 2: LLM started. Usage: 0 requests, 0 input tokens, 0 output tokens, 0 total tokens
### 3: LLM ended. Usage: 1 requests, 143 input tokens, 15 output tokens, 158 total tokens
### 4: Tool random_number started. name=random_number, call_id=call_..., args={"max":250}. ...
...
### 16: Agent Multiply Agent ended with output number=214. Usage: 4 requests, 660 input tokens, 56 output tokens, 716 total tokens
Done!

つまずきポイント

• 出力例と同じく 16 イベントになるとは限りません。乱数が偶数なら handoff が起きず、イベント数は減ります

2.4 ツールの基礎

function tool は、Python 関数に @tool（別名 @function_tool）デコレータを付けるだけで「LLM が呼び出せる道具」になる仕組みです。関数の型ヒントから引数スキーマが、docstring から説明文が自動生成され、LLM に伝えられます。LLM は「どのツールをどんな引数で使うか」を自分で判断します。

tools.py

function tool の最小構成です。天気を返すダミーツールを持つ Agent に「東京の天気は？」と尋ねます。全文引用します。

import asyncio
from typing import Annotated

from pydantic import BaseModel, Field

from agents import (
    Agent,
    Runner,
)
from agents.decorators import tool


class Weather(BaseModel):
    city: str = Field(description="The city name")
    temperature_range: str = Field(description="The temperature range in Celsius")
    conditions: str = Field(description="The weather conditions")


@tool
def get_weather(city: Annotated[str, "The city to get the weather for"]) -> Weather:
    """Get the current weather information for a specified city."""
    print("[debug] get_weather called")
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")


agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)


async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)
    # The weather in Tokyo is sunny.


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• @tool を付けた get_weather は、関数名がツール名に、docstring がツールの説明に、Annotated[str, "..."] の注釈が引数の説明になります
• from agents.decorators import tool の tool は function_tool のエイリアスです（v0.19.0 で追加）。from agents import function_tool と書いて @function_tool を使っても挙動は完全に同じで、公式ドキュメントも API リファレンス上は function_tool を正式名として扱っています。本書では examples の実物に合わせて @tool 表記を用います
• 戻り値は Pydantic モデルでも構いません。ツールの結果は文字列化されて LLM に渡され、LLM がそれを踏まえて最終回答を作文します
• 実行の流れは「LLM が get_weather(city="Tokyo") の呼び出しを決定 → SDK が関数を実行 → 結果を LLM に返す → LLM が自然文で回答」というエージェントループの 1 周です

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/tools.py

期待される動作・出力例

[debug] get_weather called
The weather in Tokyo is currently sunny with wind, and the temperature ranges from 14°C to 20°C.

[debug] 行が出ていれば、LLM が実際にツールを呼んだ証拠です。

つまずきポイント

• ツールを渡しても、LLM が「呼ぶ必要がない」と判断すれば呼びません。確実に呼ばせたい場合は instructions で明示するか、ModelSettings(tool_choice=...) を使います（この example では質問内容から自然に呼ばれます）

tool_guardrails.py

guardrail（ガードレール）とは、エージェントの入出力を検証して危険な動作を止める安全チェックの仕組みです。この example はその中でもツール単位の guardrail、すなわち「ツールに渡される引数（入力）」と「ツールが返した結果（出力）」を検査する仕組みを実演します。

入力 guardrail の例です。

@tool_input_guardrail
def reject_sensitive_words(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    """Reject tool calls that contain sensitive words in arguments."""
    try:
        args = json.loads(data.context.tool_arguments) if data.context.tool_arguments else {}
    except json.JSONDecodeError:
        return ToolGuardrailFunctionOutput(output_info="Invalid JSON arguments")

    # Check for suspicious content
    sensitive_words = [
        "password",
        "hack",
        "exploit",
        "malware",
        "ACME",
    ]
    for key, value in args.items():
        value_str = str(value).lower()
        for word in sensitive_words:
            if word.lower() in value_str:
                # Reject tool call and inform the model the function was not called
                return ToolGuardrailFunctionOutput.reject_content(
                    message=f"🚨 Tool call blocked: contains '{word}'",
                    output_info={"blocked_word": word, "argument": key},
                )

    return ToolGuardrailFunctionOutput(output_info="Input validated")

出力 guardrail は 2 種類の対応が示されています。

@tool_output_guardrail
def block_sensitive_output(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
    """Block tool outputs that contain sensitive data."""
    output_str = str(data.output).lower()

    # Check for sensitive data patterns
    if "ssn" in output_str or "123-45-6789" in output_str:
        # Use raise_exception to halt execution completely for sensitive data
        return ToolGuardrailFunctionOutput.raise_exception(
            output_info={"blocked_pattern": "SSN", "tool": data.context.tool_name},
        )

    return ToolGuardrailFunctionOutput(output_info="Output validated")

guardrail のツールへの取り付けは属性代入で行います。

# Apply guardrails to tools
send_email.tool_input_guardrails = [reject_sensitive_words]
get_user_data.tool_output_guardrails = [block_sensitive_output]
get_contact_info.tool_output_guardrails = [reject_phone_numbers]

コード解説

guardrail 関数の戻り値 ToolGuardrailFunctionOutput には 3 通りの挙動があります。

1. そのまま通す: ToolGuardrailFunctionOutput(output_info=...) を返す（チェック合格）
2. reject_content: ツール呼び出し（または結果）を差し止め、代わりに message を LLM に伝えて実行自体は継続する。LLM は「その操作はできなかった」ことを踏まえて回答を続けます
3. raise_exception: ToolOutputGuardrailTripwireTriggered 例外を発生させて実行全体を停止する。SSN（米国の社会保障番号）のような重大な情報漏えいの恐れがある場合の最終手段です

main 関数では 4 つのシナリオ（正常送信 / 入力ブロック / 例外で停止 / 出力差し止め）を順に試します。

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/tool_guardrails.py

期待される動作・出力例（ファイル末尾の docstring より）

=== Tool Guardrails Example ===

1. Normal email sending:
✅ Successful tool execution: I've sent a welcome email to john@example.com ...

2. Attempting to send email with suspicious content:
❌ Guardrail rejected function tool call: I'm unable to send the email as mentioning ACME Corp. is restricted.

3. Attempting to get user data (contains SSN). Execution blocked:
🚨 Output guardrail triggered: Execution halted for sensitive data
   Details: {'blocked_pattern': 'SSN', 'tool': 'get_user_data'}

4. Rejecting function tool output containing sensitive data:
❌ Guardrail rejected function tool output: I'm unable to retrieve the contact info for user456 ...

つまずきポイント

• ここで扱ったのは「ツール単位」の guardrail です。エージェント全体の入出力に掛ける guardrail（@input_guardrail / @output_guardrail）は別章（agent_patterns）で扱います
• シナリオ 2 と 4 は reject（継続）、シナリオ 3 は例外（停止）と、止め方の強さが違う点を意識して出力を読み比べてください

image_tool_output.py

ツールの戻り値として画像を LLM に渡す example です。通常ツールの結果は文字列ですが、ToolOutputImage 型（またはそれに対応する辞書）を返すと、画像そのものがモデルへの入力になります。全文引用します。

import asyncio

from agents import (
    Agent,
    Runner,
    ToolOutputImage,
    ToolOutputImageDict,
)
from agents.decorators import tool

return_typed_dict = True

URL = "https://images.unsplash.com/photo-1505761671935-60b3a7427bad?auto=format&fit=crop&w=400&q=80"


@tool
def fetch_random_image() -> ToolOutputImage | ToolOutputImageDict:
    """Fetch a random image."""

    print("Image tool called")
    if return_typed_dict:
        return {"type": "image", "image_url": URL, "detail": "auto"}

    return ToolOutputImage(image_url=URL, detail="auto")


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
        tools=[fetch_random_image],
    )

    result = await Runner.run(
        agent,
        input="Fetch an image using the random_image tool, then describe it",
    )
    print(result.final_output)
    """This image features the famous clock tower, commonly known as Big Ben, ..."""


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• ToolOutputImage(image_url=..., detail=...): image_url には通常の URL のほか data URL（Base64 埋め込み）も指定でき、代わりに事前アップロード済みファイルの file_id も使えます。detail は画像認識の解像度（"low" / "high" / "auto"）です
• ToolOutputImageDict は同じ内容を TypedDict（辞書）で表現したもので、return_typed_dict フラグで両方の書き方を示しています。どちらを返しても動作は同じです

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/image_tool_output.py

期待される動作・出力例

Image tool called に続き、URL の画像（ロンドンの時計塔ビッグ・ベン）の描写が表示されます。

つまずきポイント

• 画像を理解できる（vision 対応の）モデルで実行する必要があります。既定モデルは対応しています

2.5 画像・ファイル入力

Runner.run() の入力は文字列だけでなく、OpenAI Responses API 形式の「入力アイテムのリスト」も渡せます。これを使うと、画像や PDF をユーザーメッセージとして添付できます。4 つの example は「画像 or ファイル」×「ローカル or リモート」の組み合わせです。

local_image.py

ローカルの JPEG 画像（examples/basic/media/image_bison.jpg、バイソンの写真）を Base64（バイナリデータをテキスト文字列に変換する符号化方式）で埋め込んで送る example です。

FILEPATH = os.path.join(os.path.dirname(__file__), "media/image_bison.jpg")


def image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode("utf-8")
    return encoded_string

    result = await Runner.run(
        agent,
        [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_image",
                        "detail": "auto",
                        "image_url": f"data:image/jpeg;base64,{b64_image}",
                    }
                ],
            },
            {
                "role": "user",
                "content": "What do you see in this image?",
            },
        ],
    )
    print(result.final_output)

コード解説

• 入力がリスト形式になっています。1 件目のユーザーメッセージが画像（type: "input_image"）、2 件目が質問文です
• image_url に data:image/jpeg;base64,... という data URL を渡すことで、ファイルの中身ごとリクエストに埋め込みます。外部から到達できないローカル画像でも送れるのがこの方式の利点です
• os.path.dirname(__file__) 基準でパスを組み立てているので、どのディレクトリから実行しても画像が見つかります

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/local_image.py

期待される動作・出力例

「草原に立つバイソン（アメリカバイソン）が写っています」といった画像描写が表示されます。

つまずきポイント

• Base64 化するとデータ量が約 1.33 倍になります。大きな画像はリクエストサイズ制限に注意してください

remote_image.py

Web 上の画像 URL をそのまま渡す example です。全文引用します。

import asyncio

from agents import Agent, Runner

URL = "https://images.unsplash.com/photo-1505761671935-60b3a7427bad?auto=format&fit=crop&w=400&q=80"


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
    )

    result = await Runner.run(
        agent,
        [
            {
                "role": "user",
                "content": [{"type": "input_image", "detail": "auto", "image_url": URL}],
            },
            {
                "role": "user",
                "content": "What do you see in this image?",
            },
        ],
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• local_image.py との違いは image_url が data URL ではなく普通の URL である点だけです。画像の取得は OpenAI 側のサーバーが行うため、URL はインターネットから到達可能である必要があります

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/remote_image.py

期待される動作・出力例

URL の画像（ビッグ・ベンの時計塔）の描写が表示されます。

local_file.py

ローカルの PDF ファイル（examples/basic/media/partial_o3-and-o4-mini-system-card.pdf）を Base64 で添付し、内容について質問する example です。

FILEPATH = os.path.join(os.path.dirname(__file__), "media/partial_o3-and-o4-mini-system-card.pdf")

    b64_file = file_to_base64(FILEPATH)
    result = await Runner.run(
        agent,
        [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "file_data": f"data:application/pdf;base64,{b64_file}",
                        "filename": "partial_o3-and-o4-mini-system-card.pdf",
                    }
                ],
            },
            {
                "role": "user",
                "content": "What is the first sentence of the introduction?",
            },
        ],
    )
    print(result.final_output)

コード解説

• 画像との違いは、コンテンツ型が input_file になり、file_data（data URL 形式の中身）と filename を指定する点です
• PDF はモデル側でテキストとページ画像として解釈され、内容に関する質問に答えられます

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/local_file.py

期待される動作・出力例

同梱 PDF（OpenAI o3/o4-mini システムカードの抜粋）の introduction 冒頭の一文が引用されて表示されます。

remote_pdf.py

Web 上の PDF を URL 指定で渡す example です。全文引用します。

import asyncio

from agents import Agent, Runner

URL = "https://www.berkshirehathaway.com/letters/2024ltr.pdf"


async def main():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
    )

    result = await Runner.run(
        agent,
        [
            {
                "role": "user",
                "content": [{"type": "input_file", "file_url": URL}],
            },
            {
                "role": "user",
                "content": "Can you summarize the letter?",
            },
        ],
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• リモート PDF は file_data ではなく file_url を使います（remote_image.py の image_url に対応する書き方です）
• 題材はバークシャー・ハサウェイ社の 2024 年株主向けレター（ウォーレン・バフェット氏の書簡）です

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/remote_pdf.py

期待される動作・出力例

レターの要約（投資方針、後継者、業績などのポイント）が数段落で表示されます。PDF が長いため、他の example より応答に時間がかかり、消費トークンも多くなります。

つまずきポイント

• リモート URL の PDF は取得可能な公開 URL である必要があります。リンク切れや認証付き URL では失敗します

2.6 出力型（output_type）の応用

non_strict_output_type.py

output_type による構造化出力（回答を自由文ではなく決まった JSON 構造で受け取る仕組み）には、既定で strict モードが使われます。strict モードは「必ずスキーマ通りの有効な JSON が返る」ことを保証しますが、対応できるスキーマに制約があります。この example は、strict 非対応のスキーマをどう扱うかを 3 段階で示します。

問題となる型は「整数をキーにした辞書」です。

@dataclass
class OutputType:
    jokes: dict[int, str]
    """A list of jokes, indexed by joke number."""

dict[int, str] のように任意のキーを持つ辞書は strict モードのスキーマ制約（追加プロパティ禁止など）を満たせません。main 関数は次の 3 段階を順に試します。

async def main():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
        output_type=OutputType,
    )

    input = "Tell me 3 short jokes."

    # First, let's try with a strict output type. This should raise an exception.
    try:
        await Runner.run(agent, input)
    except UserError as e:
        print(f"Error (expected): {e}")
    else:
        raise AssertionError("Strict schema validation should have raised UserError")

    # Now let's try again with a non-strict output type. This should work.
    # In some cases, it will raise an error - the schema isn't strict, so the model may
    # produce an invalid JSON object.
    agent.output_type = AgentOutputSchema(OutputType, strict_json_schema=False)
    try:
        result = await Runner.run(agent, input)
        print(result.final_output)
    except ModelBehaviorError as e:
        print(f"Non-strict output validation failed (expected possibility): {e}")

    # Finally, let's try a custom output type.
    agent.output_type = CustomOutputSchema()
    result = await Runner.run(agent, input)
    print(result.final_output)

3 段階目の完全自作スキーマは AgentOutputSchemaBase を継承して作ります。

class CustomOutputSchema(AgentOutputSchemaBase):
    """A demonstration of a custom output schema."""

    def is_plain_text(self) -> bool:
        return False

    def name(self) -> str:
        return "CustomOutputSchema"

    def json_schema(self) -> dict[str, Any]:
        return {
            "type": "object",
            "properties": {"jokes": {"type": "object", "properties": {"joke": {"type": "string"}}}},
        }

    def is_strict_json_schema(self) -> bool:
        return False

    def validate_json(self, json_str: str) -> Any:
        json_obj = json.loads(json_str)
        # Just for demonstration, we'll return a list.
        return list(json_obj["jokes"].values())

コード解説

1. output_type=OutputType をそのまま使う → strict 変換できず例外（意図的な失敗例）
2. AgentOutputSchema(OutputType, strict_json_schema=False) に差し替える → strict を諦めて動かす。ただし JSON の正しさが保証されなくなるため、モデルが不正な JSON を返すと ModelBehaviorError が起きうる（コードもそれを try/except で受けています）
3. AgentOutputSchemaBase を継承した CustomOutputSchema → JSON スキーマの生成（json_schema）と検証・変換（validate_json）を完全に自作。この例では検証時にジョークの辞書をリストに変換して返しており、final_output の型すら自由に決められることを示しています

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/non_strict_output_type.py

期待される動作・出力例

1 行目に「Error (expected): ...」という strict 変換エラー、続いて非 strict モードでのジョーク辞書（例: OutputType(jokes={1: '...', 2: '...', 3: '...'})）、最後にカスタムスキーマによるジョークのリストが表示されます。

つまずきポイント

• 最初のエラーは仕様通りの失敗です。壊れているわけではありません
• どのスキーマが strict 対応かは OpenAI の構造化出力ドキュメント（コード冒頭のコメントにリンクがあります）を参照してください。迷ったら「Pydantic の BaseModel で、固定フィールドのみ」の形にしておくのが安全です

2.7 その他（usage、previous_response_id、リトライ）

usage_tracking.py

実行で消費したトークン数と API リクエスト数を集計・表示する example です。トークン使用量はそのまま API 料金に直結するため、実運用では必ず押さえたい機能です。

def print_usage(usage: Usage) -> None:
    print("\n=== Usage ===")
    print(f"Input tokens: {usage.input_tokens}")
    print(f"Output tokens: {usage.output_tokens}")
    print(f"Total tokens: {usage.total_tokens}")
    print(f"Requests: {usage.requests}")
    for i, request in enumerate(usage.request_usage_entries):
        print(f"  {i + 1}: {request.input_tokens} input, {request.output_tokens} output")


async def main() -> None:
    agent = Agent(
        name="Usage Demo",
        instructions="You are a concise assistant. Use tools if needed.",
        tools=[get_weather],
    )

    result = await Runner.run(agent, "What's the weather in Tokyo?")

    print("\nFinal output:")
    print(result.final_output)

    # Access usage from the run context
    print_usage(result.context_wrapper.usage)

コード解説

• result.context_wrapper.usage: 実行全体の使用量です。ツール呼び出しや handoff を含むすべての LLM 呼び出しの合計が集計されます
• Usage の主なフィールドは requests（API 呼び出し回数）、input_tokens / output_tokens / total_tokens、そして request_usage_entries（リクエストごとの内訳リスト）です
• この example ではツール呼び出しを挟むため LLM が 2 回呼ばれ、Requests: 2 となり内訳も 2 行表示されます

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/usage_tracking.py

期待される動作・出力例

Final output:
The weather in Tokyo is sunny with wind, 14-20°C.

=== Usage ===
Input tokens: 3xx
Output tokens: xx
Total tokens: 4xx
Requests: 2
  1: 1xx input, xx output
  2: 2xx input, xx output

（数値は実行ごとに変わります）

つまずきポイント

• LiteLLM などサードパーティ経由のモデルでは、プロバイダによって使用量が既定で返らないことがあります。その場合は ModelSettings(include_usage=True) が必要です

previous_response_id.py

会話の 2 ターン目以降で、過去のやり取りを再送せずに会話を継続する example です。OpenAI Responses API はサーバー側に応答を保存しており、previous_response_id に前回の応答 ID を渡すだけで文脈を引き継げます。

非ストリーミング版の核心部分です。

async def main():
    print("=== Non-streaming Example ===")
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant. be VERY concise.",
    )

    result = await Runner.run(agent, "What is the largest country in South America?")
    print(result.final_output)
    # Brazil

    result = await Runner.run(
        agent,
        "What is the capital of that country?",
        previous_response_id=result.last_response_id,
    )
    print(result.final_output)
    # Brasilia

ストリーミング版（main_stream）も同じ考え方で、Runner.run_streamed(..., previous_response_id=result.last_response_id) を使います。

コード解説

• 2 ターン目の入力は「その国の首都は？」だけです。「その国」が何を指すかは、previous_response_id=result.last_response_id によってサーバー側に保存された 1 ターン目の文脈から解決されます
• result.last_response_id: 直近のモデル応答の ID です。これを次の実行に渡すのがパターンの全てです
• ファイル冒頭の docstring に重要な注意が 2 つあります。(1) この機能は OpenAI Responses API 専用で、他のモデルではこのパラメータは無視されます。(2) 応答の保存期間は執筆時点で 30 日のため、本番では応答 ID と有効期限をセットで保存し、期限切れの際は会話履歴の再送にフォールバックする設計が必要です

実行手順

1. OPENAI_API_KEY を設定します
2. examples.auto_mode を import しているため、モジュール形式で実行します

uv run python -m examples.basic.previous_response_id

3. Run in stream mode? (y/n): と聞かれるので、n（通常実行）か y（ストリーミング実行）を入力します。EXAMPLES_INTERACTIVE_MODE=auto を付けると両方が連続実行されます

期待される動作・出力例

=== Non-streaming Example ===
Brazil
Brasília

2 ターン目が「Brasília」と答えられれば、履歴を再送せずに文脈が引き継がれたことの証明です。

つまずきポイント

• 会話履歴の引き継ぎには、この方式のほかに result.to_input_list() で履歴をローカル管理する方法や、session 機能（別章で解説）もあります。「サーバー側に任せるか、手元で持つか」の設計判断です

retry.py

LLM の API 呼び出しは、レート制限（429）やサーバーエラー（5xx）など一時的な失敗が起こりえます。この example は、SDK に組み込まれたリトライ（自動再試行）設定を ModelSettings(retry=...) で構成する方法を示します。

リトライポリシーの組み立て部分です。

    apply_policies = retry_policies.any(
        # On OpenAI-backed models, provider_suggested() follows provider retry advice,
        # including fallback retryable statuses when x-should-retry is absent
        # (for example 408/409/429/5xx).
        retry_policies.provider_suggested(),
        retry_policies.retry_after(),
        retry_policies.network_error(),
        retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]),
    )

リトライ設定本体と実行への適用です。

    retry = ModelRetrySettings(
        max_retries=4,
        backoff={
            "initial_delay": 0.5,
            "max_delay": 5.0,
            "multiplier": 2.0,
            "jitter": True,
        },
        policy=policy,
    )

    # RunConfig-level model_settings are shared defaults for the run.
    # If an Agent also defines model_settings, the Agent wins for overlapping
    # keys, while nested objects like retry/backoff are merged.
    run_config = RunConfig(model_settings=ModelSettings(retry=retry))

    agent = Agent(
        name="Assistant",
        instructions="You are a concise assistant. Answer in 3 short bullet points at most.",
        model_settings=ModelSettings(retry=retry),
    )

コード解説

• retry_policies.any(...): 複数の判定条件のうちどれか 1 つでも「リトライすべき」なら再試行する合成ポリシーです。部品として、プロバイダの推奨に従う provider_suggested()、Retry-After ヘッダー（サーバーが指定する待機秒数）に従う retry_after()、ネットワークエラー全般の network_error()、指定 HTTP ステータスの http_status([...]) を組み合わせています
• ModelRetrySettings(max_retries=4, backoff={...}, policy=...): 最大 4 回まで再試行し、待ち時間は 0.5 秒から 2 倍ずつ（最大 5 秒）増やします。これを指数バックオフと呼び、jitter（待ち時間へのランダムなゆらぎ）は再試行の同時集中を避けるための工夫です
• 自作の policy 関数は、合成ポリシーの判定結果（RetryDecision）を横取りして [retry] ... というログを出してから、そのまま判定を返しています。リトライの可視化テクニックです
• コメントにある通り、RunConfig の model_settings は実行全体の既定値、Agent 側の model_settings は個別上書きで、retry や backoff のようなネストした設定はマージされます

実行手順

1. OPENAI_API_KEY を設定します
2. 次を実行します

uv run python examples/basic/retry.py

期待される動作・出力例

Retry support is configured. You will only see [retry] logs if a transient failure happens.

Final output:

- Exponential backoff means waiting longer after each failed retry...

正常時は [retry] ログは出ません。一時的な障害（429 など）が起きたときだけ [retry] retry attempt 1/5 | waiting 0.52s | ... のようなログが挟まります。

つまずきポイント

• 「何も特別なログが出ない」のが正常です。リトライは保険であり、発動しないのが良い状態です
• 質問文自体が「指数バックオフを平易に説明して」なので、出力の内容がそのままこの example の仕組みの解説になっています

retry_litellm.py

retry.py とほぼ同一のコードで、モデル指定だけを LiteLLM（100 以上の LLM プロバイダを共通インターフェースで呼べるアダプタライブラリ）経由に変えた example です。リトライ設定がサードパーティアダプタ経由でも同じように機能することを示します。

差分は Agent の model 指定の 1 点です。

    agent = Agent(
        name="Assistant",
        instructions="You are a concise assistant. Answer in 3 short bullet points at most.",
        # Prefix with litellm/ to route this request through the LiteLLM adapter.
        model="litellm/openai/gpt-4o-mini",
        # This Agent repeats the same retry config for clarity. In real code you
        # can keep shared defaults in RunConfig and only put per-agent overrides
        # here when you need different retry behavior.
        model_settings=ModelSettings(retry=retry),
    )

コード解説

• model="litellm/openai/gpt-4o-mini": モデル名を litellm/ で始めると、SDK は LiteLLM アダプタ経由でリクエストを送ります。litellm/ の後ろは「プロバイダ名/モデル名」で、例えば Anthropic や Gemini のモデルにも同じ書式で切り替えられます
• リトライ設定（ModelRetrySettings / retry_policies）の書き方は retry.py と完全に共通です。モデルの接続先を替えても、信頼性まわりのコードは変えなくてよいことがこの example の要点です

実行手順

1. LiteLLM は追加依存のため、extras 付きで同期します

uv sync --extra litellm

2. OPENAI_API_KEY を設定します（この例の接続先は LiteLLM 経由の OpenAI のため）
3. 次を実行します

uv run python examples/basic/retry_litellm.py

期待される動作・出力例

retry.py と同様に、指数バックオフの説明が箇条書き（3 点以内）で表示されます。障害時のみ [retry] ログが出ます。

つまずきポイント

• uv sync --extra litellm を忘れると、LiteLLM モジュールが見つからない旨の ImportError になります
• LiteLLM 経由では、プロバイダによってはトークン使用量が既定で返らないため、必要なら ModelSettings(include_usage=True) を検討してください

まとめ

• SDK の最小サイクルは「Agent(name, instructions) を作り、Runner.run(agent, 入力) して result.final_output を読む」の 3 手（hello_world.py）。モデルは文字列指定・モデルオブジェクト指定（Ollama 等のローカル LLM 含む）のどちらも可能です
• instructions にも prompt にも関数を渡せて、コンテキスト（Runner.run(..., context=...) で持ち込む自作オブジェクト。LLM には送信されない）に応じた動的な指示が作れます
• ストリーミングは Runner.run_streamed() + stream_events()。トークン差分（raw_response_event）、アイテム完成（run_item_stream_event）、Agent 切り替え（agent_updated_stream_event）の 3 粒度を用途で使い分けます。WebSocket トランスポートと HITL 承認、Agent.as_tool() の組み合わせも可能です
• フックは Agent 単位の AgentHooks と実行全体の RunHooks の 2 段階。どのフックでも context.usage で累積使用量を観察できます
• @tool で Python 関数がそのまま LLM の道具になり、ツール単位の入出力 guardrail で「差し止めて続行（reject_content）」「例外で全停止（raise_exception）」を選べます。ツールは ToolOutputImage で画像も返せます
• 入力はリスト形式にすれば画像（input_image）や PDF（input_file）を、URL でも Base64 埋め込みでも渡せます
• 実務の周辺機能として、使用量集計（result.context_wrapper.usage）、サーバー側での会話継続（previous_response_id と result.last_response_id）、指数バックオフ付き自動リトライ（ModelRetrySettings + retry_policies）、strict 非対応スキーマへの対処（AgentOutputSchema(strict_json_schema=False) / AgentOutputSchemaBase）を押さえました

理解度チェック

解答と解説

参考リンク

• エージェントの実行（Running agents）: https://openai.github.io/openai-agents-python/running_agents/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/running_agents/
• 実行結果（Results）: https://openai.github.io/openai-agents-python/results/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/results/
• ストリーミング（Streaming）: https://openai.github.io/openai-agents-python/streaming/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/streaming/
• エージェント（Agents）: https://openai.github.io/openai-agents-python/agents/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/agents/
• コンテキスト管理（Context management）: https://openai.github.io/openai-agents-python/context/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/context/
• 使用量（Usage）: https://openai.github.io/openai-agents-python/usage/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/usage/
• ガードレール（Guardrails）: https://openai.github.io/openai-agents-python/guardrails/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/guardrails/
• SDK の設定（Configuring the SDK）: https://openai.github.io/openai-agents-python/config/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/config/
• コード例（Examples）: https://openai.github.io/openai-agents-python/examples/ ／ 日本語版: https://openai.github.io/openai-agents-python/ja/examples/

第3章 組み込みツール（tools）

前提知識

この章を読む前に、以下を理解しておくことをおすすめします。

• 第1章: SDK のインストール（git clone → uv sync）、OPENAI_API_KEY の設定、uv run によるスクリプト実行
• 第2章: Agent（エージェントの定義体）と Runner（エージェントを実行するクラス）の基本、Runner.run() / Runner.run_streamed() の使い分け、result.final_output と result.new_items の読み方

また、この章のコードはすべて 非同期処理（async / await を使い、通信などの待ち時間中に他の処理を進められる Python の仕組み）で書かれています。asyncio.run(main()) で非同期関数を起動する形は第2章までと同じです。

概念解説

ツールとは何か

エージェントにとっての「ツール」とは、LLM（大規模言語モデル。文章を理解・生成する AI モデル）が 文章の生成以外の行動を起こすための手段 です。LLM 単体は「知っていることを話す」ことしかできませんが、ツールを渡すことで「Web を検索する」「コードを実行する」「ファイルを編集する」「ブラウザを操作する」といったアクションが可能になります。

比喩で言えば、LLM は非常に博識な「電話相談員」です。電話（テキスト）だけでは調べ物も作業もできませんが、手元に検索端末（WebSearchTool）や電卓付きパソコン（CodeInterpreterTool）、社内資料棚（FileSearchTool）を用意してあげると、実際に手を動かして正確な答えを返せるようになります。

hosted tools と function tools の違い（最重要ポイント）

OpenAI Agents SDK のツールは、「誰がどこで実行するか」 で大きく分類されます。この章の examples を理解する上で最も重要な区別です。

• hosted tools は、レストランの「ルームサービス」のようなものです。注文（ツール呼び出し）を出すと、OpenAI のサーバー内の厨房で調理され、結果だけが返ってきます。あなたの手元では何も実行されないため、準備が簡単で安全ですが、中で何が起きるかは OpenAI 側の仕様に従います。hosted tools は Responses API を使う OpenAI モデル（OpenAIResponsesModel）でのみ利用できます。
• ローカル実行ツール は「食材キットの宅配」に近い形です。モデルが「この操作をしてほしい」というリクエスト（レシピ）を返し、実際の調理（コマンド実行・ファイル編集・マウス操作）は あなたが書いたコードが手元で行います。何を実行するかをモデルが決め、実行そのものは自分の環境で制御できるため、承認フローを挟むといった安全対策が組み込めます。
• function tools は完全な「自炊」です。任意の Python 関数を @tool デコレータ（function_tool の別名）でツール化し、モデルが引数を決めて呼び出します。function tools の基本は第2章（examples/basic/tools.py）で扱ったので、この章では主に hosted tools とローカル実行ツールを扱います。

公式ドキュメントは、この他に「Agents as tools（エージェントをツールとして使う）」「実験的な Codex ツール」を加えた 5 分類で説明しています。Agents as tools は第4章で扱い、Codex ツールはこの章の後半で紹介します。

この分類を図にすると次のようになります。

この章で頻出する用語

• トークン: LLM が文章を処理する際の最小単位（文字や単語の断片。文字数との比率は一定ではない）。API 利用料はトークン数に応じて課金されます。
• ストリーミング: モデルの応答を、完成を待たずに少しずつ受け取る仕組み。Runner.run_streamed() で利用します。
• ベクトルストア（vector store）: 文書を「意味を表す数値の並び（ベクトル）」に変換して保存し、キーワードの一致ではなく意味の近さで検索できる OpenAI 上のデータベース。FileSearchTool の裏側で使われます。
• サンドボックス: 外部への影響を遮断した、隔離された安全な実行環境。CodeInterpreterTool のコードはサンドボックス内で動きます。
• コンテナ: OpenAI サーバー上に用意される、独立した仮想の実行環境。hosted の ShellTool はこの中でコマンドを実行します。
• trace（トレーシング）: エージェントの実行過程（どのツールをいつ呼んだか等）を記録する仕組み。with trace("名前"): で囲むと、OpenAI ダッシュボードの Traces ページで実行の様子を確認できます。
• human-in-the-loop（HITL）: 危険な操作の前に人間の承認を挟む設計パターン。「実行してよいですか？ [y/N]」のような確認です。

各 example の解説

examples/tools ディレクトリには 15 個の Python ファイルと、シェル用スキルを定義した skills/csv-workbench サブディレクトリがあります。hosted tools → ローカル実行ツール → 応用（tool search・Codex）の順に見ていきます。

共通の前提: 以降の実行手順は、第1章の手順（git clone https://github.com/openai/openai-agents-python.git → cd openai-agents-python → uv sync）が完了し、環境変数 OPENAI_API_KEY が設定済みであることを前提とします。

web_search.py

hosted tools の最小構成です。WebSearchTool を渡すだけで、エージェントが OpenAI サーバー側で Web 検索を実行し、最新のニュースを要約して返します。

24 行の短いファイルなので全文を引用します。

import asyncio

from agents import Agent, Runner, WebSearchTool, trace


async def main():
    agent = Agent(
        name="Web searcher",
        instructions="You are a helpful agent.",
        tools=[WebSearchTool(user_location={"type": "approximate", "city": "New York"})],
    )

    with trace("Web search example"):
        result = await Runner.run(
            agent,
            "search the web for 'local sports news' and give me 1 interesting update in a sentence.",
        )
        print(result.final_output)
        # The New York Giants are reportedly pursuing quarterback Aaron Rodgers after his ...


if __name__ == "__main__":
    asyncio.run(main())

コード解説

• tools=[WebSearchTool(...)] — hosted tool はインスタンスを tools リストに入れるだけで使えます。検索処理の実装は一切書いていません。これが hosted tools の最大の特徴です。
• user_location={"type": "approximate", "city": "New York"} — 検索結果を特定の地域向けに調整するオプションです。「ローカルのスポーツニュース」という曖昧な依頼が、ニューヨークのニュースとして解釈されます。
• WebSearchTool はこの他に filters（検索対象ドメインの制限）、search_context_size（検索に使うコンテキスト量。"low" / "medium" / "high"）というオプションを持ちます（ソースコード src/agents/tool.py の定義より）。
• with trace("Web search example"): — 実行記録に名前を付けています。OpenAI ダッシュボードの Traces で「Web search example」という名前のトレースとして確認できます。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/web_search.py

期待される動作・出力例

ニューヨークのスポーツニュースを 1 文で要約した文章が表示されます。ファイル内のコメントにある通り、The New York Giants are reportedly pursuing quarterback Aaron Rodgers after his ... のような、実行時点の最新ニュースに基づく文が出力されます（実行のたびに内容は変わります）。

つまずきポイント

• WebSearchTool は OpenAI の Responses API 専用です。他社モデルや Chat Completions API 経由では使えません。
• 検索は OpenAI 側で行われるため、社内プロキシの設定などは不要ですが、その分「どのサイトをどう検索したか」の細かい制御は限定的です（次の example で制御方法を学びます）。

web_search_filters.py

WebSearchTool の応用編です。検索対象ドメインを OpenAI の開発者向けサイトに限定（ドメインフィルタリング）し、さらに 回答に付いたインライン引用の URL と 検索時に実際に参照したソース URL の一覧 の 2 種類を取り出して表示します。

コード解説

中心となるのはエージェント定義です。

    agent = Agent(
        name="WebOAI website searcher",
        model="gpt-5.6",
        instructions=(
            "You are a helpful agent that searches OpenAI developer documentation. Answer only "
            "from the allowed official documentation sources and include inline citations. Cite "
            "the official page for each model when comparing multiple models."
        ),
        tools=[
            WebSearchTool(
                # https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#domain-filtering
                filters=Filters(allowed_domains=ALLOWED_DOMAINS),
                search_context_size="medium",
            )
        ],
        model_settings=ModelSettings(
            reasoning=Reasoning(effort="low"),
            tool_choice="required",
            verbosity="low",
            # https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#sources
            response_include=["web_search_call.action.sources"],
        ),
    )

• filters=Filters(allowed_domains=ALLOWED_DOMAINS) — 検索対象をファイル冒頭で定義した ALLOWED_DOMAINS = ["developers.openai.com"] の 1 ドメインに限定します。Filters は openai パッケージ（openai.types.responses.web_search_tool）からインポートしている点に注意してください。SDK は OpenAI 公式 Python ライブラリの型をそのまま利用します。
• model_settings=ModelSettings(...) — ModelSettings はモデルの動作を細かく調整する設定クラスです。response_include=["web_search_call.action.sources"] を指定すると、API の応答に「検索で参照したソース一覧」が含まれるようになります。これがこの example の鍵です。
• reasoning=Reasoning(effort="low") は推論（モデルが答えを出す前に内部で考える処理）の深さを浅めに、verbosity="low" は応答の冗長さを抑える設定です。tool_choice="required" は「必ずツール（ここでは Web 検索）を使ってから回答する」指定で、モデルが検索せずに記憶だけで答えてソース一覧が空になる事態を防ぎます。

実行後、URL の取り出しは共通モジュール examples/web_search_utils.py の 2 つのヘルパーに委譲されています。

        citations = extract_url_citations(result.new_items)
        cited_urls = _normalized_source_urls([citation.url for citation in citations])
        retrieved_urls = _normalized_source_urls(extract_web_search_source_urls(result.new_items))
        model_documentation_urls = [
            url for url in retrieved_urls if "/api/docs/models/gpt-5.6-" in url
        ]

        if not cited_urls:
            raise RuntimeError("Expected at least one official inline citation in the final answer")
        if not model_documentation_urls:
            raise RuntimeError(
                f"Expected GPT-5.6 model documentation in retrieved sources, got {retrieved_urls}"
            )

• result.new_items には、実行中に生成されたアイテム（ツール呼び出し、メッセージなど）が並びます。ここから 2 種類の URL を取り出します。

  • extract_url_citations() — 最終メッセージ（type == "message"）の output_text に付いた url_citation 注釈を集めます。つまり「モデルが回答本文で実際に引用として示した URL」です。
  • extract_web_search_source_urls() — Web 検索呼び出し（type == "web_search_call"）の action.sources を集めます。つまり「検索で参照した URL の全量」で、引用されなかったものも含みます。
• どちらのヘルパーも examples/web_search_utils.py にあります。この共通モジュールは、同じ抽出処理を第13章の金融リサーチ example とも共有するために新設されました。from examples.web_search_utils import ... という形の import があるため、この example はパッケージとして（python -m examples.tools.web_search_filters）起動する必要があります
• ファイル前半の _normalize_source_url() / _normalized_source_urls() は、取得した URL から画像や CSS などの不要な URL を除外し、ホスト名が許可ドメイン配下かを検証し、重複を取り除くヘルパー関数です（LLM とは無関係の純粋な Python 処理）。
• 末尾の 2 つの raise RuntimeError(...) は example 自身の自己検証です。引用が 1 件も取れなかった場合や、想定したモデルドキュメントが参照されなかった場合に黙って成功したことにせず落とすようになっています。CI で example を通しで流すための作りです

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python -m examples.tools.web_search_filters

   共通モジュール examples/web_search_utils.py を import しているため、python examples/tools/web_search_filters.py の形（単独スクリプト実行）では ModuleNotFoundError になります。-m 付きのモジュール実行を使ってください。

期待される動作・出力例

### Cited sources ### に回答本文で引用された URL、### Retrieved model documentation ### に検索で参照した GPT-5.6 のモデルドキュメント URL（/api/docs/models/gpt-5.6-...）が並び、その後 ### Final output ### として、GPT-5.6 Sol と GPT-5.6 Terra を比較する 3 点の箇条書きと「どちらをいつ使うか」の説明が表示されます。

つまずきポイント

• response_include を指定し忘れると、sources が返らず URL 一覧は空になります。「ソースを取りたければ明示的にリクエストする」のが Responses API の流儀です。
• ドメインフィルタリングの仕様は OpenAI プラットフォーム側の機能です。詳細はコード中のコメントにあるプラットフォームドキュメント（tools-web-search ガイド）を参照してください。
• モデルが許可ドメイン内で目的のページに到達できなかった場合、末尾の raise RuntimeError(...) で異常終了します。エラーメッセージには実際に参照された URL 一覧が入るので、まずそこを見てください。

file_search.py

FileSearchTool を使い、ベクトルストア に保存した自社文書などから情報を検索して回答する example です。いわゆる RAG（Retrieval-Augmented Generation。検索で得た情報を根拠に回答を生成する手法）を最短の手数で実現します。

コード解説

FileSearchTool を使うには 事前にベクトルストアを作り、その ID を渡す必要があります。この example は親切なことに、実行のたびに使い捨てのベクトルストアをその場で作成し、終了時に finally で後始末までしてくれます。

    vector_store_id: str | None = None

    async with AsyncOpenAI() as client:
        try:
            print("### Preparing vector store:\n")
            # Create a temporary vector store and index a file.
            text = (
                "Arrakis, the desert planet in Frank Herbert's 'Dune,' was inspired by the "
                "scarcity of water as a metaphor for oil and other finite resources."
            )
            file_upload = await client.files.create(
                file=("example.txt", text.encode("utf-8")),
                purpose="assistants",
            )
            file_id = file_upload.id
            print(f"File uploaded: {file_upload.to_dict()}")

            vector_store = await client.vector_stores.create(
                name="example-vector-store",
                expires_after={"anchor": "last_active_at", "days": 1},
            )
            vector_store_id = vector_store.id
            print(f"Vector store created: {vector_store.to_dict()}")

            indexed = await client.vector_stores.files.create_and_poll(
                vector_store_id=vector_store_id,
                file_id=file_id,
            )
            print(f"Stored files in vector store: {indexed.to_dict()}")

• ここは Agents SDK ではなく OpenAI 公式ライブラリ（openai パッケージ）を直接使う準備コード です。手順は「①テキストをファイルとしてアップロード → ②ベクトルストアを作成 → ③ファイルをストアに登録して索引化を待つ（create_and_poll）」の 3 段階です。
• async with AsyncOpenAI() as client: と非同期クライアントを使い、await で各 API を呼びます。以前は同期版の OpenAI() を使い、vector_store_id が未指定のときだけ準備コードを走らせる分岐がありましたが、現在は毎回使い捨てのストアを作る形に整理されました。
• expires_after={"anchor": "last_active_at", "days": 1} を付けてベクトルストアに有効期限を持たせ、さらに finally 節で vector_stores.delete() と files.delete() を必ず実行します。試し終わった後の後始末が example 側で完結するようになっています。

エージェント本体は次の通りです。

            # Create an agent that can search the vector store.
            agent = Agent(
                name="File searcher",
                instructions=(
                    "You are a helpful agent. "
                    "You answer only based on the information in the vector store."
                ),
                tools=[
                    FileSearchTool(
                        max_num_results=3,
                        vector_store_ids=[vector_store_id],
                        include_search_results=True,
                    )
                ],
            )

• vector_store_ids=[...] — 検索対象のベクトルストア ID をリストで渡します。これが FileSearchTool の必須パラメータです。
• max_num_results=3 — 検索結果を最大 3 件に制限します。
• include_search_results=True — 検索でヒットした本文を出力アイテムに含めます。実行後の result.new_items で検索クエリとヒット内容を確認できます。
• この他に ranking_options（ランキング調整）と filters（ファイル属性によるフィルタ）も指定できます（ソースコードの定義より）。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/file_search.py

3. 実行が終わると、作成されたベクトルストアとファイルは finally 節で自動的に削除されます（Deleted vector store: ... / Deleted file: ... のログが出ます）。

期待される動作・出力例

まずベクトルストア作成のログ（File uploaded: ... など）が流れ、その後、登録した一文に基づく回答が表示されます。

Arrakis, the desert planet in Frank Herbert's "Dune," was inspired by the scarcity of water
as a metaphor for oil and other finite resources.

### Output items: には {"id":"...", "queries":["Arrakis"], "results":[...]} のような検索の生データが表示されます。

つまずきポイント

• この example を実行するたびに、あなたの OpenAI アカウントにファイルとベクトルストアが作成されます。ベクトルストアは保存容量に応じた課金対象になり得ますが、現在の example は finally 節で削除まで行い、加えて expires_after で 1 日後の自動失効も設定しています。途中で強制終了させた場合は後始末が走らないことがあるので、その時は OpenAI ダッシュボード（Storage ページ）で残骸がないか確認してください。
• ファイルの索引化には数秒かかります。create_and_poll が完了を待ってくれますが、大きなファイルではその分時間がかかります。

FileSearchTool を使った一連の処理をまとめると、次の一本道になります。

code_interpreter.py

CodeInterpreterTool を使い、OpenAI サーバー上のサンドボックスで Python コードを実行して数値計算を解かせる example です。ストリーミング実行と組み合わせ、モデルが書いたコードをリアルタイムに表示します。

コード解説

    agent = Agent(
        name="Code interpreter",
        # Note: using gpt-5-class models with streaming for this tool may require org verification.
        # Code interpreter does not support gpt-5 minimal reasoning effort; use default effort.
        model="gpt-5.6-sol",
        instructions=(
            "Always use the code interpreter tool to solve numeric problems, and show the code "
            "you ran when possible."
        ),
        tools=[
            CodeInterpreterTool(
                tool_config={"type": "code_interpreter", "container": {"type": "auto"}},
            )
        ],
    )

• CodeInterpreterTool は tool_config という辞書で設定します。"container": {"type": "auto"} は「実行用のコンテナを自動で用意する」という意味です。
• コメントにある通り、gpt-5 系モデルとストリーミングの組み合わせでは、組織の本人確認（org verification）が必要な場合があります。

実行部分はストリーミングです。

        result = Runner.run_streamed(
            agent,
            (
                "Use the code interpreter tool to calculate the square root of 273 * 312821 + "
                "1782. Show the Python code you ran and then provide the numeric answer."
            ),
        )
        saw_code_interpreter_call = False
        async for event in result.stream_events():
            if event.type != "run_item_stream_event":
                continue

            item = event.item
            if item.type == "tool_call_item":
                raw_call = item.raw_item
                if _get_field(raw_call, "type") == "code_interpreter_call":
                    saw_code_interpreter_call = True
                    code = _get_field(raw_call, "code")
                    if isinstance(code, str):
                        print(f"Code interpreter code:\n```\n{code}\n```\n")
                        continue

• Runner.run_streamed() は実行しながらイベントを逐次受け取れる実行方法です（第2章のストリーミングの復習です）。
• イベントの中から type == "code_interpreter_call" のツール呼び出しを探し、その code フィールド（モデルが書いた Python コード）を表示しています。「AI がどんなコードを書いて計算したか」を目視できるのがこの example の見どころです。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/code_interpreter.py

期待される動作・出力例

Solving math problem with the coding interpreter... の後、モデルが実行した Python コード（import math して平方根を計算するようなコード）が表示され、最後に Final output: として数値の答えを含む説明文が表示されます。

つまずきポイント

• 計算は OpenAI サーバーのサンドボックスで実行されるため、あなたのローカルファイルにはアクセスできません。ローカルで実行したい場合は後述の ShellTool（ローカルモード）を使います。
• コンテナの起動・実行時間に応じた課金が発生します。

image_generator.py

ImageGenerationTool で画像を生成し、返ってきた base64 データ（画像バイナリを文字列で表現したもの）を PNG ファイルに保存して開く example です。

コード解説

    image_config: ImageGenerationToolConfig = {
        "type": "image_generation",
        "model": "gpt-image-2.5-flare",
        "action": "generate",
        "size": "1536x864",
        "quality": "low",
    }
    agent = Agent(
        name="Image generator",
        instructions="Always use the image generation tool when the user asks for a new image.",
        tools=[ImageGenerationTool(tool_config=image_config)],
    )

• tool_config で品質を "low" に設定しています。試すだけなら低品質で十分で、生成も速く料金も抑えられます。

生成結果の取り出しと保存は次の通りです。

        for item in result.new_items:
            if item.type != "tool_call_item":
                continue

            raw_call = item.raw_item
            call_type = _get_field(raw_call, "type")
            if call_type != "image_generation_call":
                continue

            img_result = _get_field(raw_call, "result")
            if not isinstance(img_result, str):
                continue

            generated_image = True
            with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
                tmp.write(base64.b64decode(img_result))
                temp_path = tmp.name

• 画像は image_generation_call タイプのツール呼び出しアイテムの result フィールドに base64 文字列として入っています。base64.b64decode() でバイナリに戻して一時ファイルに書き出します。
• その後の open_file() は OS ごとに適切なコマンド（macOS なら open、Windows なら os.startfile、Linux なら xdg-open）で画像ビューアを開くヘルパーです。
• from examples.auto_mode import is_auto_mode — examples 共通のユーティリティで、環境変数 EXAMPLES_INTERACTIVE_MODE=auto が設定されていると対話やファイルオープンを省略します（CI などの自動実行用）。この import があるため、このファイルはモジュール形式で実行する必要があります。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. examples.auto_mode を import しているため、リポジトリルートから モジュール形式 で実行します。

   uv run python -m examples.tools.image_generator

期待される動作・出力例

Generating image, this may take a while... と表示され、しばらく待つと Saved generated image to: /tmp/....png と出力されて、「ピザを食べるカエル（コミック風）」の画像が既定のビューアで開きます。

つまずきポイント

• 画像生成は数十秒かかることがあります。フリーズではないので待ちましょう。
• OpenAI の画像生成モデルの利用には、アカウント側で組織の本人確認が求められる場合があります。API エラーになる場合はダッシュボードの組織設定を確認してください。

computer_use.py

ComputerTool を使った computer use（モデルが画面のスクリーンショットを見てマウス・キーボード操作を決め、ブラウザを自動操作する仕組み）の example です。hosted tools と異なり、ブラウザの操作はあなたのマシン上で Playwright（ブラウザ自動操作ライブラリ）が実行します。モデルは「座標 (x, y) をクリックせよ」といった操作指示を返すだけです。

コード解説

ファイル冒頭に実行方法が明記されています。

# How to run this example:
# uv run python -m playwright install chromium
# uv run -m examples.tools.computer_use

この example の主役は、AsyncComputer インターフェースを Playwright で実装した LocalPlaywrightComputer クラスです。

class LocalPlaywrightComputer(AsyncComputer):
    """A computer, implemented using a local Playwright browser."""

AsyncComputer は「コンピュータとはこういう操作ができるものだ」という約束事（インターフェース）で、以下のようなメソッドの実装が求められます。

    @property
    def dimensions(self) -> tuple[int, int]:
        return (1024, 768)

    async def screenshot(self) -> str:
        """Capture only the viewport (not full_page)."""
        png_bytes = await self.page.screenshot(full_page=False)
        return base64.b64encode(png_bytes).decode("utf-8")

    async def click(
        self, x: int, y: int, button: Button = "left", *, keys: list[str] | None = None
    ) -> None:
        playwright_button: Literal["left", "middle", "right"] = "left"

        # Playwright only supports left, middle, right buttons
        if button in ("left", "right", "middle"):
            playwright_button = button  # type: ignore

        async with self._hold_keys(keys):
            await self.page.mouse.click(x, y, button=playwright_button)

• screenshot() が返す画像をモデルが「見て」、次の操作（クリック位置など）を決めます。SDK が「モデルの指示 → あなたの実装の呼び出し → スクリーンショットをモデルに返す」というループを自動で回します。
• click / double_click / scroll / type / keypress / drag / move / wait がそれぞれ Playwright の対応 API に変換されています。CUA_KEY_TO_PLAYWRIGHT_KEY 辞書は、モデルが使うキー名（"ctrl" など）を Playwright のキー名（"Control"）に変換する対応表です。
• 操作対象はファイル内に埋め込まれた「東京の天気デモページ」（DEMO_PAGE_HTML）です。外部サイトに依存せず安全に試せるようになっています。環境変数 COMPUTER_USE_START_URL を設定すると任意の URL を開けます。

エージェント定義とツール登録は次の通りです。

        agent = Agent(
            name="Browser user",
            instructions=AGENT_INSTRUCTIONS,
            tools=[ComputerTool(computer=computer_config)],
            # GPT-5.4 uses the built-in Responses API computer tool.
            model="gpt-5.5",
            model_settings=ModelSettings(tool_choice="required"),
        )

• ComputerTool(computer=...) に自作の Computer 実装を渡します。tool_choice="required" は「必ずツールを使え」という強制設定です。

さらにこの example は、Computer インスタンスの管理方法を 2 パターン示しています。

async def singleton_computer() -> None:
    # Use a shared computer when you do not expect to run multiple agents concurrently.
    async with LocalPlaywrightComputer() as computer:
        await run_agent(computer)

async def computer_per_request() -> None:
    # Initialize a new computer per request to avoid sharing state between runs.
    async def create_computer(*, run_context: RunContextWrapper[Any]) -> LocalPlaywrightComputer:
        print(f"Creating computer for run context: {run_context}")
        return await LocalPlaywrightComputer().open()

    async def dispose_computer(
        *,
        run_context: RunContextWrapper[Any],
        computer: LocalPlaywrightComputer,
    ) -> None:
        print(f"Disposing computer for run context: {run_context}")
        await computer.close()

    await run_agent(
        ComputerProvider[LocalPlaywrightComputer](
            create=create_computer,
            dispose=dispose_computer,
        )
    )

• singleton モード: 1 つのブラウザを使い回す方式。並行実行しないならこれで十分です。
• ComputerProvider モード（既定）: 実行（run）のたびにブラウザを新規作成・破棄するファクトリ方式。複数の実行の間で状態を共有したくない場合に使います。コマンドライン引数 singleton を付けない限りこちらが動きます。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 事前準備（必須）: Playwright 用の Chromium ブラウザをダウンロードします（Playwright ライブラリ自体は uv sync で導入済みです）。

   uv run python -m playwright install chromium

3. example を実行します（モジュール形式）。

   uv run python -m examples.tools.computer_use

   1 つのブラウザを使い回す singleton モードで試す場合は引数を付けます。

   uv run python -m examples.tools.computer_use singleton

4. （任意）ブラウザの動きを画面で見たい場合は、ヘッドレスモード（画面を表示しない実行モード）を無効化します。

   COMPUTER_USE_HEADLESS=0 uv run python -m examples.tools.computer_use

期待される動作・出力例

Creating computer for run context: ... に続き、モデルがスクリーンショットを解析して「Refresh forecast」ボタンをクリックし、ページに表示された東京の天気（22C、風速 37 km/h など）を要約した文章が最後に表示されます。

つまずきポイント

• playwright install chromium を忘れると起動時にエラーになります。ライブラリのインストール（uv sync）とブラウザ本体のダウンロードは別作業です。
• computer use は「スクリーンショット → 操作 → スクリーンショット」のループを繰り返すため、実行に時間がかかり、トークン消費も多めです。
• モデルが座標を誤るなど、操作が常に成功するとは限りません。実運用では後述の安全チェックや承認フローとの組み合わせが重要です。

computer use のループを図示すると次のようになります。

shell.py

ShellTool の ローカルモード の example です。モデルが「実行したいシェルコマンド」を提案し、あなたが書いた executor がローカルで実行 します。実行前にターミナルで承認を求める安全設計になっています。

コード解説

executor は「コマンド実行の依頼（ShellCommandRequest）を受け取り、結果（ShellResult）を返す」呼び出し可能オブジェクトとして実装します。

class ShellExecutor:
    """Executes shell commands; approval is handled via ShellTool."""

    def __init__(self, cwd: Path | None = None):
        self.cwd = Path(cwd or Path.cwd())

    async def __call__(self, request: ShellCommandRequest) -> ShellResult:
        action = request.data.action

        outputs: list[ShellCommandOutput] = []
        for command in action.commands:
            proc = await asyncio.create_subprocess_shell(
                command,
                cwd=self.cwd,
                env=os.environ.copy(),
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE,
            )

• request.data.action.commands にモデルが提案したコマンドのリストが入っています。それを asyncio.create_subprocess_shell で 1 つずつ実行し、標準出力・標準エラー・終了コードを ShellCommandOutput に詰めて返します。
• タイムアウト処理（action.timeout_ms）も実装されており、時間切れの場合は outcome が "timeout" になります。

承認フローは ShellTool のパラメータで宣言します。

        agent = Agent(
            name="Shell Assistant",
            model=model,
            instructions=(
                "You can run shell commands using the shell tool. "
                "Keep responses concise and include command output when helpful."
            ),
            tools=[
                ShellTool(
                    executor=ShellExecutor(),
                    needs_approval=True,
                    on_approval=on_shell_approval,
                )
            ],
            model_settings=ModelSettings(tool_choice="required"),
        )

• needs_approval=True — このツールの実行には承認が必要、という宣言です。
• on_approval=on_shell_approval — 承認が必要になった瞬間に呼ばれるコールバック関数です。この example では、実行予定のコマンドを表示して input() で y/N を尋ね、{"approve": True/False, "reason": ...} を返します。コールバック方式 なので、Runner.run() の呼び出しは 1 回のままで、承認処理が実行の内側で完結します（次の example と比較してください）。
• 環境変数 SHELL_AUTO_APPROVE=1 を設定すると、確認プロンプトをスキップして常に承認します。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/shell.py

   プロンプトやモデルを変えたい場合は引数を渡せます。

   uv run python examples/tools/shell.py --prompt "Show the current date." --model gpt-5.6-sol

3. Shell command approval required: と表示されたら、実行されるコマンドを確認して y を入力します。
4. （任意）確認なしで自動承認する場合は SHELL_AUTO_APPROVE=1 を設定して実行します。

期待される動作・出力例

既定のプロンプトは「カレントディレクトリのファイル一覧を表示して」です。ls 系のコマンドが提案され、承認するとコマンドが実行され、Final response: としてファイル一覧の要約が表示されます。

つまずきポイント

• モデルが提案するコマンドは毎回変わり得ます。承認前に必ず内容を確認する習慣をつけてください。この example が承認フローをデフォルトにしているのは、シェル実行が本質的に危険な操作だからです。
• n で拒否するとツール呼び出しは実行されず、その旨がモデルに伝わります。

shell_human_in_the_loop.py

shell.py と同じ ShellTool ローカル実行ですが、承認の方式が異なります。on_approval コールバックの代わりに、interruption（中断）方式 の human-in-the-loop を実装しています。実行が承認待ちでいったん停止し、承認・拒否を登録してから実行を再開する、より本格的なパターンです。

コード解説

ShellExecutor は shell.py とほぼ同一です。違いはツール定義と実行ループにあります。

            tools=[
                ShellTool(
                    executor=ShellExecutor(),
                    needs_approval=True,
                )
            ],

• needs_approval=True のみで on_approval を渡していません。この場合、承認が必要になると 実行がそこで中断され、結果オブジェクトの interruptions に承認待ちアイテムが入ります。

        result = await Runner.run(agent, prompt)

        while result.interruptions:
            print("\n== Pending approvals ==")
            state = result.to_state()
            for interruption in result.interruptions:
                commands = _extract_commands(interruption)
                approved, always = await prompt_shell_approval(commands)
                if approved:
                    state.approve(interruption, always_approve=always)
                else:
                    state.reject(interruption, always_reject=always)

            result = await Runner.run(agent, state)

• result.interruptions が空でない間、承認待ちのループを回します。
• result.to_state() で実行状態（RunState）を取り出し、state.approve(...) / state.reject(...) で個々の承認待ちに対する判断を登録します。always_approve=True を渡すと「以降の同種の呼び出しはすべて承認」になります。
• Runner.run(agent, state) に 状態オブジェクトを渡して再実行 すると、中断地点から続きが実行されます。この「中断 → 状態保存 → 再開」の形は、Web アプリで「ユーザーの承認ボタンを待つ」ような非対話環境でも使える汎用パターンです。
• 承認プロンプトには examples.auto_mode の confirm_with_fallback() を使っており、環境変数 EXAMPLES_INTERACTIVE_MODE=auto のときは自動で既定の回答を返します。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. examples.auto_mode を import しているため、モジュール形式で実行します。

   uv run python -m examples.tools.shell_human_in_the_loop

3. == Pending approvals == と実行予定コマンドが表示されたら y / n を入力します。続けて「今後のシェル呼び出しをすべて承認するか」も聞かれます。

期待される動作・出力例

既定プロンプトは「ファイル一覧とカレントディレクトリを表示して」です。承認するとコマンドが実行され、Final response: に結果の要約が表示されます。拒否した場合は、モデルが「実行が拒否された」ことを踏まえた応答を返します。

つまずきポイント

• on_approval コールバック方式（shell.py）と interruption 方式（本ファイル）の使い分け: その場で同期的に判断できるなら前者、承認を別の画面・別のタイミングに委ねたいなら後者が向いています。
• while result.interruptions: のループを忘れると、承認待ちのまま最終出力が得られません。

2 つの承認方式の違いを図で比較すると次のようになります。

apply_patch.py

ApplyPatchTool を使って、モデルに ファイルの作成・更新・削除を diff（差分）形式で行わせる example です。エディタ実装（ApplyPatchEditor 相当）を自作し、ワークスペース外への書き込み防止と操作ごとの承認を組み込んでいます。

コード解説

エディタは create_file / update_file / delete_file の 3 メソッドを実装します。

    def create_file(self, operation: ApplyPatchOperation) -> ApplyPatchResult:
        relative = self._relative_path(operation.path)
        self._require_approval(operation, relative)
        target = self._resolve(operation.path, ensure_parent=True)
        diff = operation.diff or ""
        content = apply_diff("", diff, mode="create")
        target.write_text(content, encoding="utf-8")
        return ApplyPatchResult(output=f"Created {relative}")

• operation.diff にはモデルが生成した差分テキストが入っています。SDK 提供のヘルパー apply_diff(元テキスト, diff) を使うと、差分を適用した後のテキストが得られます。新規作成時は mode="create" で空文字列に対して適用します。
• _resolve() は、パスがワークスペース（一時ディレクトリ）の外を指していないか検証するガードです。target.relative_to(self._root) が失敗したら例外を投げます。モデルにファイル操作をさせる場合、この種の境界チェックは必須の防御策です。
• _require_approval() は操作内容（種類・パス・diff）の SHA-256 ハッシュを「指紋」として記録し、同じ操作の再承認を省きつつ、新しい操作にはターミナルで承認を求めます。

エージェント側の設定で興味深いのは previous_response_id の利用です。

            result = await Runner.run(
                agent,
                "Create tasks.md with a shopping checklist of 5 entries.",
                previous_response_id=previous_response_id,
            )
            previous_response_id = result.last_response_id

• previous_response_id は Responses API の会話継続機能で、前回の応答 ID を渡すことで会話履歴を再送信せずに文脈を引き継げます。1 回目（tasks.md の作成）の文脈を保ったまま、2 回目（最後の 2 項目にチェックを付ける更新）を依頼しています。
• 2 回目のプロンプトでは、現在のファイル内容を <BEGIN_FILES> ... <END_FILES> で囲んで渡しています。モデルが正確な diff を作るには元ファイルの内容が必要だからです。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. examples.auto_mode を import しているため、モジュール形式で実行します。

   uv run python -m examples.tools.apply_patch

3. [apply_patch] approval required と diff プレビューが表示されたら、内容を確認して y を入力します（作成と更新で計 2 回程度）。

4. （任意）承認を省略する場合は --auto-approve フラグ、または環境変数 APPLY_PATCH_AUTO_APPROVE=1 を使います。

   uv run python -m examples.tools.apply_patch --auto-approve

期待される動作・出力例

一時ディレクトリに tasks.md が作成され、買い物チェックリスト 5 項目が書き込まれます。続いて 2 回目の実行で最後の 2 項目が [x] にチェックされ、最終的なファイル内容がターミナルに表示されます。ワークスペースは一時ディレクトリなので、終了後に自動で消えます。

つまずきポイント

• 操作対象は tempfile.TemporaryDirectory で作られる一時ディレクトリです。自分のプロジェクトのファイルが書き換わることはありません。
• モデルの diff が元ファイルと食い違うと適用に失敗することがあります。「更新前に必ず最新のファイル内容をプロンプトで渡す」のが安定運用のコツです。

skills/csv-workbench（シェル用スキルの定義）

次の 3 つの example が共通で使う「スキル」の定義ディレクトリです。スキルとは、エージェントに特定の作業手順を教えるための文書の束（SKILL.md と補助ファイル）で、シェル環境にマウント（配置）して使います。

SKILL.md は YAML フロントマター（ファイル冒頭のメタデータ）と手順書からなります。

---
name: csv-workbench
description: Analyze CSV files in /mnt/data and return concise numeric summaries.
---

# CSV Workbench

Use this skill when the user asks for quick analysis of tabular data.

## Workflow

1. Inspect the CSV schema first (`head`, `python csv.DictReader`, or both).
2. Compute requested aggregates with a short Python script.
3. Return concise results with concrete numbers and units when available.

## Constraints

- Prefer Python stdlib for portability.
- If data is missing or malformed, state assumptions clearly.
- Keep the final answer short and actionable.

同梱の playbook.md には、行数カウントやグループ集計のためのシェル・Python スニペット集が書かれています。エージェントはスキルを読み込むことで「CSV 分析はこの手順とスニペットでやる」という知識を獲得します。

local_shell_skill.py

上記の csv-workbench スキルを、ローカルの ShellTool に組み込む example です。スキルのファイルをローカルパスで指定し、モデルがスキルの手順書に従ってローカルでシェルコマンドを実行します。

コード解説

def build_local_skill() -> ShellToolLocalSkill:
    return {
        "name": SKILL_NAME,
        "description": "Analyze CSV files and return concise numeric summaries.",
        "path": str(SKILL_DIR),
    }

• ローカルスキルは name / description / path（スキルディレクトリのパス）の 3 項目を持つ辞書（ShellToolLocalSkill 型）です。

            tools=[
                ShellTool(
                    environment={
                        "type": "local",
                        "skills": [local_skill],
                    },
                    executor=ShellExecutor(),
                )
            ],

• environment={"type": "local", "skills": [...]} — ShellTool の実行環境を「ローカル + スキル付き」と宣言します。ローカルモードでは executor の指定が必須です（ソースコードの検証ロジックで、未指定だと UserError になります）。
• from examples.tools.shell import ShellExecutor — executor は shell.py のものを再利用しています。この import があるため モジュール形式での実行が必要 です。
• example 後半では、スキルなしの 2 つ目のエージェントが /tmp/test_orders.csv を ls で確認し、1 つ目のエージェントが作ったファイルがローカルに実在することを確かめています。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. モジュール形式で実行します。

   uv run python -m examples.tools.local_shell_skill

期待される動作・出力例

エージェントが csv-workbench スキルの手順に従って /tmp/test_orders.csv を作成し、地域別の合計金額と失敗注文数を集計した要約を出力します。続けて 2 つ目のエージェントが ls -la /tmp/test_orders.csv の結果を 1 文で要約します。

つまずきポイント

• このモードではコマンドが 実際にあなたのマシンで実行され、/tmp にファイルが作られます。この example には承認フローがないので、内容を理解した上で実行してください。

container_shell_inline_skill.py

同じ csv-workbench スキルを、今度は OpenAI がホストするコンテナ内の ShellTool で使う example です。スキルディレクトリを ZIP に固めて base64 で埋め込み（インラインスキル）、リクエストと一緒にサーバーへ送ります。さらに、1 つ目の実行で作られたコンテナを 2 つ目のエージェントが 再利用 する方法も示します。

コード解説

def build_inline_skill() -> ShellToolInlineSkill:
    bundle = build_skill_zip_bundle()
    return {
        "type": "inline",
        "name": SKILL_NAME,
        "description": "Analyze CSV files in /mnt/data and return concise numeric summaries.",
        "source": {
            "type": "base64",
            "media_type": "application/zip",
            "data": base64.b64encode(bundle).decode("ascii"),
        },
    }

• build_skill_zip_bundle() がスキルディレクトリを ZIP 圧縮し、その中身を base64 文字列にして source に埋め込みます。スキルの実体ごとサーバーに送る方式です。

            tools=[
                ShellTool(
                    environment={
                        "type": "container_auto",
                        "network_policy": {"type": "disabled"},
                        "skills": [inline_skill],
                    }
                )
            ],

• "type": "container_auto" — OpenAI 側でコンテナを自動作成するモードです。hosted モードなので executor は書きません（公式ドキュメントも、hosted 環境では executor / needs_approval / on_approval を設定しないよう明記しています）。
• "network_policy": {"type": "disabled"} — コンテナからの外部ネットワークアクセスを遮断します。allowlist モードで特定ドメインだけ許可することもできます。

コンテナ再利用のための ID 抽出が次の関数です。

def extract_container_id(raw_responses: list[ModelResponse]) -> str | None:
    for response in raw_responses:
        for item in response.output:
            if isinstance(item, ResponseFunctionShellToolCall) and isinstance(
                item.environment, ResponseContainerReference
            ):
                return item.environment.container_id

    return None

• API の生応答（result.raw_responses）からシェルツール呼び出しを探し、実行に使われたコンテナの ID（cntr_...）を取り出します。
• 2 つ目のエージェントは environment={"type": "container_reference", "container_id": container_id} を指定して同じコンテナに接続し、ls -la /mnt/data で 1 つ目のエージェントが作ったファイルが残っていることを確認します。コンテナ内の状態（ファイル）が実行をまたいで保持されることの実演です。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/container_shell_inline_skill.py

期待される動作・出力例

1 つ目のエージェントがコンテナ内の /mnt/data/orders.csv を作成して地域別集計を報告し、[info] Reusing container_id=cntr_... の後、2 つ目のエージェントが同じコンテナの /mnt/data の一覧を 1 文で要約します。

つまずきポイント

• コマンドは OpenAI のコンテナ内で実行されるため、あなたのマシンにファイルは作られません（ローカル版との対比を意識してください）。
• コンテナの生成・稼働には課金が発生し得ます。また、コンテナには有効期限があるため、時間を置いて container_reference で再接続するとエラーになることがあります。

同じスキルが 2 つの経路に分かれる様子を図にすると次のようになります。

container_shell_skill_reference.py

インラインスキルと対になる方式で、事前に OpenAI プラットフォームへ登録済みのスキルを ID で参照 して hosted コンテナにマウントする example です。

コード解説

DEFAULT_SKILL_REFERENCE: ShellToolSkillReference = {
    "type": "skill_reference",
    "skill_id": "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377",
    "version": "1",
}

def resolve_skill_reference() -> ShellToolSkillReference:
    skill_id = os.environ.get(SHELL_SKILL_ID_ENV)
    if not skill_id:
        return DEFAULT_SKILL_REFERENCE

    reference: ShellToolSkillReference = {"type": "skill_reference", "skill_id": skill_id}
    skill_version = os.environ.get(SHELL_SKILL_VERSION_ENV)
    if skill_version:
        reference["version"] = skill_version
    return reference

• スキル参照は {"type": "skill_reference", "skill_id": "skill_...", "version": "..."} という形式の辞書です。ZIP を毎回送るインライン方式と違い、登録済みスキルを ID で指すだけなので軽量で、チームでの共有・バージョン管理に向きます。
• 環境変数 OPENAI_SHELL_SKILL_ID（と任意の OPENAI_SHELL_SKILL_VERSION）で自分のスキル ID に差し替えられます。ファイル内のデフォルト ID はサンプル値であり、あなたのアカウントからは参照できない可能性が高い 点に注意してください。
• エージェント定義・コンテナ再利用のコードは container_shell_inline_skill.py と同一構造です。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。
2. 事前準備: OpenAI プラットフォームに自分のスキルをアップロードし、スキル ID（skill_...）を取得します（プラットフォームの Skills ガイド参照）。

3. 取得した ID を環境変数で渡して実行します。

   OPENAI_SHELL_SKILL_ID=skill_xxxxxxxx uv run python examples/tools/container_shell_skill_reference.py

期待される動作・出力例

[info] Using skill reference: skill_... (version 1) と表示された後の流れはインライン版と同じで、コンテナ内での CSV 作成・集計と、コンテナ再利用による ls の要約が出力されます。

つまずきポイント

• デフォルトのスキル ID のまま実行すると、スキルが見つからない旨の API エラーになることがあります。必ず自分で登録したスキル ID を環境変数で指定してください。

tool_search.py

ToolSearchTool による tool search（ツールの遅延読み込み） の example です。エージェントに大量のツールを持たせると、全ツールの定義（スキーマ）が毎回プロンプトに含まれてトークンを浪費します。tool search を使うと、ツールを「隠して」おき、モデルが必要になった時に検索して読み込む ことができます。

コード解説

ツール側は defer_loading=True を付けた function tool として定義します。

@tool(defer_loading=True)
def get_customer_profile(
    customer_id: Annotated[str, "The CRM customer identifier to look up."],
) -> str:
    """Fetch a CRM customer profile."""
    return json.dumps(CUSTOMER_PROFILES[customer_id], indent=2)

• defer_loading=True — このツールは最初はモデルに見えず、ToolSearchTool 経由で読み込まれるまで使えません。

関連ツールは 名前空間（namespace） でグループ化できます。

crm_tools = tool_namespace(
    name="crm",
    description="CRM tools for customer lookups.",
    tools=[get_customer_profile, list_open_orders],
)

billing_tools = tool_namespace(
    name="billing",
    description="Billing tools for invoice lookups.",
    tools=[get_invoice_status],
)

namespaced_agent = Agent(
    name="Operations assistant",
    model="gpt-5.6-sol",
    instructions=(
        "For customer questions in this example, load the full `crm` namespace with no query "
        "filter before calling tools. "
        "Do not search `billing` unless the user asks about invoices."
    ),
    model_settings=ModelSettings(parallel_tool_calls=False),
    tools=[*crm_tools, *billing_tools, ToolSearchTool()],
)

• tool_namespace(name=..., description=..., tools=[...]) — 「crm」「billing」のような業務単位でツールをまとめます。モデルは名前空間の説明だけを最初に見て、必要なグループをまとめて読み込みます。公式ドキュメントは「可能な限り名前空間を使う」ことと「1 名前空間は 10 個未満に保つ」ことを推奨しています。
• tools=[*crm_tools, *billing_tools, ToolSearchTool()] — 名前空間を展開して並べ、ToolSearchTool() を 1 つだけ 追加します。これが検索の入り口になります。
• もう 1 つの top_level_agent は、名前空間を使わずトップレベルの deferred ツール（get_shipping_eta など）を個別に検索するパターンを示します。

実行結果の分析部分では、result.new_items の中の tool_search_output_item を調べて「どのツール/名前空間が実際に読み込まれたか」を集計し、registered（登録済み）/ loaded（読み込まれた）/ untouched(読み込まれなかった) を表示します。「billing は聞かれていないので読み込まれない」ことを確認するのが狙いです。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。tool search は OpenAI Responses モデル専用で、openai パッケージ 2.25.0 以上が必要です（uv sync 済みなら条件を満たしています）。

2. 次のコマンドを実行します。

   uv run python examples/tools/tool_search.py

   名前空間の例だけ・トップレベルの例だけを実行することもできます。

   uv run python examples/tools/tool_search.py namespace
   uv run python examples/tools/tool_search.py top-level

期待される動作・出力例

## Tool search with namespaces のセクションで、顧客 customer_42（Avery Chen）のプロフィールと注文一覧が表示され、Loaded paths に loaded: crm / untouched: billing のような集計が出ます。続く top-level の例では、追跡番号 ZX-123 の到着予定（2026-03-06 14:00 JST）が回答され、get_shipping_credit_balance が untouched のままであることが確認できます。

つまずきポイント

• defer_loading=True のツールを使う場合、ToolSearchTool() を必ず一緒に登録してください。検索手段がないとそのツールは永遠に使えません。
• tool_choice で名前空間名や deferred のみのツール名を直接指定することはできません（auto / required / 実在するトップレベルのツール名を使います）。

tool search の仕組みを図にすると次のようになります。

programmatic_tool_calling.py

v0.19.0 で追加された example です。 モデルが JavaScript のプログラムを生成し、そのプログラムからツールを呼ぶという新しい呼び出し方式（Programmatic Tool Calling）を扱います。3 SKU × 3 ツール＝ 9 回のツール呼び出しを並列実行し、その場で在庫の発注量を計算させる在庫補充プランナーです。

従来の方式では「モデルがツールを 1 つ呼ぶ → 結果がモデルに戻る → モデルが次のツールを呼ぶ」とツール 1 回ごとにモデルとの往復（ラウンドトリップ）が発生しました。Programmatic Tool Calling では、モデルが一度だけプログラムを書き、そのプログラムがループ・分岐・並列呼び出し・途中計算をこなして、最終結果 1 個だけをモデルに返します。「呼ぶ順番と組み合わせ方が決まっている定型作業」で効きます。

生成されたプログラムは、OpenAI 側のまっさらな V8 環境で実行されます。Node.js の API もファイルシステムもネットワークもなく、プロセスも永続しません。プログラムが触れるのは、あなたが明示的に許可したツールだけです。

コード解説

ツール側は allowed_callers で「プログラムからのみ呼べる」ことを宣言します。

@tool(allowed_callers=["programmatic"])
def get_inventory(sku: Sku) -> InventoryOutput:
    """Return the currently available units for one SKU."""
    print(f"[tool] get_inventory({sku})")
    return InventoryOutput(sku=sku, available_units=inventory[sku])

• allowed_callers は「そのツールを誰が呼べるか」の指定です。省略するとモデルの直接呼び出しのみ、["programmatic"] でプログラム専用、["direct", "programmatic"] で両方を許可します
• 戻り値の型注釈に Pydantic モデル（ここでは InventoryOutput）を使うと、strict なオブジェクト出力スキーマが自動生成され、返り値はプログラムに渡される前にそのスキーマで検証されます。注釈が使えない場合は output_type=...、既に strict なスキーマを持っている場合は output_json_schema={...} を使います（両者は排他）。str / Any / None の注釈ではスキーマは作られません
• 使えるツール型は FunctionTool / CustomTool / ShellTool / ApplyPatchTool / HostedMCPTool / CodeInterpreterTool です。前 4 つは allowed_callers を直接指定でき、hosted MCP と code interpreter は tool_config の中に書きます

エージェント側は ProgrammaticToolCallingTool() を 1 つ足し、tool_choice で方式を指定します。

    agent = Agent(
        name="Replenishment planner",
        model="gpt-5.6",
        instructions="""
<tool_orchestration>
Use Programmatic Tool Calling to prepare a replenishment plan for desk-lamp,
ergonomic-keyboard, and usb-c-dock. For every SKU, call get_inventory,
get_weekly_demand, and get_inbound_units. Create all nine tool-call promises
before awaiting them, then run them concurrently with one Promise.all call.
...
</tool_orchestration>
        """.strip(),
        model_settings=ModelSettings(tool_choice="programmatic_tool_calling"),
        tools=[
            get_inventory,
            get_weekly_demand,
            get_inbound_units,
            ProgrammaticToolCallingTool(),
        ],
    )

• ProgrammaticToolCallingTool() は 1 エージェントにつき最大 1 つです。加えて、プログラムから呼べるツールが最低 1 つ必要です（あるいは名前空間・遅延ツール・遅延 hosted MCP を持つ ToolSearchTool()）。中身のない ToolSearchTool() だけの構成は拒否されます
• instructions が「9 個の promise を先に全部作ってから Promise.all で一度に待て」「安全在庫は 5、reorder_units = max(forecast + 5 - available - inbound, 0) で計算せよ」とプログラムの書き方まで指示している点に注目してください。生成されるのはコードなので、指示も「アルゴリズムの仕様書」として書きます
• tool_choice="programmatic_tool_calling" で、直接呼び出しではなくプログラム生成を強制しています

実行結果からは、生成されたプログラム本体とプログラム経由の呼び出し記録を取り出せます。

    programmatic_calls: list[str] = []
    for item in result.new_items:
        if not isinstance(item, ToolCallItem):
            continue
        raw_item = item.raw_item
        if isinstance(raw_item, Program):
            print(f"\nGenerated program:\n{raw_item.code}\n")
        elif (
            isinstance(raw_item, ResponseFunctionToolCall)
            and raw_item.caller is not None
            and raw_item.caller.type == "program"
        ):
            programmatic_calls.append(raw_item.name)

• 生成されたプログラムは Program 型の raw_item として ToolCallItem に入り、.code で JavaScript のソースそのものを読めます。モデルが何を書いたかを人間が検査できるのがこの方式の重要な性質です
• プログラムから呼ばれた子ツールは raw_item.caller.type == "program" で判別できます。SDK は親プログラムと子呼び出しの関係を保持します
• プログラム経由の呼び出しでも、Runner の通常のライフサイクルはそのまま効きます。ツールの入出力 guardrail・フック・タイムアウト・同時実行数制限・承認・セッション・RunState の中断/再開はすべて従来どおり動作します

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 次のコマンドを実行します。

   uv run python examples/tools/programmatic_tool_calling.py

期待される動作・出力例

[tool] get_inventory(desk-lamp) のようなツール実行ログが 9 行分（順不同・並列実行のため）流れ、続いて Generated program: としてモデルが書いた JavaScript が表示されます。最後に Programmatic calls: get_inventory, get_weekly_demand, ... と、発注推奨をまとめた最終回答が出ます。

つまずきポイント

• Responses API の対応モデル専用です。 Chat Completions 系のモデルや非 Responses バックエンドでは、ProgrammaticToolCallingTool() と tool_choice="programmatic_tool_calling" は拒否されます
• ProgrammaticToolCallingTool() があると、モデルリクエストのリトライ条件が厳しくなります。プログラムが実行される前であっても、プロバイダー管理のリトライと WebSocket の事前イベントリトライは無効化されます。Runner のリトライポリシーは「プロバイダーが再送安全と明示した場合」だけ再試行し、retry_policies.network_error() 単体ではこの境界を越えられません
• 承認が要るツールや影響の大きいツールは、プログラムに渡さず直接呼び出しのままにしておくのが無難です。 プログラムの一部として一括実行されると、人間が 1 つずつ確認する余地がなくなります。なおプログラム経由の呼び出しが承認待ちで止まった場合も、RunState で中断を解決して元の実行を再開する通常の手順で対処できます
• ツールの返り値スキーマがある場合、既定の失敗フォーマッタ（例外を自由文のテキストに変換する仕組み）は無効化されます。自由文はスキーマを満たさないためです。ハンドラの例外はそのまま伝播するので、スキーマに沿った JSON を返す failure_error_function を自分で用意してください
• 公式プラットフォームガイド: Programmatic Tool Calling

この一連の流れを図にすると次のようになります。

codex.py

実験的機能 である Codex ツール（codex_tool）の example です。Codex CLI（OpenAI のコーディングエージェント用コマンドラインツール）をサブプロセスとして起動し、エージェントのツール呼び出しの中でワークスペース調査などのタスクを Codex に委任します。実験段階のため、API は今後変更される可能性があります。

コード解説

    agent = Agent(
        name="Codex Agent",
        instructions=(
            "Use the codex tool to inspect the workspace in read-only mode and answer the question. "
            ...
        ),
        tools=[
            # Run local Codex CLI as a sub process
            codex_tool(
                sandbox_mode="read-only",
                default_thread_options=ThreadOptions(
                    model="gpt-5.5",
                    model_reasoning_effort="low",
                    network_access_enabled=True,
                    web_search_enabled=False,
                    approval_policy="never",  # We'll update this example once the HITL is implemented
                ),
                default_turn_options=TurnOptions(
                    # Abort Codex CLI if no events arrive within this many seconds.
                    idle_timeout_seconds=60,
                ),
                on_stream=on_codex_stream,
            )
        ],
    )

• codex_tool(...) は agents.extensions.experimental.codex からインポートします（agents 直下ではありません）。
• sandbox_mode="read-only" — Codex にファイルの読み取りだけを許可します。書き込みを許す workspace-write などのモードもあります。
• ThreadOptions は Codex 側のセッション（スレッド）の既定設定（使用モデル、推論の深さ、ネットワークアクセス可否など）、TurnOptions は 1 ターンごとの設定（アイドルタイムアウトなど）です。
• on_stream=on_codex_stream — Codex の実行中に発生するイベント（スレッド開始、推論、コマンド実行、ファイル変更、Web 検索など）を受け取るコールバックです。ファイル前半の on_codex_stream() は、イベントの型を isinstance で判別してログ出力する網羅的なサンプルになっています。Codex が内部で何をしているかを可視化する仕組みとして参考になります。

main 処理では、リポジトリの pyproject.toml と AGENTS.md を Codex に読み取り専用で調査させ、対応 Python バージョンやローカル検証コマンドを要約させています。

実行手順

1. OPENAI_API_KEY が設定されていることを確認します（Codex 用に CODEX_API_KEY を別途設定することも可能です）。

2. 事前準備: Codex CLI が必要です。SDK は「環境変数 CODEX_PATH → PATH 上の codex コマンド → SDK 同梱のバイナリ」の順で実行ファイルを探します（ソースコード exec.py の解決順より）。手元に codex コマンドがない場合は、Node.js 環境で次のようにインストールできます。

   npm install -g @openai/codex

3. リポジトリルートから実行します（Codex がカレントディレクトリのファイルを調査するため）。

   uv run python examples/tools/codex.py

期待される動作・出力例

タイムスタンプ付きのログで codex thread started: ...、codex command item.completed: ... のようなイベントが流れ、最後に「対応 Python バージョンは 3.10 以上、テストコマンドは make check 系」といった要約と、codex resume <thread_id> でセッションを継続できる旨の案内が出力されます。

つまずきポイント

• 実験的機能 です。agents.extensions.experimental 配下の API は予告なく変わる可能性があります。
• approval_policy="never" は「Codex 側の承認確認を行わない」設定です。この example は read-only なので安全ですが、書き込みモードで使う際は慎重に設定してください。

codex_same_thread.py

Codex ツールの応用で、複数回の Runner.run() をまたいで同じ Codex スレッド（会話セッション）を再利用する example です。1 回目の調査結果を踏まえて、2 回目に「さっきの内容を 1 文に要約して」と依頼できます。

コード解説

        tools=[
            codex_tool(
                # Give each Codex tool a unique `codex_` name when you run multiple tools in one agent.
                # Name-based defaults keep their run-context thread IDs separated.
                name="codex_engineer",
                sandbox_mode="read-only",
                default_thread_options=ThreadOptions(
                    model="gpt-5.5",
                    model_reasoning_effort="low",
                    network_access_enabled=True,
                    web_search_enabled=False,
                    approval_policy="never",
                ),
                on_stream=on_codex_stream,
                # Reuse the same Codex thread across runs that share this context object.
                use_run_context_thread_id=True,
            )
        ],

• use_run_context_thread_id=True — Codex のスレッド ID を run context（Runner.run(..., context=...) で渡す、実行間で共有できる状態オブジェクト）に保存・再利用します。
• name="codex_engineer" — ツール名を変えると、スレッド ID の保存キーも codex_thread_id_engineer に変わります（既定名 codex なら codex_thread_id）。1 つのエージェントに複数の Codex ツールを持たせるときの分離の仕組みです。

    class MyContext(BaseModel):
        something: str | None = None
        # the default is "codex_thread_id"; missing this works as well
        codex_thread_id_engineer: str | None = None  # aligns with run_context_thread_id_key

    context = MyContext()

• context は Pydantic モデルでも素の辞書でも構いません。1 回目の実行後にこのフィールドへスレッド ID が書き込まれ、2 回目の実行はその ID で既存スレッドに接続します。
• main の最後で、1 回目と 2 回目のスレッド ID が一致するか（same thread reused: True）を検証しています。

実行手順

1. codex.py と同じ準備（OPENAI_API_KEY、Codex CLI）を整えます。

2. リポジトリルートから実行します。

   uv run python examples/tools/codex_same_thread.py

期待される動作・出力例

Turn 1 で AGENTS.md の検証コマンド一覧が出力され、thread id after turn 1: <ID> が表示されます。Turn 2 では同じスレッドの文脈を使って 1 文の要約が返り、最後に same thread reused: True と表示されます。

つまずきポイント

• 2 回の Runner.run() に 同じ context オブジェクト を渡すことが再利用の条件です。context を作り直すとスレッド ID が失われ、新しいスレッドが始まります。

まとめ

• ツールは「hosted tools（OpenAI サーバーで実行）」「ローカル実行ツール（モデルが指示し、あなたのコードが実行）」「function tools（自作 Python 関数）」に大別されます。
• hosted tools（WebSearchTool / FileSearchTool / CodeInterpreterTool / ImageGenerationTool など）は tools=[...] に置くだけで動きますが、OpenAI の Responses API 専用です。
• FileSearchTool は ベクトルストア ID（vs_...）の事前準備が必須 です。example は OpenAI クライアントでストアを自動作成する手順も含んでいます。
• ComputerTool は Playwright のインストールと playwright install chromium が事前に必要 で、AsyncComputer インターフェース（screenshot / click / type など）を自分で実装します。
• ShellTool はローカル実行（executor 自作 + needs_approval による承認）と hosted コンテナ実行（container_auto / container_reference、スキルのマウント）の両モードを持ちます。承認には「on_approval コールバック方式」と「interruption + state.approve() 方式」の 2 パターンがあります。
• ApplyPatchTool は diff ベースのファイル編集をエージェントに任せる仕組みで、ワークスペース境界チェックと承認が安全運用の鍵です。
• ToolSearchTool + defer_loading=True + tool_namespace() で、大量ツールのスキーマを必要時のみ読み込み、トークンを節約できます。
• ProgrammaticToolCallingTool() + @tool(allowed_callers=["programmatic"]) で、モデルが生成した JavaScript から複数ツールを並列に呼び、途中計算まで済ませて結果 1 個だけを返せます（v0.19.0 で追加）。ツール 1 回ごとのモデル往復がなくなる代わりに、Responses API 対応モデル限定・リトライ条件が厳格化・承認向きでない、という制約があります。
• codex_tool は Codex CLI をツールとして呼び出す実験的機能で、スレッド再利用による会話の継続もできます。

理解度チェック

解答と解説

参考リンク

• Tools ガイド（英語）: https://openai.github.io/openai-agents-python/tools/
• Tools ガイド（日本語）: https://openai.github.io/openai-agents-python/ja/tools/
• Examples 一覧（英語）: https://openai.github.io/openai-agents-python/examples/
• Examples 一覧（日本語）: https://openai.github.io/openai-agents-python/ja/examples/
• 実行結果（RunResult）ガイド（英語）: https://openai.github.io/openai-agents-python/results/
• 実行結果（RunResult）ガイド（日本語）: https://openai.github.io/openai-agents-python/ja/results/
• Human-in-the-loop ガイド（英語）: https://openai.github.io/openai-agents-python/human_in_the_loop/
• Human-in-the-loop ガイド（日本語）: https://openai.github.io/openai-agents-python/ja/human_in_the_loop/
• ストリーミングガイド（英語）: https://openai.github.io/openai-agents-python/streaming/
• ストリーミングガイド（日本語）: https://openai.github.io/openai-agents-python/ja/streaming/

第4章 エージェント設計パターン（agent_patterns）

@input_guardrail(run_in_parallel=False)
async def math_guardrail(context, agent, input):
    result = await Runner.run(guardrail_agent, input, context=context.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math_homework,
    )

前提知識

この章を読む前に、以下の内容を理解しておくことをおすすめします。

• 第1章: リポジトリのクローン、uv sync による環境構築、OPENAI_API_KEY の設定方法
• 第2章: Agent（エージェントの定義）と Runner（エージェントの実行）の基本、output_type による構造化出力、Runner.run_streamed によるストリーミング実行
• 第3章: function_tool デコレータによるツールの定義と、エージェントへのツールの登録方法

概念解説

一人の万能社員より、チームで分業する

ここまでの章では、1 つのエージェント（Agent。LLM に指示とツールを持たせた実行単位のこと）に仕事をさせる方法を学びました。しかし現実のアプリケーションでは、1 つのエージェントにすべてを任せると、指示文（instructions）が長くなりすぎて精度が落ちたり、間違った出力をそのままユーザーに返してしまったりする問題が起きます。

これは会社の仕事に似ています。一人の万能社員に「企画も執筆も校正も翻訳も全部やって」と頼むより、企画担当・執筆担当・校正担当に分業して、決まった手順で仕事を回す方が品質は安定します。マルチエージェント設計とは、この「分業と手順の設計」をエージェントで行うことです。

公式ドキュメント（docs/multi_agent.md）では、エージェントの協調（オーケストレーション）の方法を大きく 2 つに分類しています。

1. コードによるオーケストレーション: どのエージェントをどの順番で動かすかを Python コードで固定する方法。速度・コスト・結果が予測しやすい
2. LLM によるオーケストレーション: LLM 自身に「次に誰へ仕事を渡すか」を判断させる方法。柔軟だが結果は予測しにくい

この章の examples/agent_patterns ディレクトリは、この 2 つを組み合わせた「定石集」です。各パターンの位置づけを先にまとめておきます。

この 8 パターンを「誰が制御するか」という軸で並べ直すと、次の図のようになります。

handoff と agents as tools の違い（この章の最重要ポイント）

似て非なる 2 つのパターンの違いを、電話窓口にたとえて説明します。

• handoff（ハンドオフ。会話の引き継ぎ）: 総合受付が「その件は技術サポートにおつなぎします」と電話を転送するイメージです。転送後は技術サポートがあなたと直接話し、会話の主導権も履歴もそちらに移ります。
• agents as tools（エージェントのツール化）: 総合受付が保留にして内線で専門家に確認し、自分の言葉であなたに回答するイメージです。会話の相手はずっと総合受付のままで、専門家は裏方として結果だけを返します。

公式ドキュメントの判断基準は明快です。専門家に会話そのものを引き継がせたいなら handoff、司令塔（オーケストレーター）が最終回答を統合・所有すべきなら agents as tools を使います。handoff の詳細は次の第5章で扱うため、この章では routing.py で全体像だけつかみ、agents as tools を深掘りします。

この違いを電話窓口の比喩のまま図にすると、「ユーザーとの対話がどちらへ繋がり続けるか」がはっきり見えます。

この章で登場する用語

• 非同期処理（async/await）: 待ち時間の長い処理（API 呼び出しなど）の完了を待つ間に他の処理を進められる Python の仕組みです。examples はすべて asyncio.run(main()) で非同期関数を実行します
• ストリーミング: LLM の応答を、全文完成を待たずに生成されたそばから少しずつ受け取る方式です
• トークン: LLM が文章を処理する最小単位（文字や単語の断片で、分割方法はモデルにより異なる）で、API 課金の単位でもあります
• トレース（trace）: 一連のエージェント実行を 1 つの作業単位として記録する仕組みです。with trace("名前"): で囲むと、OpenAI ダッシュボードの Traces 画面で複数エージェントの動きを 1 本の流れとして確認できます
• コンテキスト（context）: 実行時にエージェントやツールへ引き回されるアプリ独自のデータ（ユーザー情報や設定など）です

なお、多くの example は examples.auto_mode というリポジトリ内の共通ヘルパーを import しています。これは環境変数 EXAMPLES_INTERACTIVE_MODE=auto を設定したときに、キーボード入力の代わりに既定値を自動入力してくれる仕組みです（input_with_fallback は入力プロンプト、confirm_with_fallback は y/n 確認の自動化）。普通に実行すれば対話式に動くので、読者が特別な設定をする必要はありません。ただし、この import があるためファイルパス指定の直接実行ではなく python -m によるモジュール指定での実行が必要です（実行手順で後述します）。

各 example の解説

以降のすべての example は、リポジトリのルートディレクトリ（openai-agents-python/）で、環境変数 OPENAI_API_KEY を設定した状態で実行してください。

export OPENAI_API_KEY="sk-..."  # 第1章参照

deterministic.py — 決定的フロー

物語の「アウトライン生成 → 品質チェック → 本文執筆」という 3 ステップを、コードで固定した順番どおりに実行する example です。各ステップを担当する 3 つのエージェントを、Python コードが順番に呼び出します。

いつ使うべきか: 業務の手順が事前に決まっていて、途中に「合格しなければ先に進ませない」品質ゲートを置きたいときに最適です。LLM に手順の判断を任せないため、実行時間・コスト・結果のばらつきが最小になります。

コード解説

まず 3 つのエージェントを定義します。ポイントは 2 番目のチェック担当エージェントに output_type（構造化出力。LLM の返答を自由文ではなく指定した型のデータとして受け取る機能）を指定していることです。

story_outline_agent = Agent(
    name="story_outline_agent",
    instructions="Generate a very short story outline based on the user's input.",
)


class OutlineCheckerOutput(BaseModel):
    good_quality: bool
    is_scifi: bool


outline_checker_agent = Agent(
    name="outline_checker_agent",
    instructions="Read the given story outline, and judge the quality. Also, determine if it is a scifi story.",
    output_type=OutlineCheckerOutput,
)

story_agent = Agent(
    name="story_agent",
    instructions="Write a short story based on the given outline.",
    output_type=str,
)

OutlineCheckerOutput は Pydantic（Python のデータ検証ライブラリ）のモデルで、「品質は良いか」「SF か」を 2 つの真偽値で返させます。自由文ではなく bool で受け取るからこそ、次の if 文でコードによる分岐が可能になる——これが決定的フローの核心です。

メイン処理では、前のエージェントの出力（final_output）を次のエージェントの入力として手渡ししていきます。

    # Ensure the entire workflow is a single trace
    with trace("Deterministic story flow"):
        # 1. Generate an outline
        outline_result = await Runner.run(
            story_outline_agent,
            input_prompt,
        )
        print("Outline generated")

        # 2. Check the outline
        outline_checker_result = await Runner.run(
            outline_checker_agent,
            outline_result.final_output,
        )

        # 3. Add a gate to stop if the outline is not good quality or not a scifi story
        assert isinstance(outline_checker_result.final_output, OutlineCheckerOutput)
        if not outline_checker_result.final_output.good_quality:
            print("Outline is not good quality, so we stop here.")
            exit(0)

        if not outline_checker_result.final_output.is_scifi:
            print("Outline is not a scifi story, so we stop here.")
            exit(0)

        print("Outline is good quality and a scifi story, so we continue to write the story.")

        # 4. Write the story
        story_result = await Runner.run(
            story_agent,
            outline_result.final_output,
        )
        print(f"Story: {story_result.final_output}")

with trace("Deterministic story flow"): で 3 回の Runner.run を囲むことで、3 つのエージェント実行がダッシュボード上で 1 つのワークフローとして記録されます。品質ゲート（ステップ 3）で不合格なら exit(0) で打ち切り、高価な本文執筆ステップを実行しません。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.deterministic

2. What kind of story do you want? と聞かれるので、書いてほしい物語の内容（例: A sci-fi story about a robot）を入力します。

期待される動作・出力例

What kind of story do you want? A sci-fi story about a robot
Outline generated
Outline is good quality and a scifi story, so we continue to write the story.
Story: （生成された短編小説の本文）

SF 以外の題材（例: 恋愛小説）を入力すると、Outline is not a scifi story, so we stop here. と表示されて途中終了します。

つまずきポイント

• 入力を英語以外で書いても動作しますが、チェック担当の判定（is_scifi）は LLM の解釈に依存するため、曖昧な題材では合否が実行のたびに変わることがあります。決定的なのは「フローの順序」であって「LLM の判定内容」ではない点に注意してください。

routing.py — ルーティング（handoff によるトリアージ）

最初に受け付ける「トリアージエージェント」（triage。緊急度や種別を見て振り分ける係のこと）が、ユーザーのメッセージの言語を判別し、フランス語・スペイン語・英語の専門エージェントへ handoff する example です。応答はストリーミングで表示されます。

いつ使うべきか: 「振り分け」自体が業務フローの一部で、振り分け先の専門エージェントがそのままユーザーと会話を続けるべきときに使います。カスタマーサポートの一次受付などが典型です。

コード解説

エージェント定義はシンプルで、トリアージエージェントの handoffs パラメータに委譲先の候補を並べるだけです。

french_agent = Agent(
    name="french_agent",
    instructions="You only speak French",
)

spanish_agent = Agent(
    name="spanish_agent",
    instructions="You only speak Spanish",
)

english_agent = Agent(
    name="english_agent",
    instructions="You only speak English",
)

triage_agent = Agent(
    name="triage_agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[french_agent, spanish_agent, english_agent],
)

メインループでは Runner.run_streamed でストリーミング実行し、テキストの断片（delta）が届くたびに画面へ出力します。

        with trace("Routing example", group_id=conversation_id):
            result = Runner.run_streamed(
                agent,
                input=inputs,
            )
            async for event in result.stream_events():
                if not isinstance(event, RawResponsesStreamEvent):
                    continue
                data = event.data
                if isinstance(data, ResponseTextDeltaEvent):
                    print(data.delta, end="", flush=True)
                elif isinstance(data, ResponseContentPartDoneEvent):
                    print("\n")

        inputs = result.to_input_list()
        print("\n")

        if auto_mode:
            break
        user_msg = input_with_fallback("Enter a message: ", "Thanks!")
        inputs.append({"content": user_msg, "role": "user"})
        agent = result.current_agent

最後の 2 行が handoff の本質を示しています。result.to_input_list() でこれまでの会話履歴を取り出して次の入力とし、さらに result.current_agent（handoff 後に会話を担当しているエージェント）を次のターンの開始エージェントにする——つまり 2 回目以降の発言はトリアージを経由せず、引き継いだ専門エージェントに直接届きます。「会話の主導権が移る」という handoff の性質がコードにそのまま表れています。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.routing

2. 最初のメッセージ（例: Hola, ¿cómo estás?）を入力します。
3. 応答後、続けてメッセージを入力できます。終了は Ctrl+C です。

期待される動作・出力例

Hi! We speak French, Spanish and English. How can I help? Hola, ¿cómo estás?
¡Hola! Estoy muy bien, gracias. ¿Y tú? ...（スペイン語の応答がストリーミング表示される）

Enter a message:

スペイン語で話しかけると spanish_agent に handoff され、以降はスペイン語で会話が続きます。

つまずきポイント

• 2 回目以降に別の言語で話しかけても、開始エージェントがすでに専門エージェントに切り替わっているため、自動では別言語の担当に振り直されません。常にトリアージへ戻したい場合は、専門エージェント側にもトリアージへの handoff を持たせる設計（第5章で解説）が必要です。

agents_as_tools.py — エージェントをツールとして使う

司令塔（orchestrator）エージェントが、スペイン語・フランス語・イタリア語の翻訳エージェントをツールとして呼び出し、最後に別の統合（synthesizer）エージェントが結果を検品・整形する example です。

いつ使うべきか: 「複数の専門家の成果を 1 つの回答に統合したい」「会話の窓口は 1 つのエージェントに固定したい」ときに使います。handoff と違って複数の専門家を 1 ターン内で何度でも呼べるため、「複数言語へ同時に翻訳」のような並列的な依頼に向きます。

コード解説

核心は Agent.as_tool() メソッドです。エージェントを、他のエージェントから呼び出せる関数ツール（FunctionTool）に変換します。

orchestrator_agent = Agent(
    name="orchestrator_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools in order."
        "You never translate on your own, you always use the provided tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="Translate the user's message to Italian",
        ),
    ],
)

as_tool() のソースコード（src/agents/agent.py）のコメントには、handoff との違いが明記されています。（1）handoff では新しいエージェントが会話履歴全体を受け取るのに対し、ツール化されたエージェントは呼び出し元 LLM が生成した入力文字列だけを受け取る、（2）handoff では会話の主導権が移るが、ツール呼び出しでは元のエージェントが会話を続ける、の 2 点です。

instructions に「You never translate on your own（自分では絶対に翻訳しない）」と念押ししている点にも注目してください。LLM は放っておくと自力で翻訳してしまうため、ツールへの委譲を指示文で強制するのが定石です。

メイン処理では、司令塔の実行結果から中間のツール出力を表示し、その全履歴を統合エージェントへ渡します。

    with trace("Orchestrator evaluator"):
        orchestrator_result = await Runner.run(orchestrator_agent, msg)

        for item in orchestrator_result.new_items:
            if isinstance(item, MessageOutputItem):
                text = ItemHelpers.text_message_output(item)
                if text:
                    print(f"  - Translation step: {text}")

        synthesizer_result = await Runner.run(
            synthesizer_agent, orchestrator_result.to_input_list()
        )

    print(f"\n\nFinal response:\n{synthesizer_result.final_output}")

new_items は実行中に生成されたアイテム（メッセージ、ツール呼び出し、ツール結果など）のリストで、ItemHelpers.text_message_output はその中からテキストメッセージ部分を取り出すユーティリティです。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.agents_as_tools

2. 翻訳したい文と言語（例: Translate 'Hello, world!' to French and Spanish.）を入力します。

期待される動作・出力例

Hi! What would you like translated, and to which languages? Translate 'Hello, world!' to French and Spanish.
  - Translation step: Bonjour, le monde !
  - Translation step: ¡Hola, mundo!

Final response:
French: Bonjour, le monde !
Spanish: ¡Hola, mundo!

つまずきポイント

• ツール化されたエージェントには会話履歴が渡らないため、「さっきの文を訳して」のような文脈依存の依頼は失敗します。文脈を渡したい場合は、司令塔がツール引数に必要な情報をすべて含めるよう instructions を工夫するか、後述の parameters による構造化入力を使います。

agents_as_tools_conditional.py — 条件付きツール有効化 + 承認

ユーザーの言語設定（コンテキスト）に応じて、司令塔が使える翻訳ツールを動的に増減させる example です。as_tool(is_enabled=...) によるツールの出し分けと、needs_approval=True による承認フロー（human-in-the-loop）の組み合わせを学べます。

いつ使うべきか: ユーザーの権限・プラン・設定によって「LLM に見せるツールの選択肢そのもの」を変えたいときに使います。instructions で「このツールは使うな」と指示するより、そもそも見せない方が確実です。

コード解説

まずアプリ独自のコンテキスト型と、有効化判定の関数を定義します。

class AppContext(BaseModel):
    language_preference: str = "spanish_only"  # "spanish_only", "french_spanish", "european"


def french_spanish_enabled(ctx: RunContextWrapper[AppContext], agent: AgentBase) -> bool:
    """Enable for French+Spanish and European preferences."""
    return ctx.context.language_preference in ["french_spanish", "european"]


def european_enabled(ctx: RunContextWrapper[AppContext], agent: AgentBase) -> bool:
    """Only enable for European preference."""
    return ctx.context.language_preference == "european"

RunContextWrapper は、Runner.run(..., context=...) で渡したアプリ独自データを包んで各所へ引き回す SDK のラッパーです。判定関数は実行時に呼ばれ、True を返したツールだけが LLM に提示されます。

司令塔のツール定義では、この判定関数を is_enabled に渡します。スペイン語ツールには needs_approval=True も付いています。

    tools=[
        spanish_agent.as_tool(
            tool_name="respond_spanish",
            tool_description="Respond to the user's question in Spanish",
            is_enabled=True,  # Always enabled
            needs_approval=True,  # HITL
        ),
        french_agent.as_tool(
            tool_name="respond_french",
            tool_description="Respond to the user's question in French",
            is_enabled=french_spanish_enabled,
        ),
        italian_agent.as_tool(
            tool_name="respond_italian",
            tool_description="Respond to the user's question in Italian",
            is_enabled=european_enabled,
        ),
    ],

さらに spanish_agent 自身も内部に承認必須のツール get_user_name を持ち、ModelSettings(tool_choice="required") で必ずツールを使うよう設定されています（tool_choice は後述の forcing_tool_use.py で詳しく解説します）。

@tool(needs_approval=True)
async def get_user_name() -> str:
    print("Getting the user's name...")
    return "Kaz"

メイン処理では、実行前に get_all_tools() で「今のコンテキストで LLM から見えるツール一覧」を確認できます。

    context = RunContextWrapper(AppContext(language_preference=language_preference))
    available_tools = await orchestrator.get_all_tools(context)
    tool_names = [tool.name for tool in available_tools]

実行後は、承認待ちがあれば result.interruptions に入っているので、承認（state.approve）または拒否（state.reject）してから再実行します。

        result = await Runner.run(
            starting_agent=orchestrator,
            input=user_request,
            context=context.context,
        )
        while result.interruptions:

            async def confirm(question: str) -> bool:
                return confirm_with_fallback(f"{question} (y/n): ", default=True)

            state = result.to_state()
            for interruption in result.interruptions:
                prompt = f"\nDo you approve this tool call: {interruption.name} with arguments {interruption.arguments}?"
                confirmed = await confirm(prompt)
                if confirmed:
                    state.approve(interruption)
                    print(f"✓ Approved: {interruption.name}")
                else:
                    state.reject(interruption)
                    print(f"✗ Rejected: {interruption.name}")
            result = await Runner.run(orchestrator, state)

注目すべきは、入れ子になったエージェント（spanish_agent の中の get_user_name）の承認要求も、外側の実行（orchestrator）の interruptions に浮上してくる点です。公式ドキュメント（docs/human_in_the_loop.md）にあるとおり、承認はどの階層で発生しても常に最上位の実行で処理し、最上位のエージェントで再開します。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.agents_as_tools_conditional

2. 言語設定を 1〜3 で選びます（3 を選ぶと 3 ツールすべてが有効になります）。
3. 質問（例: How do you say good morning?)を入力します。
4. 承認を求められたら y または n を入力します。

期待される動作・出力例

Choose language preference:
1. Spanish only (1 tool)
2. French and Spanish (2 tools)
3. European languages (3 tools)

Select option (1-3): 2

Language preference: french_spanish
Available tools: respond_spanish, respond_french
The LLM will only see and can use these 2 tools

...
Do you approve this tool call: respond_spanish with arguments {...}? (y/n): y
✓ Approved: respond_spanish
...
Response:
（スペイン語とフランス語の回答）

つまずきポイント

• Runner.run の context 引数には RunContextWrapper そのものではなく、中身（context.context）を渡している点に注意してください。RunContextWrapper を自分で作っているのは、実行前に get_all_tools(context) を呼ぶためです。
• 承認ループの終了条件は result.interruptions が空になることです。承認・拒否のどちらを選んでも実行は最後まで進みます（拒否時はその旨が LLM に伝わり、LLM が代替の回答を組み立てます）。

agents_as_tools_streaming.py — 入れ子エージェントのストリーミング観測

エージェントをツール化すると、その内部の動きは通常ブラックボックスになります。この example は as_tool(on_stream=...) コールバックを使い、入れ子で動く請求（billing）エージェントの内部イベントをリアルタイムに観測する方法を示します。

いつ使うべきか: ツール化したエージェントの進捗をユーザーに見せたいとき（「調査中…」のような UI 表示）や、内部動作のデバッグ・ロギングをしたいときに使います。

コード解説

このファイルは対話入力なしで完結します。まず、ツール名と説明を明示した関数ツールを定義します（name_override / description_override は関数名や docstring の代わりに任意の名前・説明を指定するオプションです）。

@tool(
    name_override="billing_status_checker",
    description_override="Answer questions about customer billing status.",
)
def billing_status_checker(customer_id: str | None = None, question: str = "") -> str:
    """Return a canned billing answer or a fallback when the question is unrelated."""
    normalized = question.lower()
    if "bill" in normalized or "billing" in normalized:
        return f"This customer (ID: {customer_id})'s bill is $100"
    return "I can only answer questions about billing."

次にストリーミングイベントを受け取るコールバックです。AgentToolStreamEvent は辞書型（TypedDict）で、event（ストリームイベント本体）、agent（イベントを発した入れ子エージェント）、tool_call（呼び出し元のツールコール情報）の 3 つのキーを持ちます。

def handle_stream(event: AgentToolStreamEvent) -> None:
    """Print streaming events emitted by the nested billing agent."""
    stream = event["event"]
    tool_call = event.get("tool_call")
    tool_call_info = tool_call.call_id if tool_call is not None else "unknown"
    print(f"[stream] agent={event['agent'].name} call={tool_call_info} type={stream.type} {stream}")

組み立て部分では、billing_agent をツール化する際に on_stream=handle_stream を渡します。ソースコードの仕様どおり、on_stream を指定すると入れ子エージェントは自動的にストリーミングモードで実行されます。

        billing_agent_tool = billing_agent.as_tool(
            tool_name="billing_agent",
            tool_description="You are a billing agent that answers billing questions.",
            on_stream=handle_stream,
        )

        main_agent = Agent(
            name="Customer Support Agent",
            instructions=(
                "You are a customer support agent. Always call the billing agent to answer billing "
                "questions and return the billing agent response to the user."
            ),
            tools=[billing_agent_tool],
        )

        result = await Runner.run(
            main_agent,
            "Hello, my customer ID is ABC123. How much is my bill for this month?",
        )

外側の Runner.run は通常の（非ストリーミングの）実行のままで、入れ子エージェントのイベントだけがコールバック経由で流れてくる、という構造です。

実行手順

1. リポジトリルートで以下を実行します（対話入力は不要です）。

   uv run python -m examples.agent_patterns.agents_as_tools_streaming

期待される動作・出力例

[stream] agent=Billing Agent call=call_abc123 type=raw_response_event ...
[stream] agent=Billing Agent call=call_abc123 type=run_item_stream_event ...
（多数のイベント行が続く）

Final response:
Your bill for this month is $100 (customer ID: ABC123).

つまずきポイント

• イベントは生データがそのまま print されるため出力が大量になります。実用時は stream.type でフィルタし、必要なイベント（テキスト delta やツール呼び出し）だけを扱うのが普通です。

agents_as_tools_structured.py — 構造化入力によるツール化

エージェントツールの引数を、既定の「自由なテキスト 1 個」ではなく、Pydantic モデルで定義した構造化パラメータ（翻訳対象テキスト・元言語・先言語）にする example です。

いつ使うべきか: ツール化したエージェントに渡すべき情報が複数の要素からなるとき（翻訳の 3 要素、検索のクエリ+件数+期間など）に使います。呼び出し元 LLM が必要な情報を漏れなく渡すことを、型スキーマの力で強制できます。

コード解説

ファイルはコメント込みで 65 行と短いため、主要部を通して見ます。

class TranslationInput(BaseModel):
    text: str = Field(description="Text to translate.")
    source: str = Field(description="Source language code or name.")
    target: str = Field(description="Target language code or name.")


translator = Agent(
    name="translator",
    instructions=(
        "Translate the input text into the target language. "
        "If the target is not clear, ask the user for clarification."
    ),
)

orchestrator = Agent(
    name="orchestrator",
    instructions=(
        "You are a task dispatcher. Always call the tool with sufficient input. "
        "Do not handle the translation yourself."
    ),
    tools=[
        translator.as_tool(
            tool_name="translate_text",
            tool_description=(
                "Translate text between languages. Provide text, source language, "
                "and target language."
            ),
            parameters=TranslationInput,
            # By default, the input schema will be included in a simpler format.
            # Set include_input_schema to true to include the full JSON Schema:
            # include_input_schema=True,
            # Build a custom prompt from structured input data:
            # input_builder=lambda options: (
            #     f'Translate the text "{options["params"]["text"]}" '
            #     f'from {options["params"]["source"]} to {options["params"]["target"]}.'
            # ),
        )
    ],
)

as_tool(parameters=TranslationInput) により、呼び出し元 LLM に提示されるツール定義の引数が text / source / target の 3 フィールドになります。ソースコード上、parameters には Pydantic モデルまたは dataclass を指定でき、コメントアウトされた 2 つのオプションも用意されています。

• include_input_schema=True: 入れ子エージェントへの入力に完全な JSON Schema（データ構造を記述する標準形式）を含める
• input_builder: 構造化データから入れ子エージェントへ渡すプロンプト文字列を自作する関数

メイン処理は、同じ質問を「translator を直接実行した場合」と「orchestrator 経由でツールとして実行した場合」で比較します。

async def main() -> None:
    query = 'Translate "Hola" from Spanish to French.'

    response1 = await Runner.run(translator, query)
    print(f"Translator agent direct run: {response1.final_output}")

    response2 = await Runner.run(orchestrator, query)
    print(f"Translator agent as tool: {response2.final_output}")

実行手順

1. リポジトリルートで以下を実行します（対話入力は不要です）。

   uv run python -m examples.agent_patterns.agents_as_tools_structured

期待される動作・出力例

Translator agent direct run: Bonjour
Translator agent as tool: The translation of "Hola" from Spanish to French is "Bonjour".

直接実行では翻訳結果そのもの、ツール経由では orchestrator が結果を文章にまとめて返す、という違いが観察できます。

つまずきポイント

• parameters に指定できるのは Pydantic モデルか dataclass だけです。それ以外の型を渡すと TypeError（Agent tool parameters must be a dataclass or Pydantic model type.）が発生します。

parallelization.py — 並列実行

同じ翻訳エージェントを 3 回並列に実行して 3 通りのスペイン語訳を作り、別の「選定エージェント」に最良の 1 つを選ばせる example です。

いつ使うべきか: （1）互いに依存しない複数タスクを同時に走らせて待ち時間を短縮したいとき、（2）LLM の出力のばらつきを逆手に取り、複数案を生成してベストを選ぶ「best-of-N」で品質を上げたいとき、の 2 つの場面で使います。SDK 特有の機能は使わず、Python 標準の asyncio.gather だけで実現できるのがポイントです。

コード解説

エージェントは「翻訳担当」と「選定担当」の 2 つだけです。

spanish_agent = Agent(
    name="spanish_agent",
    instructions="You translate the user's message to Spanish",
)

translation_picker = Agent(
    name="translation_picker",
    instructions="You pick the best Spanish translation from the given options.",
)

メイン処理では asyncio.gather（複数の非同期処理を同時に開始し、全部の完了を待つ関数）で同一エージェントを 3 回走らせます。

    with trace("Parallel translation"):
        res_1, res_2, res_3 = await asyncio.gather(
            Runner.run(
                spanish_agent,
                msg,
            ),
            Runner.run(
                spanish_agent,
                msg,
            ),
            Runner.run(
                spanish_agent,
                msg,
            ),
        )

        outputs = [
            ItemHelpers.text_message_outputs(res_1.new_items),
            ItemHelpers.text_message_outputs(res_2.new_items),
            ItemHelpers.text_message_outputs(res_3.new_items),
        ]

        translations = "\n\n".join(outputs)
        print(f"\n\nTranslations:\n\n{translations}")

        best_translation = await Runner.run(
            translation_picker,
            f"Input: {msg}\n\nTranslations:\n{translations}",
        )

3 つの結果を文字列として連結し、元の入力と一緒に選定エージェントへ渡す——後段の入力をコードで組み立てる点は決定的フローと同じ発想です。LLM は同じ入力でも毎回少しずつ違う出力を返す性質があるため、3 案はたいてい互いに異なります。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.parallelization

2. 翻訳したいメッセージ（例: Good morning!）を入力します。

期待される動作・出力例

Hi! Enter a message, and we'll translate it to Spanish.

Good morning!

Translations:

¡Buenos días!

¡Buen día!

Buenos días.

-----
Best translation: ¡Buenos días!

つまずきポイント

• 並列実行は速度を上げますが、API 呼び出し回数（= コストとレート制限の消費）は実行回数分だけ増えます。best-of-N は品質とコストのトレードオフであることを意識してください。

asyncio.gather で 3 本の実行が同時に走り、結果がそろってから選定エージェントへ渡る流れは次の図のとおりです。

llm_as_a_judge.py — LLM を審査員にする

物語のアウトラインを生成するエージェントと、それを採点してフィードバックを返す「審査員」エージェントを while ループで交互に実行し、審査員が合格（pass）を出すまで改善を繰り返す example です。

いつ使うべきか: 出力の品質基準が「一発生成では満たしにくいが、評価はしやすい」ときに有効です。文章の推敲、コードレビュー、要件チェックなどが典型です。README が示唆するとおり、生成側に小さく安価なモデル、審査側に大きく賢いモデルを使うコスト最適化も可能です。

コード解説

審査員の出力は dataclass による構造化出力で、3 段階のスコアとフィードバック文を返します（Literal 型は「この 3 つの文字列のどれか」に値を制限する型ヒントです）。

@dataclass
class EvaluationFeedback:
    feedback: str
    score: Literal["pass", "needs_improvement", "fail"]


evaluator = Agent[None](
    name="evaluator",
    instructions=(
        "You evaluate a story outline and decide if it's good enough. "
        "If it's not good enough, you provide feedback on what needs to be improved. "
        "Never give it a pass on the first try. After 5 attempts, you can give it a pass if the story outline is good enough - do not go for perfection"
    ),
    output_type=EvaluationFeedback,
)

instructions の「Never give it a pass on the first try（初回では絶対に合格を出すな）」「5 回試したら完璧を求めず合格させてよい」という指示は、実際の運用でも重要なテクニックです。審査員が甘すぎるとループの意味がなく、厳しすぎると無限ループするため、合格基準と打ち切り条件をプロンプトに明示します。

改善ループの本体は以下です。

    with trace("LLM as a judge"):
        while True:
            story_outline_result = await Runner.run(
                story_outline_generator,
                input_items,
            )

            input_items = story_outline_result.to_input_list()
            latest_outline = ItemHelpers.text_message_outputs(story_outline_result.new_items)
            print("Story outline generated")

            evaluator_result = await Runner.run(evaluator, input_items)
            result: EvaluationFeedback = evaluator_result.final_output

            print(f"Evaluator score: {result.score}")

            if result.score == "pass":
                print("Story outline is good enough, exiting.")
                break

不合格の場合は、フィードバックを user ロールのメッセージとして履歴に追加し、生成エージェントへ再投入します。

            print("Re-running with feedback")

            input_items.append({"content": f"Feedback: {result.feedback}", "role": "user"})

生成エージェント側の instructions に「If there is any feedback provided, use it to improve the outline.（フィードバックがあればそれを使って改善せよ）」とあるため、2 周目以降は指摘を反映したアウトラインが生成されます。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.llm_as_a_judge

2. 聞きたい物語の内容（例: A detective story in space.）を入力します。

期待される動作・出力例

What kind of story would you like to hear? A detective story in space.
Story outline generated
Evaluator score: needs_improvement
Re-running with feedback
Story outline generated
Evaluator score: needs_improvement
Re-running with feedback
Story outline generated
Evaluator score: pass
Story outline is good enough, exiting.
Final story outline: （改善を重ねたアウトライン）

つまずきポイント

• ループ 1 周ごとに生成 + 審査で最低 2 回の API 呼び出しが発生します。トークン消費が周回数に比例して増えるため、実運用では最大周回数の上限をコード側にも入れるのが安全です（この example では対話モード時のコード上の上限はなく、審査員のプロンプトで打ち切りを制御しています）。

生成と審査を交互に繰り返すこの改善ループを図にすると次のようになります。

input_guardrails.py — 入力ガードレール

カスタマーサポートエージェントに「数学の宿題を解かせようとする入力」を検知する入力 guardrail（ガードレール。入出力を検査する安全柵の仕組み）を取り付け、検知したら本体の実行を中断して定型の断り文を返す example です。

いつ使うべきか: 高価で賢いモデルを使う本体エージェントを、規約違反・目的外利用・悪意ある入力から守りたいときに使います。検査には高速で安価なモデルを使えるため、「不正入力に高いモデルの料金を払わない」というコスト防御の意味もあります。

コード解説

guardrail 自体も小さなエージェントとして実装できます。検査結果は構造化出力で受け取ります。

class MathHomeworkOutput(BaseModel):
    reasoning: str
    is_math_homework: bool


guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking you to do their math homework.",
    output_type=MathHomeworkOutput,
)


@input_guardrail
async def math_guardrail(
    context: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
    """This is an input guardrail function, which happens to call an agent to check if the input
    is a math homework question.
    """
    result = await Runner.run(guardrail_agent, input, context=context.context)
    final_output = result.final_output_as(MathHomeworkOutput)

    return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=final_output.is_math_homework,
    )

@input_guardrail デコレータを付けた関数は、（1）コンテキスト、（2）対象エージェント、（3）エージェントに渡されたのと同じ入力、を受け取り、GuardrailFunctionOutput を返します。なお v0.19.0 以降、examples は input_guardrail / output_guardrail を agents.decorators からインポートしています（from agents import input_guardrail でも同じものが得られます。agents.decorators は tool / input_guardrail / output_guardrail / tool_input_guardrail / tool_output_guardrail を 1 か所に集めた公開モジュールです）。tripwire_triggered（トリップワイヤー。侵入を検知すると作動する仕掛け線のこと）が True になると、SDK は InputGuardrailTripwireTriggered 例外を送出して実行を停止します。

本体エージェントへの取り付けは input_guardrails パラメータ、例外処理は通常の try/except です。

    agent = Agent(
        name="Customer support agent",
        instructions="You are a customer support agent. You help customers with their questions.",
        input_guardrails=[math_guardrail],
    )

        try:
            result = await Runner.run(agent, input_data)
            print(result.final_output)
            # If the guardrail didn't trigger, we use the result as the input for the next run
            input_data = result.to_input_list()
        except InputGuardrailTripwireTriggered:
            # If the guardrail triggered, we instead add a refusal message to the input
            message = "Sorry, I can't help you with your math homework."
            print(message)
            input_data.append(
                {
                    "role": "assistant",
                    "content": message,
                }
            )

例外を捕捉したら、断り文を assistant ロールとして会話履歴に追加し、次のターンへ進みます。こうすることで「断った」事実も会話の文脈に残ります。

公式ドキュメント（docs/guardrails.md）の重要な補足を 2 点挙げます。

• 入力 guardrail はチェーンの最初のエージェントでのみ実行され、出力 guardrail は最終出力を出すエージェントでのみ実行されます
• 既定では guardrail は本体エージェントと並行に実行されます（レイテンシ最優先）。run_in_parallel=False を指定すると本体の開始前に guardrail を完了させる「ブロッキング実行」になり、検査で拒否された入力について、本体の開始を防ぎます。検査用モデルのトークン消費は残り、検査の見逃しや別経路のツール実行まで防ぐ保証ではありません

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.input_guardrails

2. まず普通の質問（例: What's the capital of California?）を入力し、次に数学の宿題（例: Can you help me solve for x: 2x + 5 = 11）を入力して挙動の違いを確認します。

期待される動作・出力例

ファイル末尾のコメントに実行例が記載されています。

Enter a message: What's the capital of California?
The capital of California is Sacramento.
Enter a message: Can you help me solve for x: 2x + 5 = 11
Sorry, I can't help you with your math homework.

つまずきポイント

• 既定の並行実行モードでは、guardrail が作動したときすでに本体エージェントが動き始めておりトークンを消費している可能性があります。本体の先行実行を避けたい場合はブロッキング実行を選びます。検査そのものの費用は発生し、外部操作にはツール単位の検証と承認も必要です。

既定の並行実行とブロッキング実行（run_in_parallel=False）の違いを図で比較します。

output_guardrails.py — 出力ガードレール

エージェントの最終出力に電話番号（この例では「650」という市外局番）が含まれていないかを検査し、含まれていたら OutputGuardrailTripwireTriggered 例外で止める example です。個人情報などの機微データの流出防止を模しています。

いつ使うべきか: 「ユーザーに見せてはいけない情報（個人情報、社外秘、不適切表現）が出力に混ざるリスク」を最後の関門で摘み取りたいときに使います。入力 guardrail が「門番」なら、出力 guardrail は「検品係」です。

コード解説

エージェントの出力型と guardrail 関数を定義します。今回は LLM を使わず、単純な文字列判定です。

class MessageOutput(BaseModel):
    reasoning: str = Field(description="Thoughts on how to respond to the user's message")
    response: str = Field(description="The response to the user's message")
    user_name: str | None = Field(description="The name of the user who sent the message, if known")


@output_guardrail
async def sensitive_data_check(
    context: RunContextWrapper, agent: Agent, output: MessageOutput
) -> GuardrailFunctionOutput:
    phone_number_in_response = "650" in output.response
    phone_number_in_reasoning = "650" in output.reasoning

    return GuardrailFunctionOutput(
        output_info={
            "phone_number_in_response": phone_number_in_response,
            "phone_number_in_reasoning": phone_number_in_reasoning,
        },
        tripwire_triggered=phone_number_in_response or phone_number_in_reasoning,
    )


agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    output_type=MessageOutput,
    output_guardrails=[sensitive_data_check],
)

@output_guardrail の関数は第 3 引数にエージェントの最終出力（ここでは MessageOutput 型のオブジェクト）を受け取ります。response だけでなく reasoning（思考過程）フィールドも検査している点が実践的です。ユーザーに直接見せないフィールドにも機微データは漏れ得ます。

メイン処理は安全な質問と危険な質問を 1 回ずつ実行して比較します。

async def main():
    # This should be ok
    await Runner.run(agent, "What's the capital of California?")
    print("First message passed")

    # This should trip the guardrail
    try:
        result = await Runner.run(
            agent, "My phone number is 650-123-4567. Where do you think I live?"
        )
        print(
            f"Guardrail didn't trip - this is unexpected. Output: {json.dumps(result.final_output.model_dump(), indent=2)}"
        )

    except OutputGuardrailTripwireTriggered as e:
        print(f"Guardrail tripped. Info: {e.guardrail_result.output.output_info}")

例外オブジェクトの e.guardrail_result.output.output_info から、guardrail 関数が output_info に詰めた診断情報を取り出せます。

実行手順

1. リポジトリルートで以下を実行します（対話入力は不要です）。

   uv run python -m examples.agent_patterns.output_guardrails

期待される動作・出力例

First message passed
Guardrail tripped. Info: {'phone_number_in_response': True, 'phone_number_in_reasoning': False}

（LLM が電話番号を reasoning にも書いた場合は phone_number_in_reasoning も True になります。）

つまずきポイント

• 出力 guardrail は最終出力の完成後に実行されるため、入力 guardrail と違いトークン消費の節約にはなりません。目的は「漏らさないこと」です。
• 2 番目の質問で LLM が応答に「650」を含めなかった場合、想定どおり guardrail が作動しないことがあります（Guardrail didn't trip - this is unexpected. と表示されます）。LLM の出力は確率的である、という教訓も含んだ example です。

streaming_guardrails.py — ストリーミング中のガードレール

出力 guardrail は「全部できてから検品」ですが、ストリーミングでは応答が長いほど不適切な内容が画面に流れ続けてしまいます。この example は、ストリーミング中に約 300 文字ごとに途中経過を検査し、問題を検知したら配信を打ち切る自前の実装パターンを示します。

いつ使うべきか: チャット UI のようにストリーミング表示するアプリで、不適切な出力を「流れきる前に」止めたいときに使います。SDK の guardrail 機能ではなく asyncio を使った手組みのパターンである点に注意してください。

コード解説

本体エージェントはあえて冗長な長文を書く設定、検査エージェントは「10 歳児に理解できる文章か」を判定する設定です。検査側には明示的に軽量モデル gpt-4o-mini を指定しています。

guardrail_agent = Agent(
    name="Checker",
    instructions=(
        "You will be given a question and a response. Your goal is to judge whether the response "
        "is simple enough to be understood by a ten year old."
    ),
    output_type=GuardrailOutput,
    model="gpt-4o-mini",
)


async def check_guardrail(text: str) -> GuardrailOutput:
    result = await Runner.run(guardrail_agent, text)
    return result.final_output_as(GuardrailOutput)

メインループでは、テキスト delta を受け取り画面に流しつつ、蓄積文字数がしきい値を超えたら検査をバックグラウンドタスクとして起動します（asyncio.create_task は非同期処理を「待たずに」開始する関数です。検査中もストリーミング表示は止まりません）。

    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="", flush=True)
            current_text += event.data.delta

            # Check if it's time to run the guardrail check
            # Note that we don't run the guardrail check if there's already a task running. An
            # alternate implementation is to have N guardrails running, or cancel the previous
            # one.
            if len(current_text) >= next_guardrail_check_len and not guardrail_task:
                print("Running guardrail check")
                guardrail_task = asyncio.create_task(check_guardrail(current_text))
                next_guardrail_check_len += 300

        # Every iteration of the loop, check if the guardrail has been triggered
        if guardrail_task and guardrail_task.done():
            guardrail_result = guardrail_task.result()
            if not guardrail_result.is_readable_by_ten_year_old:
                print("\n\n================\n\n")
                print(f"Guardrail triggered. Reasoning:\n{guardrail_result.reasoning}")
                break

ループを抜けた後に最終テキスト全体をもう一度検査する「最終チェック」も入っており、途中検査をすり抜けた場合の保険になっています。

実行手順

1. リポジトリルートで以下を実行します（質問はコード内に固定されており、対話入力は不要です）。

   uv run python -m examples.agent_patterns.streaming_guardrails

期待される動作・出力例

ブラックホールについての専門的な長文がストリーミング表示され、途中で Running guardrail check が挟まり、検査が「10 歳児には難しい」と判定した時点で打ち切られます。

A black hole is a region of spacetime where gravity is so intense that ...（長文が流れる）
Running guardrail check
...（続きが流れる）

================

Guardrail triggered. Reasoning:
The response uses technical terms like "spacetime curvature" and "event horizon" that ...

つまずきポイント

• 検査は非同期に走るため、「問題を検知した瞬間」までに数百文字が既に表示されています。ゼロ露出が必要なら、表示前にバッファして検査を通過した分だけ画面に出す、より保守的な設計が必要です。
• しきい値（300 文字）と検査の並行数は品質とコストのトレードオフです。コメントにあるとおり、複数検査を並行させる・古い検査をキャンセルするなどの変種が考えられます。

forcing_tool_use.py — ツール使用の強制

LLM は「ツールを使うかどうか」を自分で判断しますが、天気 API のように必ずツールを使ってほしい場合があります。この example は ModelSettings(tool_choice="required") でツール使用を強制し、その後の挙動を tool_use_behavior で 3 通りに制御する方法を示します。

いつ使うべきか: 「LLM がツールを使わず記憶で答えてしまう」事故を防ぎたいとき、およびツールの結果をそのまま最終出力にして LLM の再呼び出しを省略（高速化・コスト削減）したいときに使います。

コード解説

ファイル冒頭のコメントが 3 つのモードを説明しています。

"""
This example shows how to force the agent to use a tool. It uses `ModelSettings(tool_choice="required")`
to force the agent to use any tool.

You can run it with 3 options:
1. `default`: The default behavior, which is to send the tool output to the LLM. In this case,
    `tool_choice` is not set, because otherwise it would result in an infinite loop - the LLM would
    call the tool, the tool would run and send the results to the LLM, and that would repeat
    (because the model is forced to use a tool every time.)
2. `first_tool_result`: The first tool result is used as the final output.
3. `custom`: A custom tool use behavior function is used. The custom function receives all the tool
    results, and chooses to use the first tool result to generate the final output.
"""

ツールは天気を返すだけの単純なものです。カスタム動作関数は、全ツール結果のリストを受け取り、最終出力にするかどうかを ToolsToFinalOutputResult で返します。

@tool
def get_weather(city: str) -> Weather:
    print("[debug] get_weather called")
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind")


async def custom_tool_use_behavior(
    context: RunContextWrapper[Any], results: list[FunctionToolResult]
) -> ToolsToFinalOutputResult:
    weather: Weather = results[0].output
    return ToolsToFinalOutputResult(
        is_final_output=True, final_output=f"{weather.city} is {weather.conditions}."
    )

エージェントの組み立てでは、モードに応じて tool_use_behavior と tool_choice を切り替えます。

    agent = Agent(
        name="Weather agent",
        instructions="You are a helpful agent.",
        tools=[get_weather],
        tool_use_behavior=behavior,
        model_settings=ModelSettings(
            tool_choice="required" if tool_use_behavior != "default" else None
        ),
    )

tool_use_behavior の意味（ソースコード src/agents/agent.py の定義より）は次のとおりです。

• "run_llm_again"（既定）: ツール実行後、結果を LLM に渡してもう一度応答を生成させる
• "stop_on_first_tool": 最初のツール呼び出しの出力をそのまま最終結果とし、LLM には戻さない
• 関数を渡す: 実行コンテキストとツール結果のリストを受け取り、ToolsToFinalOutputResult で「最終出力にするか、LLM に続けさせるか」を自分で決める
• このほか StopAtTools（指定した名前のツールが呼ばれたら停止する辞書型設定）も指定できます

tool_choice="required" と既定の "run_llm_again" を組み合わせると、「毎ターンツール使用を強制 → 結果を LLM へ → また強制…」の無限ループになり得る、というコメントの警告は重要です。実際には SDK に reset_tool_choice（ツール実行後に tool_choice を既定へ戻す設定。既定で有効）という安全装置がありますが、強制と再呼び出しの組み合わせには常に注意が必要です。

実行手順

1. リポジトリルートで、3 つのモードをそれぞれ試します。

   uv run python -m examples.agent_patterns.forcing_tool_use -t default
   uv run python -m examples.agent_patterns.forcing_tool_use -t first_tool
   uv run python -m examples.agent_patterns.forcing_tool_use -t custom

期待される動作・出力例

# -t default: ツール結果を LLM が文章化する
[debug] get_weather called
The weather in Tokyo is sunny with wind, with temperatures ranging from 14 to 20°C.

# -t first_tool: ツールの生の戻り値（Weather オブジェクト）がそのまま最終出力になる
[debug] get_weather called
city='Tokyo' temperature_range='14-20C' conditions='Sunny with wind'

# -t custom: カスタム関数が整形した文字列が最終出力になる
[debug] get_weather called
Tokyo is Sunny with wind.

つまずきポイント

• stop_on_first_tool では LLM による文章化が入らないため、ツールの戻り値の型・体裁がそのままユーザーへの出力になります。表示用の整形が必要ならカスタム関数方式を選びます。
• tool_use_behavior の設定が効くのは自作の関数ツール（FunctionTool）だけで、Web 検索などのホスト型ツールの結果は常に LLM が処理します（ソースコードの NOTE より）。

human_in_the_loop.py — 人間の承認（HITL）の基本

エージェントが特定のツールを呼ぼうとしたら実行を一時停止し、人間が承認（approve）または拒否（reject）してから再開する human-in-the-loop の基本形です。実行状態（RunState）を JSON ファイルに保存・復元するデモも兼ねています。

いつ使うべきか: 送金、データ削除、メール送信、本番環境への変更など、「間違えたら取り返しがつかない操作」の前に必ず人間の目を入れたいときに使います。

コード解説

承認要否はツール定義時に needs_approval で宣言します。True 固定のほか、引数の内容を見て動的に判断する関数も渡せます。

async def _needs_temperature_approval(_ctx, params, _call_id) -> bool:
    """Check if temperature tool needs approval."""
    return "Oakland" in params.get("city", "")


@tool(
    # Dynamic approval: only require approval for Oakland
    needs_approval=_needs_temperature_approval
)
async def get_temperature(city: str) -> str:
    ...

この例では「都市名に Oakland が含まれるときだけ承認が必要」です。判定関数はコンテキスト・解析済みパラメータ・ツール呼び出し ID の 3 つを受け取ります。

承認フローの本体は「interruptions（割り込み）を確認 → 状態を保存/復元 → 承認/拒否 → 再開」のループです。

    result = await Runner.run(
        agent,
        "What is the weather and temperature in Oakland?",
    )

    has_interruptions = len(result.interruptions) > 0

    while has_interruptions:
        ...
        # Storing state to file (demonstrating serialization)
        state = result.to_state()
        state_json = state.to_json()
        RESULT_PATH.parent.mkdir(parents=True, exist_ok=True)
        with RESULT_PATH.open("w") as f:
            json.dump(state_json, f, indent=2)
        ...
        state = await RunState.from_json(agent, stored_state_json)

        # Process each interruption
        for interruption in result.interruptions:
            print("\nTool call details:")
            print(f"  Agent: {interruption.agent.name}")
            print(f"  Tool: {interruption.name}")
            print(f"  Arguments: {interruption.arguments}")

            confirmed = await confirm("\nDo you approve this tool call?")

            if confirmed:
                print(f"✓ Approved: {interruption.name}")
                state.approve(interruption)
            else:
                print(f"✗ Rejected: {interruption.name}")
                state.reject(interruption)

        # Resume execution with the updated state
        print("\nResuming agent execution...")
        result = await Runner.run(agent, state)
        has_interruptions = len(result.interruptions) > 0

流れを整理すると次のとおりです。

1. 承認が必要なツール呼び出しが発生すると、実行が一時停止し result.interruptions に ToolApprovalItem（エージェント名・ツール名・引数を持つ承認要求）が入る
2. result.to_state() で実行状態を RunState に変換し、to_json() でシリアライズ（オブジェクトを保存可能なデータ形式に変換すること）できる。つまり承認待ちのままプロセスを終了し、別プロセス・別サーバーで後から再開することも可能
3. RunState.from_json(agent, ...) で復元し、state.approve(...) / state.reject(...) で決定を記録する
4. Runner.run(agent, state) に入力の代わりに state を渡すと、続きから実行が再開される。新たな承認要求が出ればまたループする

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.human_in_the_loop

2. Do you approve this tool call? (y/n): と聞かれたら y（承認）または n（拒否）を入力します。
3. 実行後、.cache/agent_patterns/human_in_the_loop/result.json に保存された実行状態を覗いてみると、何が永続化されるのか理解が深まります。

期待される動作・出力例

================================================================================
Run interrupted - tool approval required
================================================================================
State saved to .cache/agent_patterns/human_in_the_loop/result.json
Loading state from .cache/agent_patterns/human_in_the_loop/result.json

Tool call details:
  Agent: Weather Assistant
  Tool: get_temperature
  Arguments: {"city":"Oakland"}

Do you approve this tool call? (y/n): y
✓ Approved: get_temperature

Resuming agent execution...

================================================================================
Final Output:
================================================================================
The weather in Oakland is sunny and the temperature is 20° Celsius.

n で拒否した場合は、エージェントが「気温の取得は承認されなかった」ことを踏まえた回答（天気のみの回答など）を生成します。

つまずきポイント

• get_weather には needs_approval が付いていないため、承認なしで即実行されます。止まるのは Oakland 宛の get_temperature だけです。
• 再開時の Runner.run に渡すのは「新しい入力」ではなく state です。ここで元の質問文字列をもう一度渡すと、続きではなく新規実行になってしまいます。

中断から再開までの一連のやり取りを、アプリコード・Runner・人間の3者間のシーケンス図として整理すると次のとおりです。

human_in_the_loop_stream.py — ストリーミング版 HITL

human_in_the_loop.py と同じ承認フローを、Runner.run_streamed によるストリーミング実行で行う example です。

いつ使うべきか: チャット UI などリアルタイム表示のアプリに承認フローを組み込むときの雛形です。

コード解説

ツール定義（Oakland のみ承認必須の get_temperature と承認不要の get_weather）は基本版と同じです。違いは実行と再開の両方がストリーミングである点です。

    # Run the agent with streaming
    result = Runner.run_streamed(
        main_agent,
        "What is the weather and temperature in Oakland?",
    )
    async for _ in result.stream_events():
        pass  # Process streaming events silently or could print them

    # Handle interruptions
    while len(result.interruptions) > 0:
        ...
        state = result.to_state()

        for interruption in result.interruptions:
            ...
            if confirmed:
                state.approve(interruption)
            else:
                state.reject(interruption)

        # Resume execution with streaming
        print("\nResuming agent execution...")
        result = Runner.run_streamed(main_agent, state)
        async for _ in result.stream_events():
            pass  # Process streaming events silently or could print them

重要なのは、stream_events() を最後まで消費し切ってから result.interruptions を確認するという順序です（公式ドキュメント docs/human_in_the_loop.md にも明記されています）。ストリームの途中では承認要求がまだ確定していません。この example ではイベントを pass で読み捨てていますが、実アプリではここで delta を画面表示します。再開も Runner.run_streamed(main_agent, state) で行い、再開後の出力もストリーミングされます。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.human_in_the_loop_stream

2. 承認を求められたら y または n を入力します。

期待される動作・出力例

基本版とほぼ同じ出力になります（この example はイベントを表示しないため、見た目上の違いは小さいです）。

================================================================================
Human-in-the-loop: approval required for the following tool calls:
================================================================================

Tool call details:
  Agent: Weather Assistant
  Tool: get_temperature
  Arguments: {"city":"Oakland"}

Do you approve this tool call? (y/n): y
✓ Approved: get_temperature

Resuming agent execution...

================================================================================
Final Output:
================================================================================
The weather in Oakland is sunny and the temperature is 20°C.

Done!

つまずきポイント

• stream_events() の消費を忘れる（async for を書かない）と、実行が完了せず interruptions も正しく取得できません。ストリーミング版では「ストリームを飲み干す → interruptions を見る → 再開」の 3 拍子を崩さないでください。

human_in_the_loop_custom_rejection.py — 拒否メッセージのカスタマイズ

承認を拒否したとき、LLM には既定で「Tool execution was not approved.」という定型文が渡ります。この example は、その文言を（1）実行全体のフォールバックとして RunConfig.tool_error_formatter で、（2）個別の拒否として state.reject(..., rejection_message=...) で、2 層でカスタマイズする方法を示します。

いつ使うべきか: 拒否理由をエージェントの次の応答に正確に反映させたいとき（「レビュー担当者が否認した」等、業務上の文脈を伝えたいとき）に使います。

コード解説

まず実行全体のフォールバックとなるフォーマッタ関数です。args.kind で「承認拒否」のケースだけを対象にし、それ以外は None を返して既定動作に任せます。

async def tool_error_formatter(args: ToolErrorFormatterArgs[None]) -> str | None:
    """Build the universal fallback output message for rejected tool calls."""
    if args.kind != "approval_rejected":
        return None
    # The default message is "Tool execution was not approved."
    return "Publish action was canceled because approval was rejected."

エージェントは「お知らせを公開する」ツールを必ず呼ぶよう、tool_choice にツール名そのものを指定しています（"required" が「どれかのツールを必ず使え」なのに対し、ツール名指定は「このツールを必ず使え」です）。

@tool(needs_approval=True)
async def publish_announcement(title: str, body: str) -> str:
    """Simulate publishing an announcement to users."""
    return f"Published announcement '{title}' with body: {body}"

    agent = Agent(
        name="Operations Assistant",
        instructions=(
            "When a user asks to publish an announcement, call the publish_announcement tool directly. "
            "Do not ask the user for approval in plain text; runtime approvals handle that. "
            "If the tool call is rejected, respond with the exact rejection message and nothing else."
        ),
        model_settings=ModelSettings(tool_choice="publish_announcement"),
        tools=[publish_announcement],
    )
    run_config = RunConfig(tool_error_formatter=tool_error_formatter)

拒否時には、フォーマッタより優先される呼び出し単位の rejection_message を渡します。

            if approved:
                state.approve(interruption)
            else:
                # This per-call rejection message takes precedence over ``tool_error_formatter``.
                state.reject(
                    interruption,
                    rejection_message=(
                        "Publish action was canceled because the reviewer denied approval."
                    ),
                )

        result = await Runner.run(agent, state, run_config=run_config)

優先順位は「state.reject の rejection_message（個別）＞ RunConfig.tool_error_formatter（全体フォールバック）＞ SDK 既定文」です。実行の最後には、ツール呼び出し結果アイテム（tool_call_output_item）から実際に LLM へ渡った文言を取り出して表示します。

実行手順

1. リポジトリルートで以下を実行します。

   uv run python -m examples.agent_patterns.human_in_the_loop_custom_rejection

2. Approve this tool call? [y/N]: に対して n（または Enter のみ。既定は拒否）を入力すると、カスタム拒否メッセージの効果を確認できます。

期待される動作・出力例

拒否した場合の例です。

Approval required:
- Tool: publish_announcement
  Arguments: {"title":"Office maintenance","body":"The office will close at 6 PM today."}
Approve this tool call? [y/N]: n

Formatter output:
Publish action was canceled because the reviewer denied approval.

Final output:
Publish action was canceled because the reviewer denied approval.

y で承認すると、ツールが実行されて公開完了のメッセージが最終出力になります。

つまずきポイント

• この example の確認プロンプトは既定が拒否（default=False）です。他の HITL example（既定が承認）と逆なので、Enter 連打での挙動が異なります。
• instructions で「拒否されたら拒否メッセージだけをそのまま返せ」と指示しているため最終出力が拒否文と一致しますが、この指示がない場合、LLM は拒否メッセージを踏まえた自由な文章で応答します。

hosted_multi_agent_beta.py — OpenAI ホスト型マルチエージェント（実験的）

v0.18.2 で追加された example です。 これまでの節はすべて「あなたのプロセスが複数のエージェントを組み立てて動かす」設計でしたが、この example は サブエージェントの生成と統括を OpenAI のサーバー側に任せるという別方式（hosted multi-agent ベータ）を扱います。ルートのモデルがサーバー上でサブエージェントを作り、それらを並行に走らせ、結果をまとめます。あなたのアプリケーションはサブエージェントを作りもスケジュールもしません。

一方で、開発者が定義した function tool は従来どおりあなたの手元で実行されます。サーバー側のサブエージェントが「このツールを呼びたい」と言うと、SDK の通常の Runner がローカルで関数を実行し、同じ call ID の function_call_output を WebSocket 上の実行中レスポンスへ注入（inject）して、呼び出し元のホスト型エージェントを再開させます。「統括はサーバー、ツール実行は手元」という役割分担です。

コード解説

エージェントの model に専用のモデルクラスを渡すだけで有効になります。

from agents.extensions.experimental.hosted_multi_agent import (
    OpenAIHostedMultiAgentModel,
    get_hosted_agent_metadata,
)


def build_agent() -> Agent[Any]:
    return Agent(
        name="Hosted proposal coordinator",
        instructions=(
            "Create two subagents. Ask one to inspect proposal alpha and the other to inspect "
            "proposal beta. Each subagent must call get_proposal for its assigned proposal. "
            "Wait for both results, then return one concise comparison from the root agent."
        ),
        model=OpenAIHostedMultiAgentModel(
            model="gpt-5.6-sol",
            config={"max_concurrent_subagents": 3},
        ),
        tools=[get_proposal],
    )

• OpenAIHostedMultiAgentModel を構築すると multi_agent.enabled が有効になり、OpenAI-Beta: responses_multi_agent=v1 というヘッダーが WebSocket に送られます。max_concurrent_subagents を省略するとサービス側の既定値が使われます
• instructions は「サブエージェントを 2 つ作れ」「それぞれに alpha / beta を見させろ」「両方の結果を待ってからルートエージェントが 1 つの比較を返せ」と、サブエージェントの編成そのものを日本語ならぬ自然言語で指示している点に注目してください。編成表がコードではなくプロンプトに書かれるのが、この方式の最大の特徴です

ツール側は get_hosted_agent_metadata() で「どのホスト型エージェントから呼ばれたか」を知ることができます。

@tool
def get_proposal(ctx: ToolContext[Any], proposal: str) -> dict[str, object]:
    """Return deterministic details for one proposal."""
    metadata = get_hosted_agent_metadata(ctx)
    caller = metadata.agent_name if metadata else "unknown"
    print(f"local tool caller={caller} call_id={ctx.tool_call_id} proposal={proposal}")
    if proposal not in PROPOSALS:
        raise ValueError(f"Unknown proposal: {proposal}")
    return PROPOSALS[proposal]

• 第 1 引数に ToolContext を取ると、SDK が実行文脈を渡してくれます。get_hosted_agent_metadata(ctx) が返す agent_name が呼び出し元のホスト型エージェント名です（ルートは /root）
• ホスト型エージェント名は観測用のメタデータであって、ローカルのルーティング機構ではありません。 出力の振り分けには SDK が渡す call ID を使ってください。副作用のあるツールでは、その call ID を冪等キーとして使い、必要な認可はアプリケーション側で実装します

ストリーミング時は、ホスト型のアイテムを raw イベントから拾えます。

def log_hosted_event(event: object) -> None:
    if getattr(event, "type", None) != "response.output_item.done":
        return
    item = getattr(event, "item", None)
    item_type = item.get("type") if isinstance(item, Mapping) else getattr(item, "type", None)
    metadata = get_hosted_agent_metadata(item)
    is_hosted_item = item_type in {
        "agent_message",
        "multi_agent_call",
        "multi_agent_call_output",
    }

• agent_message / multi_agent_call / multi_agent_call_output がホスト型オーケストレーションの記録です
• 最終出力になるのは、/root に帰属し phase が final_answer のメッセージだけです。サブエージェントのメッセージとオーケストレーション記録は高レベルの RunResult からは除外されます（SDK がそれらをローカル関数として実行することもありません）

実行手順

1. OPENAI_API_KEY が設定されていることを確認します。

2. 非ストリーミング版は次のコマンドです。

   uv run -m examples.agent_patterns.hosted_multi_agent_beta

3. ストリーミング版は --mode stream を付けます。

   uv run -m examples.agent_patterns.hosted_multi_agent_beta --mode stream

期待される動作・出力例

local tool caller=... call_id=... proposal=alpha のようなログが 2 回（alpha / beta）出て、最後に Final response: として 2 案の比較が表示されます。ストリーミング版では加えて hosted item type=multi_agent_call agent=/root のような、サーバー側オーケストレーションの実況が流れます。

つまずきポイント

• 実験的機能です。 インターフェースとベータのアイテムスキーマは一般提供までに変わり得ます。client.beta.responses.connect を公開する openai[realtime] 2.45.0 以降のビルドが必要で、通信は Responses の WebSocket トランスポートを使います（ローカル関数の出力を response.inject で実行中のホスト型エージェントへ返すため）
• SDK の handoff とは併用できません。 すべてのホスト型エージェントが同じ handoff ツールを受け取ってしまい所有権が衝突するため、handoff を渡すと UserError で弾かれます。agents-as-tools は使えますが、クライアント側とサーバー側の入れ子オーケストレーションになるので、レイテンシ・コスト・ツール露出を意識して選んでください
• ツール承認（approval）は使えません。 needs_approval が False 以外の function tool は、リクエスト送信前に拒否されます。認可が要るなら、承認機構ではなくアプリケーションコード側で実装してください
• 現状の制限として、reasoning.summary・max_tool_calls・呼び出し側からの multi_agent / betas の上書きは拒否されます。Responses の /compact エンドポイントも未対応です（ただしサービスが各ホスト型エージェントの文脈を独立に自動圧縮するため、明示的な context_management.compact_threshold は使えます）
• ツールの引数と出力は Responses API の境界を越えて流れます。機密データを扱うツールでは、この点を踏まえて設計してください

「統括はサーバー、ツール実行は手元」という役割分担を図にすると次のとおりです。

まとめ

• マルチエージェント設計には「コードで制御」と「LLM に判断させる」の 2 軸があり、手順が固定なら決定的フロー、統合責任を 1 エージェントに置くなら agents as tools、会話ごと専門家に渡すなら handoff が基本の選び分けです
• Agent.as_tool() はエージェントを関数ツール化する仕組みで、is_enabled（条件付き有効化）、on_stream（内部イベント観測）、parameters（構造化入力）、needs_approval（承認必須化）などのオプションで実運用の要件に対応できます
• 並列実行は asyncio.gather だけで実現でき、速度向上のほか「複数案生成 + LLM as a judge による選定・改善ループ」で品質を高める用途にも使えます
• guardrail は入力用（最初のエージェントで実行、コスト防御が主目的）と出力用（最後のエージェントで実行、漏えい防止が主目的）があり、tripwire が作動すると例外で実行が止まります。ストリーミング中の途中検査は自前実装のパターンで補います
• ModelSettings(tool_choice="required") と tool_use_behavior の組み合わせで「必ずツールを使う」「ツール結果を最終出力にして LLM 再呼び出しを省く」といった制御ができます
• needs_approval を付けたツールは実行前に停止して interruptions に承認要求が現れ、to_state() → approve/reject → Runner.run(agent, state) で再開します。RunState は JSON にシリアライズでき、承認待ちを別プロセスに持ち越せます
• OpenAIHostedMultiAgentModel（実験的、v0.18.2 で example 追加）を使うと、サブエージェントの生成・並行実行・統括を OpenAI のサーバー側が担い、function tool だけが手元で実行されます。編成をコードではなくプロンプトで指示する方式で、SDK handoff とは併用できず、ツール承認も使えません

理解度チェック

• (a) handoff は会話履歴を渡さないが、agents as tools は渡す
• (b) handoff では委譲先が会話の主導権を持つが、agents as tools では元のエージェントが会話を続ける
• (c) agents as tools は 1 つのエージェントしか呼べない
• (d) 両者は内部的に同じ動作で、名前が違うだけである

解答と解説

参考リンク

• エージェントのオーケストレーション（英語）: https://openai.github.io/openai-agents-python/multi_agent/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/multi_agent/
• ガードレール（英語）: https://openai.github.io/openai-agents-python/guardrails/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/guardrails/
• Human-in-the-loop（英語）: https://openai.github.io/openai-agents-python/human_in_the_loop/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/human_in_the_loop/
• ツール（Agent.as_tool() を含む）（英語）: https://openai.github.io/openai-agents-python/tools/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/tools/
• エージェントの実行と結果（英語）: https://openai.github.io/openai-agents-python/running_agents/ ・ https://openai.github.io/openai-agents-python/results/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/running_agents/ ・ https://openai.github.io/openai-agents-python/ja/results/
• コード例一覧（英語）: https://openai.github.io/openai-agents-python/examples/ ／（日本語）: https://openai.github.io/openai-agents-python/ja/examples/

第5章 ハンドオフ（handoffs）

前提知識

この章を読む前に、以下を理解していることを前提とします。

• 第1章: リポジトリのクローンと uv sync によるセットアップ、OPENAI_API_KEY の設定
• 第2章: Agent と Runner.run() の基本、実行結果（RunResult）から to_input_list() で会話履歴を取り出して次の実行につなげる方法
• 第3章: @tool（別名 @function_tool）デコレータによるツール（LLM が呼び出せる関数）の定義
• 第4章: agents-as-tools パターン（エージェントをツールとして別のエージェントから呼び出す設計）。この章で handoff との違いを比較します

概念解説

handoff とは何か — 「電話窓口の転送」の比喩

handoff（ハンドオフ）とは、あるエージェントが会話の主導権ごと別のエージェントに引き継ぐ仕組みです。

コールセンターに電話をかけた場面を想像してください。最初に応対するのは総合受付のオペレーターです。あなたが「返金について相談したい」と言うと、受付は「返金担当におつなぎします」と言って電話を転送します。転送された後は、返金担当者があなたと直接会話を続けます。総合受付はもう会話に参加しません。そして重要なのは、転送先の担当者がそれまでの会話内容（あなたの名前や要件）を引き継いだ状態で応対を始めることです。

これがまさに handoff です。SDK の世界では、

• 総合受付 = 振り分け役のエージェント（triage agent、トリアージエージェントとも呼びます）
• 返金担当 = 専門エージェント
• 電話の転送 = handoff
• 「それまでの会話内容」= 会話履歴（これまでのユーザー発言と AI 応答の記録）

に対応します。カスタマーサポートアプリなら、注文状況・返金・FAQ をそれぞれ専門に扱うエージェントを用意し、受付エージェントが適切な担当へ handoff する、という構成が典型例です。

handoff は LLM からは「ツール」として見える

handoff は、LLM（大規模言語モデル。ChatGPT の中身のような文章生成 AI）に対してはツールとして表現されます。たとえば Refund Agent という名前のエージェントへの handoff があると、LLM には transfer_to_refund_agent という名前のツールが見えます。LLM が「この会話は返金担当に任せるべきだ」と判断してこのツールを呼び出すと、SDK が実際の引き継ぎ処理を実行します。

つまり「誰に引き継ぐかの判断」は LLM が行い、「引き継ぎの実務（履歴の受け渡しや実行エージェントの切り替え）」は SDK が行う、という役割分担です。

handoff の作り方

すべての Agent には handoffs パラメータがあり、引き継ぎ先を 2 通りの書き方で指定できます。公式ドキュメント（docs/handoffs.md）の例を引用します。

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])

• billing_agent のように Agent をそのまま渡す: 最も簡単な方法です。エージェントに handoff_description（引き継ぎ先としての説明文）を設定しておくと、その内容がツールの説明に追記され、LLM が「いつこの引き継ぎ先を選ぶべきか」を判断しやすくなります
• handoff(refund_agent) のように handoff() 関数でラップして渡す: 挙動を細かくカスタマイズしたいときに使います

handoff() 関数でカスタマイズできること

handoff() 関数には以下のオプションがあります（公式ドキュメントより）。

on_handoff と input_type を組み合わせると、LLM に引き継ぎ時のメタデータを生成させられます。公式ドキュメントの例です。

from pydantic import BaseModel

from agents import Agent, handoff, RunContextWrapper

class EscalationData(BaseModel):
    reason: str

async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
    print(f"Escalation agent called with reason: {input_data.reason}")

agent = Agent(name="Escalation agent")

handoff_obj = handoff(
    agent=agent,
    on_handoff=on_handoff,
    input_type=EscalationData,
)

エスカレーション（上位担当への引き上げ）用エージェントに引き継ぐ際、LLM に「理由（reason）」を出力させ、ログに残す、という使い方です。注意点として、input_type はあくまで handoff というツール呼び出しの引数であって、引き継ぎ先エージェントへの入力（会話履歴）を置き換えるものではありません。履歴を変えたい場合は次に説明する input_filter を使います。

input filter — 引き継ぐ会話履歴を加工する

handoff が発生すると、新しいエージェントが会話を丸ごと引き継ぎ、それまでの会話履歴全体を見られる状態になります。これがデフォルトの挙動です。

しかし、履歴をそのまま渡したくない場合もあります。たとえば、

• 前のエージェントが使ったツールの呼び出し記録は、引き継ぎ先には無関係なノイズなので消したい
• 履歴が長すぎるので古い部分を削って、LLM に渡すトークン（LLM が文章を処理する際の最小単位。課金や入力上限の単位でもあります）を節約したい
• 個人情報を含む発言を引き継ぎ先に見せたくない

こうしたときに使うのが input filter です。input filter は HandoffInputData を受け取り、加工した新しい HandoffInputData を返す関数です。

HandoffInputData には以下が含まれます（SDK ソース src/agents/handoffs/__init__.py の定義に基づく）。

HandoffInputData には clone(**kwargs) メソッドがあり、一部のフィールドだけ差し替えたコピーを簡単に作れます。

よくある加工パターンはあらかじめ agents.extensions.handoff_filters に実装されています。代表が remove_all_tools で、履歴からツール関連の項目（関数呼び出しとその結果、Web 検索・ファイル検索の記録など）をすべて取り除きます。

from agents import Agent, handoff
from agents.extensions import handoff_filters

agent = Agent(name="FAQ agent")

handoff_obj = handoff(
    agent=agent,
    input_filter=handoff_filters.remove_all_tools,
)

なお、handoff とその実行全体の設定 RunConfig.handoff_input_filter の両方にフィルターが定義されている場合は、handoff 個別の input_filter が優先されます。

推奨プロンプト

LLM に handoff を正しく理解させるため、SDK は推奨のプロンプト接頭辞を提供しています。agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX を instructions の先頭に付けるか、prompt_with_handoff_instructions() 関数で自動付与します。

from agents import Agent
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

billing_agent = Agent(
    name="Billing agent",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    <Fill in the rest of your prompt here>.""",
)

この接頭辞には「あなたはマルチエージェントシステムの一部であり、transfer_to_<agent_name> という関数で会話を引き継げる。引き継ぎのことをユーザーとの会話で話題にしないこと」といった内容が含まれています。

handoff と agents-as-tools の使い分け

第4章で学んだ agents-as-tools（Agent.as_tool() でエージェントをツール化して呼び出すパターン）と handoff は、どちらも「エージェントが別のエージェントに仕事を任せる」仕組みですが、性質が大きく異なります。

比喩で言えば、handoff は「電話の転送」、agents-as-tools は「部下への調べ物の依頼」です。転送すれば以後は転送先が話し相手になりますが、調べ物の依頼では依頼した本人が回答を受け取り、自分の言葉でユーザーに答えます。

補足として、handoff は 1 回の実行（run）の内部で完結します。入力ガードレール（不正な入力をブロックする安全チェック。別章で詳しく扱います）は連鎖の最初のエージェントにのみ適用され、出力ガードレールは最終出力を生成したエージェントにのみ適用される点も覚えておいてください。

各 example の解説

examples/handoffs ディレクトリには 2 つのファイルがあります。どちらも「input filter で会話履歴を加工してから handoff する」流れを示すもので、2 つ目はストリーミング実行版です。

message_filter.py

英語のアシスタントからスペイン語専門アシスタントへ handoff する際に、input filter で「ツール呼び出しの記録」と「履歴の先頭 2 件」を削除して引き継ぐ example です。フィルターが実際に効いたことを、最終的な会話履歴を出力して確認します。

コード解説

まず import とツール定義です。

from __future__ import annotations

import json
import random

from agents import (
    Agent,
    HandoffInputData,
    Runner,
    handoff,
    trace,
)
from agents.decorators import tool
from agents.extensions import handoff_filters
from agents.models import is_gpt_5_default


@tool
def random_number_tool(max: int) -> int:
    """Return a random integer between 0 and the given maximum."""
    return random.randint(0, max)

random_number_tool は乱数を返すだけの単純なツールです。これは「履歴にツール呼び出しの記録を残す」ために用意されています。後でフィルターがこの記録を削除する様子を観察します。

次が本章の主役、input filter 関数です。

def spanish_handoff_message_filter(handoff_message_data: HandoffInputData) -> HandoffInputData:
    if is_gpt_5_default():
        print("gpt-5 is enabled, so we're not filtering the input history")
        # when using gpt-5, removing some of the items could break things, so we do this filtering only for other models
        return HandoffInputData(
            input_history=handoff_message_data.input_history,
            pre_handoff_items=tuple(handoff_message_data.pre_handoff_items),
            new_items=tuple(handoff_message_data.new_items),
        )

    # First, we'll remove any tool-related messages from the message history
    handoff_message_data = handoff_filters.remove_all_tools(handoff_message_data)

    # Second, we'll also remove the first two items from the history, just for demonstration
    history = (
        tuple(handoff_message_data.input_history[2:])
        if isinstance(handoff_message_data.input_history, tuple)
        else handoff_message_data.input_history
    )

    # or, you can use the HandoffInputData.clone(kwargs) method
    return HandoffInputData(
        input_history=history,
        pre_handoff_items=tuple(handoff_message_data.pre_handoff_items),
        new_items=tuple(handoff_message_data.new_items),
    )

ポイントを順に見ます。

• is_gpt_5_default() の分岐: デフォルトモデルが GPT-5 系のとき、履歴の一部項目（推論の記録など）を削除するとモデル呼び出しが壊れる可能性があるため、フィルタリングをスキップしてそのまま返します。この関数はデフォルトモデル名（環境変数 OPENAI_DEFAULT_MODEL、未設定なら SDK 組み込みの既定値）が GPT-5 系かどうかを判定します
• handoff_filters.remove_all_tools(...): SDK 既製のフィルターで、input_history・pre_handoff_items・new_items からツール関連の項目（関数呼び出し・関数結果・handoff 呼び出しの記録など）をすべて除去した新しい HandoffInputData を返します
• 先頭 2 件の削除: input_history[2:] で履歴の最初の 2 項目（最初のユーザー発言とアシスタント応答）をデモとして切り落とします。input_history は文字列の場合もあるため、タプルのときだけスライスしています
• 戻り値: 加工済みの HandoffInputData を組み立てて返します。コメントにあるとおり、handoff_message_data.clone(input_history=history) と書いても同じことができます

続いてエージェントの定義です。

first_agent = Agent(
    name="Assistant",
    instructions="Be extremely concise.",
    tools=[random_number_tool],
)

spanish_agent = Agent(
    name="Spanish Assistant",
    instructions="You only speak Spanish and are extremely concise.",
    handoff_description="A Spanish-speaking assistant.",
)

second_agent = Agent(
    name="Assistant",
    instructions=(
        "Be a helpful assistant. If the user speaks Spanish, handoff to the Spanish assistant."
    ),
    handoffs=[handoff(spanish_agent, input_filter=spanish_handoff_message_filter)],
)

• first_agent: 乱数ツールを持つアシスタント。履歴の「前半」を作る役です
• spanish_agent: スペイン語しか話さない専門エージェント。handoff_description により、LLM に見えるツール説明へ「スペイン語話者向けアシスタント」という補足が付きます
• second_agent: ユーザーがスペイン語を話したら handoff するよう指示されたエージェント。handoff(spanish_agent, input_filter=spanish_handoff_message_filter) により、この handoff が発動した瞬間に先ほどのフィルターが呼ばれます

最後に main 関数です。会話を 4 ステップに分けて積み上げていきます。

async def main():
    # Trace the entire run as a single workflow
    with trace(workflow_name="Message filtering"):
        # 1. Send a regular message to the first agent
        result = await Runner.run(first_agent, input="Hi, my name is Sora.")

        print("Step 1 done")

        # 2. Ask it to generate a number
        result = await Runner.run(
            first_agent,
            input=result.to_input_list()
            + [{"content": "Can you generate a random number between 0 and 100?", "role": "user"}],
        )

        print("Step 2 done")

        # 3. Call the second agent
        result = await Runner.run(
            second_agent,
            input=result.to_input_list()
            + [
                {
                    "content": "I live in New York City. Whats the population of the city?",
                    "role": "user",
                }
            ],
        )

        print("Step 3 done")

        # 4. Cause a handoff to occur
        result = await Runner.run(
            second_agent,
            input=result.to_input_list()
            + [
                {
                    "content": "Por favor habla en español. ¿Cuál es mi nombre y dónde vivo?",
                    "role": "user",
                }
            ],
        )

        print("Step 4 done")

• with trace(workflow_name="Message filtering"): トレーシング（実行の記録を OpenAI のダッシュボードで可視化する仕組み）のブロックです。複数回の Runner.run() を 1 つのワークフローとしてまとめて記録します
• ステップ 1〜2: first_agent に名前を名乗り（"my name is Sora"）、乱数生成を依頼します。result.to_input_list() は「これまでの入力＋生成された項目」を次の実行の入力リストに変換するメソッドで、これにより会話履歴が引き継がれます。ステップ 2 でツール呼び出しの記録が履歴に入ります
• ステップ 3: second_agent に切り替えて英語で質問します。英語なので handoff は起きません
• ステップ 4: スペイン語で「私の名前と住んでいる場所は？」と尋ねます。second_agent は指示に従い transfer_to_spanish_assistant ツールを呼び出し、handoff が発動 → spanish_handoff_message_filter が呼ばれ → 加工済み履歴を持った spanish_agent が応答を生成します

最後に、フィルターの効果を確認するために最終履歴を JSON（データ交換用のテキスト形式）で出力します。

    print("\n===Final messages===\n")

    # 5. That should have caused spanish_handoff_message_filter to be called, which means the
    # output should be missing the first two messages, and have no tool calls.
    # Let's print the messages to see what happened
    for message in result.to_input_list():
        print(json.dumps(message, indent=2))

実行手順

1. リポジトリのルートディレクトリ（openai-agents-python）にいることを確認します（第1章のとおり git clone と uv sync は完了している前提です）
2. OPENAI_API_KEY を設定します: export OPENAI_API_KEY=sk-...
3. フィルターの動作を観察したい場合は、デフォルトモデルを GPT-5 系以外に切り替えます（理由は後述の「つまずきポイント」参照）: export OPENAI_DEFAULT_MODEL=gpt-4.1
4. 実行します: uv run python examples/handoffs/message_filter.py

期待される動作・出力例

Step 1 done 〜 Step 4 done が順に表示された後、最終履歴が JSON で出力されます。ソースコード内のコメントに実行例が残されており、要点は次のとおりです。

• 履歴の先頭が「乱数を生成して」というユーザー発言から始まっている（最初の 2 件 —「Hi, my name is Sora.」とその応答 — がフィルターで削除された）
• 乱数ツールの呼び出し・結果の項目が存在しない（remove_all_tools の効果）
• 最後のスペイン語の質問に対し、スペイン語エージェントが「あなたの名前は分かりませんが、ニューヨークに住んでいると言っていましたね」という趣旨の応答を返す

{
  "content": "Por favor habla en español. ¿Cuál es mi nombre y dónde vivo?",
  "role": "user"
}
{
  ...
  "text": "No tengo acceso a esa información personal, solo sé lo que me has contado: vives en Nueva York.",
  ...
}

名前（Sora）を答えられないのは、名乗った発言がフィルターで履歴から消えたためです。一方、ニューヨーク在住であることは履歴に残っているので答えられます。「何を消したら何を忘れるか」が応答にそのまま表れる、input filter の効果が一目で分かる仕掛けです。

つまずきポイント

• デフォルト設定のままではフィルターが働きません。 この SDK バージョン（v0.22.2）のデフォルトモデル gpt-5.6-luna は GPT-5 系のため、is_gpt_5_default() が真になり、フィルター関数は冒頭で「gpt-5 is enabled, so we're not filtering the input history」と表示して履歴を無加工で返します。フィルタリングの動作を確認したいときは、環境変数 OPENAI_DEFAULT_MODEL に GPT-5 系以外のモデル（例: gpt-4.1）を設定してください
• 出力される名前や乱数、応答の文言は実行のたびに変わります。コメント内の実行例と完全一致しなくても正常です
• trace() でまとめた実行記録は、OpenAI ダッシュボードの Traces ページ（https://platform.openai.com/traces）で「Message filtering」というワークフロー名で確認できます。handoff の発生箇所やフィルター適用後の入力を視覚的に追えるので、ぜひ見てみてください

message_filter_streaming.py

message_filter.py とほぼ同じ内容を、最後の handoff 発生ステップだけストリーミング実行（応答を完成後にまとめて受け取るのではなく、生成されるそばから逐次受け取る実行方式）に変えた example です。input filter がストリーミングでも同じように機能することを確認します。

コード解説

ツール定義・フィルター関数・エージェント定義・ステップ 1〜3 は message_filter.py と同一です（トレース名だけ "Streaming message filter" に変わっています）。違いはステップ 4 と最終出力の部分だけなので、そこを引用します。

        # 4. Cause a handoff to occur
        stream_result = Runner.run_streamed(
            second_agent,
            input=result.to_input_list()
            + [
                {
                    "content": "Por favor habla en español. ¿Cuál es mi nombre y dónde vivo?",
                    "role": "user",
                }
            ],
        )
        async for _ in stream_result.stream_events():
            pass

        print("Step 4 done")

• Runner.run_streamed(...): Runner.run() の代わりに使うストリーミング版の実行メソッドです。戻り値はストリーミング結果オブジェクトで、await せずに受け取ります
• async for _ in stream_result.stream_events(): 非同期イテレーション（結果が届くたびに 1 件ずつ処理を進める書き方）でイベントを消費します。この example ではイベントの中身を使わないため _ で読み捨てていますが、実際のアプリではここで応答テキストの断片を画面に逐次表示する、といった処理を書きます。ストリームを最後まで消費しないと実行が完了しないため、読み捨てでもループは必須です

最終履歴の出力もストリーミング結果オブジェクトから行います。

    print("\n===Final messages===\n")

    # 5. That should have caused spanish_handoff_message_filter to be called, which means the
    # output should be missing the first two messages, and have no tool calls.
    # Let's print the messages to see what happened
    for item in stream_result.to_input_list():
        print(json.dumps(item, indent=2))

ストリーミング実行でも to_input_list() で会話履歴を取り出せる点は通常実行と同じです。

実行手順

1. リポジトリのルートディレクトリにいることを確認します
2. OPENAI_API_KEY を設定します: export OPENAI_API_KEY=sk-...
3. フィルターの動作を観察する場合はデフォルトモデルを切り替えます: export OPENAI_DEFAULT_MODEL=gpt-4.1
4. 実行します: uv run python examples/handoffs/message_filter_streaming.py

期待される動作・出力例

message_filter.py と同様に Step 1 done 〜 Step 4 done が表示され、最終履歴の JSON が出力されます。確認ポイントも同じです。

• 履歴の先頭 2 件（名乗りとその応答）が消えている
• ツール呼び出しの項目が消えている
• スペイン語エージェントは「名前は分からないが、ニューヨーク在住なのは知っている」と答える

ソースコード内のコメントに残された実行例では、最終応答は次のようになっています。

"No sé tu nombre, pero me dijiste que vives en Nueva York."

つまずきポイント

• input filter による履歴の加工結果はストリーミングイベントとして流れてきません。 SDK の Handoff.input_filter の仕様として、フィルター適用より前に生成された項目はすでにストリーミング済みであり、フィルターの結果として何かが再送されることはありません。「フィルターで消したはずの項目がイベントとしては流れてきた」ように見えても、最終的な履歴（to_input_list()）には反映されています
• message_filter.py と同じく、デフォルトモデルが GPT-5 系の場合はフィルタリングがスキップされます
• サーバー管理の会話機能（conversation_id や previous_response_id を使って会話履歴を OpenAI 側に保存する方式）と handoff の input filter は併用できません。この example のようにクライアント側で to_input_list() により履歴を管理する方式で使ってください

まとめ

• handoff は、エージェントが会話の主導権ごと別のエージェントに引き継ぐ仕組みで、LLM からは transfer_to_<agent_name> というツールとして見えます
• 引き継ぎ先は Agent.handoffs に Agent を直接渡すか、handoff() 関数でラップして渡します。handoff() ではツール名・説明・コールバック（on_handoff）・入力スキーマ（input_type）・有効/無効（is_enabled）などをカスタマイズできます
• デフォルトでは引き継ぎ先が会話履歴全体を見られます。input filter に HandoffInputData を加工する関数を渡すことで、ツール記録の削除や古い履歴の切り落としなどが可能です
• よくある加工は agents.extensions.handoff_filters に既製実装があり、代表が remove_all_tools です
• handoff は「電話の転送」（主導権が移る）、agents-as-tools は「部下への調べ物の依頼」（主導権は呼び出し元に残る）。以後の会話を専門家に任せたいなら handoff、結果だけ受け取って統合したいなら agents-as-tools を選びます
• ストリーミング実行（Runner.run_streamed）でも handoff と input filter は機能しますが、フィルターの加工結果自体はストリーミングされません

理解度チェック

解答と解説

参考リンク

• Handoffs（公式ドキュメント）: https://openai.github.io/openai-agents-python/handoffs/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/handoffs/

• Running agents（Runner.run / run_streamed の解説）: https://openai.github.io/openai-agents-python/running_agents/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/running_agents/

• Results（to_input_list() など実行結果の扱い）: https://openai.github.io/openai-agents-python/results/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/results/

• Streaming（ストリーミングイベントの詳細）: https://openai.github.io/openai-agents-python/streaming/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/streaming/

• Tracing（trace() とダッシュボードでの可視化）: https://openai.github.io/openai-agents-python/tracing/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/tracing/

• Examples 一覧: https://openai.github.io/openai-agents-python/examples/

  • 日本語版: https://openai.github.io/openai-agents-python/ja/examples/

第6章 MCP 連携（mcp）

前提知識

この章を読む前に、以下の内容を理解しておいてください。

• 第1章: SDK のセットアップ（git clone → uv sync）、OPENAI_API_KEY の設定、Agent と Runner の基本
• 第2章: function tool の仕組み（LLM がツールを選んで呼び出す流れ）
• 第3章: ストリーミングと非同期処理（async / await）の基本

また、この章の一部の example では Python 以外のツールが必要です。

概念解説

MCP（Model Context Protocol）とは

MCP（Model Context Protocol）は、アプリケーションが LLM（大規模言語モデル）にツールやコンテキスト（文脈情報）を提供する方法を標準化したオープンなプロトコルです。公式ドキュメントでは次のように説明されています。

MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにおける USB-C ポートのようなものだと考えてください。USB-C がさまざまな周辺機器やアクセサリーにデバイスを接続する標準化された方法を提供するように、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。

日常の比喩で考えてみましょう。海外旅行に行くとき、国ごとにコンセントの形状が違うと、家電ごとに専用の変換プラグが必要になり大変です。しかし USB-C のような統一規格があれば、どのメーカーの充電器でも、どのデバイスでも同じケーブルで接続できます。

AI エージェント開発でも同じ問題がありました。「ファイルを読むツール」「Git を操作するツール」「データベースを検索するツール」を Agent に持たせたいとき、従来はエージェントフレームワークごとに個別のツール実装（変換プラグ）を書く必要がありました。MCP はこの「接続部分」を標準化したことで、誰かが一度 MCP サーバーとして公開したツールは、MCP に対応したどのアプリケーションからでもそのまま使えるようになりました。

MCP サーバーと MCP クライアント

MCP の世界には 2 つの登場人物がいます。

• MCP サーバー: ツール（機能）を提供する側。例えば「ファイルシステム操作サーバー」は read_file（ファイルを読む）や list_directory（ディレクトリ一覧を取得する）といったツールを公開します
• MCP クライアント: ツールを利用する側。この章では OpenAI Agents SDK で作った Agent がクライアントになります

レストランに例えると、MCP サーバーは「メニュー（ツール一覧）を提示し、注文（ツール呼び出し）を受けて料理（実行結果）を返す厨房」、Agent は「メニューを見て注文する客」です。そしてメニューの書式や注文の伝え方（プロトコル）が世界共通なので、どの厨房（サーバー）とどの客（クライアント）を組み合わせても会話が成立します。

MCP サーバーはツール以外に、プロンプト（Agent への指示文のテンプレート。後述の prompt_server で扱います）やリソース（読み取り可能なデータ）も提供できます。

この関係を図にすると次のようになります。

SDK での統合の流れ

OpenAI Agents SDK では、MCP サーバーへの接続を表すオブジェクトを作り、Agent の mcp_servers 引数に渡すだけで統合できます。内部の流れは次のとおりです。

1. MCP サーバーに接続する（stdio の場合はサブプロセスとして起動する。サブプロセスとは、プログラムの中から起動される別のプログラムのことです）
2. Agent の実行のたびに、SDK がサーバーの list_tools() を呼び出してツール一覧を取得する
3. 取得したツールは LLM から見ると通常の function tool と同じように見える
4. LLM が MCP ツールの使用を選択すると、SDK がサーバーの call_tool() を呼び出して実行し、結果を LLM に返す

つまり読者のみなさんは「サーバーへの接続」さえ書けば、あとは第2章で学んだ function tool とまったく同じ感覚で使えます。この4ステップを図にすると次のとおりです。

3 つのトランスポートの違い

MCP クライアントとサーバーの間の通信方式をトランスポートと呼びます。SDK は 3 種類のトランスポートをサポートしており、それぞれに対応するクラスが agents.mcp モジュールに用意されています。

• stdio: サーバーをローカルのサブプロセスとして起動し、標準入出力（キーボード入力や画面出力に使われる、プログラムの基本的な入出力経路）でやり取りします。「同じ部屋にいる相手と直接会話する」イメージです。ネットワーク設定が不要で、最も手軽です
• SSE（Server-Sent Events）: サーバーからクライアントへ一方向にデータをプッシュし続ける HTTP の仕組みです。「ラジオ放送を聞きながら、別の電話で注文する」ような二本立ての通信になります。MCP プロジェクトではすでに非推奨となっており、新規開発では次の Streamable HTTP を使うべきです
• Streamable HTTP: 単一の HTTP エンドポイントで双方向のやり取りとストリーミング（データを一括ではなく少しずつ順次送る方式）を実現する、現在推奨されている HTTP トランスポートです

なお、これらはすべて「自分のコードがクライアントとして接続を管理する」方式です。これに対して、接続管理ごと OpenAI 側のインフラに任せる「ホスト型 MCP（Hosted MCP）」もあり、それは次の第7章で扱います。

3 つのトランスポートの通信経路を並べると、次のようになります。

この章の examples の全体像

examples/mcp ディレクトリには 11 個の example があります。前半（6.1〜6.7）はトランスポート別の基本形、後半（6.8〜6.11）は応用機能（プロンプト、フィルタリング、事前取得、ライフサイクル管理）です。

すべての example は、リポジトリのルートディレクトリ（git clone して uv sync を済ませた openai-agents-python ディレクトリ）で実行する前提です。また、LLM を呼び出す example はすべて環境変数（OS がプログラムに渡す設定値）OPENAI_API_KEY の設定が必要です。

export OPENAI_API_KEY=sk-...

各 example の解説

filesystem_example

MCP の最も基本的な example です。Model Context Protocol 公式が配布しているファイルシステム操作用 MCP サーバー（@modelcontextprotocol/server-filesystem）を npx 経由でサブプロセスとして起動し、Agent にローカルファイルの読み取り能力を与えます。

コード解説

main.py の中心部分は、MCPServerStdio でサーバーを起動して Agent に渡す箇所です。

async def main():
    current_dir = os.path.dirname(os.path.abspath(__file__))
    samples_dir = os.path.join(current_dir, "sample_files")

    async with MCPServerStdio(
        name="Filesystem Server, via npx",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
        },
    ) as server:
        trace_id = gen_trace_id()
        with trace(workflow_name="MCP Filesystem Example", trace_id=trace_id):
            print(f"View trace: https://platform.openai.com/logs/trace?trace_id={trace_id}\n")
            await run(server)

• MCPServerStdio の params には、サーバーを起動するコマンドラインをそのまま指定します。ここでは「npx -y @modelcontextprotocol/server-filesystem <sample_filesディレクトリ>」を実行しています。-y は npx の確認プロンプトを省略するオプション、最後の引数はサーバーがアクセスを許可されるディレクトリです。サーバーには sample_files ディレクトリしか見せていない点に注目してください。MCP サーバーに渡す権限は最小限に絞るのが安全です
• async with（非同期コンテキストマネージャ。ブロックを抜けるときに後片付けを自動実行する構文）を使うことで、ブロック終了時にサブプロセスの終了とパイプのクローズが自動で行われます
• gen_trace_id() と trace() はトレーシング（実行の記録。どのツールがいつ呼ばれたかを OpenAI のダッシュボードで可視化する機能）の設定です。表示された URL を開くと、MCP ツールの呼び出し履歴を確認できます

Agent 側は驚くほどシンプルです。

async def run(mcp_server: MCPServer):
    agent = Agent(
        name="Assistant",
        instructions="Use the tools to read the filesystem and answer questions based on those files.",
        mcp_servers=[mcp_server],
    )

    # List the files it can read
    message = "Read the files and list them."
    print(f"Running: {message}")
    result = await Runner.run(starting_agent=agent, input=message)
    print(result.final_output)

mcp_servers=[mcp_server] にサーバーを渡すだけで、サーバーが公開する list_directory() や read_file() などのツールが Agent から使えるようになります。ツールを 1 つも自分で定義していないのに、Agent がファイル操作できるようになるのが MCP の威力です。

ファイル末尾では、実行前に npx の存在チェックをしています。

if __name__ == "__main__":
    # Let's make sure the user has npx installed
    if not shutil.which("npx"):
        raise RuntimeError("npx is not installed. Please install it with `npm install -g npx`.")

    asyncio.run(main())

実行手順

1. Node.js をインストールし、npx --version でコマンドが使えることを確認します
2. OPENAI_API_KEY を設定します
3. リポジトリルートで以下を実行します（初回は npx がサーバーパッケージをダウンロードするため少し時間がかかります）

uv run python examples/mcp/filesystem_example/main.py

期待される動作・出力例

3 つの質問が順に実行されます。sample_files には favorite_books.txt、favorite_cities.txt、favorite_songs.txt が入っているため、次のような出力になります。

View trace: https://platform.openai.com/logs/trace?trace_id=trace_...

Running: Read the files and list them.
The files are: favorite_books.txt, favorite_cities.txt, favorite_songs.txt ...

Running: Read favorite_books.txt and tell me my #1 favorite book.
Your #1 favorite book is "To Kill a Mockingbird" by Harper Lee.

Running: Read favorite_songs.txt and suggest one new song that I might like.
(好みの曲リストを踏まえたおすすめ曲の提案)

つまずきポイント

• npx is not installed エラーが出る場合は Node.js がインストールされていません
• 企業ネットワーク等で npm レジストリにアクセスできない環境では、初回のパッケージダウンロードに失敗します

async with MCPServerStdio(...) のブロックが、サブプロセスの一生（起動から終了まで）とちょうど重なっている様子を図にすると次のとおりです。

git_example

公式の Git 操作用 MCP サーバー（mcp-server-git）を uvx 経由で起動し、任意のローカル Git リポジトリについて質問できる Agent を作る example です。uvx は uv に同梱されているコマンドで、Python 製ツールをインストールなしで一時的に実行できます（Node.js における npx の Python 版と考えてください）。

コード解説

async def main():
    # Ask the user for the directory path
    directory_path = input_with_fallback(
        "Please enter the path to the git repository: ",
        ".",
    )

    async with MCPServerStdio(
        cache_tools_list=True,  # Cache the tools list, for demonstration
        params={"command": "uvx", "args": ["mcp-server-git"]},
    ) as server:
        with trace(workflow_name="MCP Git Example"):
            await run(server, directory_path)

• 起動時にユーザーへ Git リポジトリのパスを尋ねます。input_with_fallback は examples 共通のヘルパー関数で、環境変数 EXAMPLES_INTERACTIVE_MODE=auto が設定されているときは入力を求めずに既定値（ここではカレントディレクトリ .）を使います。CI などの自動実行のための仕組みで、通常の学習では普通に入力すれば大丈夫です
• cache_tools_list=True が新しいポイントです。SDK は Agent の実行のたびにサーバーの list_tools() を呼びますが、このオプションを有効にするとツール一覧を初回取得後にキャッシュ（結果を保存して再利用）し、2 回目以降の問い合わせを省略します。ツール構成が変わらないサーバーでは実行のたびの待ち時間を減らせます。キャッシュを破棄したいときは server.invalidate_tools_cache() を呼びます

Agent の instructions には、ユーザーが入力したリポジトリパスを埋め込みます。

async def run(mcp_server: MCPServer, directory_path: str):
    agent = Agent(
        name="Assistant",
        instructions=f"Answer questions about the git repository at {directory_path}, use that for repo_path",
        mcp_servers=[mcp_server],
    )

    message = "Who's the most frequent contributor?"

Git サーバーのツール（git_log など）は引数に repo_path を要求するため、instructions で「このパスを repo_path に使え」とあらかじめ指示しているのがコツです。

実行手順

1. uv がインストール済みであることを確認します（uvx --version が通れば OK）
2. OPENAI_API_KEY を設定します
3. リポジトリルートで以下を実行します

uv run python examples/mcp/git_example/main.py

4. Please enter the path to the git repository: と聞かれたら、調べたい Git リポジトリの絶対パス（例: いま作業中の openai-agents-python のパス）を入力します

期待される動作・出力例

「最も頻繁なコントリビューターは誰か」「最後の変更を要約して」という 2 つの質問に対して、Agent が git_log 等の MCP ツールでコミット履歴を取得し、回答します。

----------------------------------------
Running: Who's the most frequent contributor?
The most frequent contributor to this repository is ... with NNN commits.

----------------------------------------
Running: Summarize the last change in the repository.
The most recent change is commit ... which ...

つまずきポイント

• コード内のエラーメッセージには pip install uvx とありますが、実際には uvx は uv 本体に同梱されています。uv を公式手順でインストールすれば別途インストールは不要です
• Git リポジトリではないパスを入力すると、ツール呼び出しがエラーになります

sse_example

SSE トランスポートの example です。server.py（自作の小さな MCP サーバー）をサブプロセスとして自動起動し、MCPServerSse で接続します。「MCP サーバーを自分で作る」側のコードが初めて登場します。

コード解説（サーバー側: server.py）

サーバーは公式 MCP Python SDK の MCPServer を使うと、デコレーター（関数に機能を追加する @ 記法）だけで作れます。42 行の全体像から主要部を引用します。

バージョン注記: MCP Python SDK v1 では、このクラスの名前は FastMCP（from mcp.server.fastmcp import FastMCP）でした。SDK v2 で MCPServer（from mcp.server.mcpserver import MCPServer）に改称され、ホスト・ポートは MCPServer() のコンストラクタ引数ではなく mcp.run() の引数で渡す形に変わっています。openai-agents は v0.20.0 で MCP Python SDK v1 と v2 の両方をサポートし（依存は mcp>=1.19.0,<3）、examples は v2 の書き方に更新されました。v1 のままにしたい場合は mcp<2 にピン留めできます

from mcp.server.mcpserver import MCPServer

SSE_HOST = os.getenv("SSE_HOST", "127.0.0.1")
SSE_PORT = int(os.getenv("SSE_PORT", "8000"))

# Create server
mcp = MCPServer("Echo Server")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    print(f"[debug-server] add({a}, {b})")
    return a + b


@mcp.tool()
def get_secret_word() -> str:
    print("[debug-server] get_secret_word()")
    return random.choice(["apple", "banana", "cherry"])

if __name__ == "__main__":
    mcp.run(transport="sse", host=SSE_HOST, port=SSE_PORT)

• @mcp.tool() を付けた Python 関数が、そのまま MCP ツールとして公開されます。関数の型ヒントと docstring からツールのスキーマ（引数の仕様）が自動生成されます
• mcp.run(transport="sse", host=..., port=...) で SSE トランスポートのサーバーとして起動します。MCP SDK v1（FastMCP）ではホスト・ポートをコンストラクタで渡していましたが、v2 では run() 側に移りました
• このほか get_current_weather(city) ツールも定義されており、東京・サンフランシスコ・ニューヨークの固定の天気を返します（オフラインでも安定動作するように実データは取得しません）

コード解説（クライアント側: main.py）

main.py は空いているポートを自動選択し（環境変数 SSE_PORT があればそれを優先）、subprocess.Popen でサーバーを起動してから Agent を実行します。

    process: subprocess.Popen[Any] | None = None
    try:
        this_dir = os.path.dirname(os.path.abspath(__file__))
        server_file = os.path.join(this_dir, "server.py")

        print(f"Starting SSE server at {SSE_URL} ...")

        # Run `uv run server.py` to start the SSE server
        env = os.environ.copy()
        env.setdefault("SSE_HOST", SSE_HOST)
        env.setdefault("SSE_PORT", str(SSE_PORT))
        process = subprocess.Popen(["uv", "run", server_file], env=env)
        # Give it 3 seconds to start
        time.sleep(3)

接続部分は URL を指定するだけです。stdio と違い、サーバーの起動コマンドではなく接続先 URL を渡す点が本質的な違いです。

async def main():
    async with MCPServerSse(
        name="SSE Python Server",
        params={
            "url": SSE_URL,
        },
    ) as server:

Agent には ModelSettings(tool_choice="required") が指定されています。これは「必ず何らかのツールを使って回答せよ」というモデルへの強制で、デモとして確実にツール呼び出しを観察するための設定です。

    agent = Agent(
        name="Assistant",
        instructions="Use the tools to answer the questions.",
        mcp_servers=[mcp_server],
        model_settings=ModelSettings(tool_choice="required"),
    )

実行手順

1. OPENAI_API_KEY を設定します
2. リポジトリルートで以下を実行します（サーバーの起動・終了はスクリプトが自動で行うため、ターミナルは 1 つで完結します）

uv run python examples/mcp/sse_example/main.py

3. ポートを固定したい場合は SSE_PORT=8000 SSE_HOST=127.0.0.1 を指定して実行します

期待される動作・出力例

「7 + 22 を計算して」「東京の天気は？」「秘密の言葉は？」の 3 つの質問に、それぞれ add、get_current_weather、get_secret_word ツールを使って回答します。サーバー側のログ（[debug-server] add(7, 22) など）も同じターミナルに混ざって表示されます。

Starting SSE server at http://127.0.0.1:xxxxx/sse ...
SSE server started. Running example...

Running: Add these numbers: 7 and 22.
[debug-server] add(7, 22)
The sum of 7 and 22 is 29.

Running: What's the weather in Tokyo?
The weather in Tokyo is sunny with a light breeze and 20°C.

Running: What's the secret word?
The secret word is "banana".

つまずきポイント

• SSE トランスポートは MCP プロジェクトで非推奨になっています。この example は既存 SSE サーバーとの接続方法を知るためのもので、新規にサーバーを作るなら Streamable HTTP（6.5）を選んでください
• サーバー起動の待機は time.sleep(3) の固定 3 秒です。低速なマシンで接続エラーになる場合は、この秒数を伸ばすと解決することがあります

sse_remote_example

SSE サーバーが「リモートにある」場合の接続パターンを示す example です。環境変数 MCP_SSE_REMOTE_URL が設定されていればそのリモートサーバーへ、なければ 6.3 の sse_example/server.py をローカルで自動起動して接続します。

コード解説

接続時にタイムアウト（応答を待つ制限時間）関連のパラメータを指定しているのが 6.3 との違いです。

async def run(url: str, name: str) -> None:
    async with MCPServerSse(
        name=name,
        params={
            "url": url,
            "timeout": 5,
            "sse_read_timeout": 30,
        },
    ) as server:

• timeout は HTTP 接続のタイムアウト秒数、sse_read_timeout は SSE ストリームの読み取りタイムアウト秒数です。ネットワーク越しの接続では、こうした値を明示しておくと障害時の切り分けが楽になります

メイン処理は URL の有無で分岐します。

async def main() -> None:
    if REMOTE_SSE_URL:
        print(f"Connecting to remote SSE server at {REMOTE_SSE_URL} ...", flush=True)
        await run(REMOTE_SSE_URL, "Remote SSE Server")
        return

    print(
        "MCP_SSE_REMOTE_URL is not set; using the bundled local SSE server for this demo.",
        flush=True,
    )
    with local_sse_server() as url:
        await run(url, "Local SSE Server")

local_sse_server() はコンテキストマネージャとして実装されており、隣の sse_example/server.py をサブプロセス起動し、終了時には terminate() → 5 秒待っても終わらなければ kill() という丁寧な後始末をしています。実運用でサブプロセスを管理する際の良いお手本です。

実行手順

1. OPENAI_API_KEY を設定します
2. ローカルサーバーで試す場合は、そのまま実行します

uv run python examples/mcp/sse_remote_example/main.py

3. 手元にある互換の SSE サーバー（add ツールを持つもの）に接続したい場合は、URL を指定します

export MCP_SSE_REMOTE_URL=http://<ホスト>:<ポート>/sse
uv run python examples/mcp/sse_remote_example/main.py

期待される動作・出力例

「MCP の add ツールで 7 + 22 を計算して」という 1 つの質問を実行し、29 を含む回答が表示されます。

MCP_SSE_REMOTE_URL is not set; using the bundled local SSE server for this demo.
Starting local SSE server at http://127.0.0.1:xxxxx/sse ...
View trace: https://platform.openai.com/logs/trace?trace_id=trace_...

7 + 22 = 29.

つまずきポイント

• MCP_SSE_REMOTE_URL に指定するサーバーは add ツールを公開している必要があります。ツール名が異なるサーバーでは質問文と噛み合わず、期待した動作になりません

streamablehttp_example

現在推奨されている Streamable HTTP トランスポートの基本 example です。構成は 6.3 の sse_example とほぼ同じで、server.py を自動起動して MCPServerStreamableHttp で接続します。SSE 版と見比べると、トランスポートを差し替えても Agent 側のコードがほとんど変わらないことがよく分かります。

コード解説

サーバー側（server.py）の違いは、起動時のトランスポート指定と既定ポートだけです。

STREAMABLE_HTTP_HOST = os.getenv("STREAMABLE_HTTP_HOST", "127.0.0.1")
STREAMABLE_HTTP_PORT = int(os.getenv("STREAMABLE_HTTP_PORT", "18080"))

# Create server
mcp = MCPServer("Echo Server")

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host=STREAMABLE_HTTP_HOST,
        port=STREAMABLE_HTTP_PORT,
    )

このサーバーの get_current_weather は、実際に天気情報サイト（wttr.in）へ HTTP アクセスを試み、失敗したらフォールバック文字列を返す実装になっています（SSE 版は固定データでした）。

クライアント側は、クラス名と URL のパス（/sse → /mcp）が変わっただけです。

async def main():
    async with MCPServerStreamableHttp(
        name="Streamable HTTP Python Server",
        params={
            "url": STREAMABLE_HTTP_URL,
        },
    ) as server:
        trace_id = gen_trace_id()
        with trace(workflow_name="Streamable HTTP Example", trace_id=trace_id):
            print(f"View trace: https://platform.openai.com/logs/trace?trace_id={trace_id}\n")
            await run(server)

URL は http://<ホスト>:<ポート>/mcp という形式で、Streamable HTTP サーバーは慣例的に /mcp パスを使います。

実行手順

1. OPENAI_API_KEY を設定します
2. リポジトリルートで以下を実行します（サーバーは自動起動されます）

uv run python examples/mcp/streamablehttp_example/main.py

3. ポートを固定したい場合は STREAMABLE_HTTP_PORT、バインドアドレスを変えたい場合は STREAMABLE_HTTP_HOST を設定します

期待される動作・出力例

sse_example と同じ 3 つの質問（足し算・天気・秘密の言葉）が実行されます。天気の質問では wttr.in のテキストアート形式の天気予報が返ることもあれば、オフライン時はフォールバックメッセージが返ります。

つまずきポイント

• 新規に HTTP 系の MCP 統合を作るときは、SSE ではなくこの Streamable HTTP を選んでください
• 3 秒待機で接続できない場合の対処は sse_example と同じです

streamable_http_remote_example

インターネット上に公開されている実在の MCP サーバー DeepWiki（https://mcp.deepwiki.com/mcp。GitHub リポジトリの内容を調べられるサービス）に Streamable HTTP で接続する example です。自前のサーバー起動が一切不要で、「他者が運用する MCP サーバーをそのまま使う」体験ができます。ファイルは 38 行と短いので全文を引用します。

コード解説

import asyncio

from agents import Agent, Runner, gen_trace_id, trace
from agents.mcp import MCPServerStreamableHttp


async def main():
    async with MCPServerStreamableHttp(
        name="DeepWiki MCP Streamable HTTP Server",
        params={
            "url": "https://mcp.deepwiki.com/mcp",
            # Allow more time for remote tool responses.
            "timeout": 15,
            "sse_read_timeout": 300,
        },
        # Retry slow/unstable remote calls a couple of times.
        max_retry_attempts=2,
        retry_backoff_seconds_base=2.0,
        client_session_timeout_seconds=15,
    ) as server:
        agent = Agent(
            name="DeepWiki Assistant",
            instructions="Use the tools to respond to user requests.",
            mcp_servers=[server],
        )

        trace_id = gen_trace_id()
        with trace(workflow_name="DeepWiki Streamable HTTP Example", trace_id=trace_id):
            print(f"View trace: https://platform.openai.com/logs/trace?trace_id={trace_id}\n")
            result = await Runner.run(
                agent,
                "For the repository openai/codex, tell me the primary programming language.",
            )
            print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

リモートサーバーならではの堅牢化オプションが 3 つ登場します。

• max_retry_attempts=2: list_tools() や call_tool() が失敗したとき最大 2 回まで自動リトライ（再試行）します
• retry_backoff_seconds_base=2.0: リトライ間隔の基準秒数です。指数バックオフ（失敗のたびに待ち時間を倍々に伸ばす方式）の底として使われます
• client_session_timeout_seconds=15: MCP セッションの読み取りタイムアウトです

ローカルサーバーでは不要だったこれらの設定が、不安定になりがちなリモート接続では重要になります。

実行手順

1. OPENAI_API_KEY を設定します
2. インターネットに接続できる環境で、リポジトリルートで以下を実行します

uv run python examples/mcp/streamable_http_remote_example/main.py

期待される動作・出力例

Agent が DeepWiki のツールで openai/codex リポジトリを調査し、主要なプログラミング言語（Rust）を回答します。

View trace: https://platform.openai.com/logs/trace?trace_id=trace_...

The primary programming language of the openai/codex repository is Rust.

つまずきポイント

• DeepWiki は外部サービスのため、応答に時間がかかったり一時的に失敗したりすることがあります。リトライ設定はそのための保険です
• プロキシ必須のネットワーク環境では接続に失敗します。その場合は次の 6.7 のカスタム HTTP クライアントが解決策になります

streamablehttp_custom_client_example

MCPServerStreamableHttp の httpx_client_factory パラメータを使って、MCP 通信に使う HTTP クライアント（Python の HTTP ライブラリ httpx の AsyncClient）を自分で構成する example です。

バージョン注記: この example は openai-agents v0.20.0 の MCP Python SDK v2 対応にあわせて httpx から httpx2 へ移行しました。カスタム HTTP 認証やクライアントファクトリを使うアプリケーションは、インストールされている MCP のメジャーバージョンが持つ HTTP 型（v2 なら httpx2、v1 なら httpx）を使う必要があります。移行したくない場合は mcp<2 にピン留めしてください。v0.20.0 で唯一「破壊的になりうる」とアナウンスされた箇所です。SSL 証明書、カスタムヘッダー、タイムアウト、プロキシなど、企業ネットワークや本番運用で必要になる細かな HTTP 設定を注入できます。

コード解説

中心は、カスタム設定済みの httpx2.AsyncClient を返すファクトリ関数（オブジェクトを生成して返す関数）です。

def create_custom_http_client(
    headers: dict[str, str] | None = None,
    timeout: httpx2.Timeout | None = None,
    auth: httpx2.Auth | None = None,
) -> httpx2.AsyncClient:
    """Create a custom HTTP client with specific configurations."""
    if headers is None:
        headers = {
            "X-Custom-Client": "agents-mcp-example",
            "User-Agent": "OpenAI-Agents-MCP/1.0",
        }
    if timeout is None:
        timeout = httpx2.Timeout(60.0, read=120.0)
    if auth is None:
        auth = None
    return httpx2.AsyncClient(
        # Disable SSL verification for testing (not recommended for production)
        verify=False,
        # Set custom timeout
        timeout=httpx2.Timeout(60.0, read=120.0),
        # Add custom headers that will be sent with every request
        headers=headers,
    )

• verify=False は SSL 証明書検証の無効化です。コメントにあるとおりテスト専用で、本番では絶対に使わないでください。証明書検証を無効にすると中間者攻撃（MITM。通信経路上の第三者による盗聴・改ざん）を検出できなくなります。開発環境で自己署名証明書を使う場合も、検証を無効化するのではなく、verify="/path/to/ca.pem" のように CA 証明書を信頼対象として指定するか、正規に発行された証明書を使うのが正しい対処です
• headers に指定した内容は、MCP サーバーへのすべての HTTP リクエストに付与されます。API キーによる認証ヘッダーの追加などに応用できます

このファクトリ関数を params に渡すだけで、SDK が MCP 通信にこのクライアントを使うようになります。

    async with MCPServerStreamableHttp(
        name="Streamable HTTP with Custom Client",
        params={
            "url": STREAMABLE_HTTP_URL,
            "httpx_client_factory": create_custom_http_client,
        },
    ) as server:

サーバー側（server.py、27 行）は add と get_secret_word の 2 ツールだけの最小構成で、6.5 と同様に main.py がサブプロセスとして自動起動します。

実行手順

1. OPENAI_API_KEY を設定します
2. README の手順どおり、example のディレクトリに移動して実行します

cd examples/mcp/streamablehttp_custom_client_example
uv run main.py

（リポジトリルートから uv run python examples/mcp/streamablehttp_custom_client_example/main.py でも実行できます）

期待される動作・出力例

カスタムクライアント経由で「7 + 22」の足し算が実行され、29 を含む回答が表示されます。見た目の動作は 6.5 と同じですが、裏側の HTTP リクエストにはカスタムヘッダーが載っています。

つまずきポイント

• ここで学ぶべきは「動くこと」より「どこを差し替えられるか」です。社内プロキシ経由の接続、独自 CA 証明書、Bearer トークン認証などが必要になったら、この example の create_custom_http_client を書き換える形で対応します

prompt_server

MCP サーバーはツールだけでなくプロンプト（Agent への指示文テンプレート）も提供できます。この example では、コードレビュー用の instructions を生成するプロンプトを持つサーバーを立て、Agent の instructions を MCP 経由で動的に組み立てます。「Agent の人格・専門性をサーバー側で管理する」パターンです。

コード解説（サーバー側: server.py）

ツールの @mcp.tool() の代わりに @mcp.prompt() デコレーターを使います。

# Instruction-generating prompts (user-controlled)
@mcp.prompt()
def generate_code_review_instructions(
    focus: str = "general code quality", language: str = "python"
) -> str:
    """Generate agent instructions for code review tasks"""
    print(f"[debug-server] generate_code_review_instructions({focus}, {language})")

    return f"""You are a senior {language} code review specialist. Your role is to provide comprehensive code analysis with focus on {focus}.
...
"""

focus（レビューの観点）と language（対象言語）という 2 つのパラメータを受け取り、それを埋め込んだ長文の instructions を返します。呼び出し側がパラメータを変えるだけで、「セキュリティ特化のレビュアー」「パフォーマンス特化のレビュアー」を同じテンプレートから作り分けられます。

コード解説（クライアント側: main.py）

プロンプト関連の API は 2 つです。まず list_prompts() で利用可能なプロンプトを列挙します。

async def show_available_prompts(mcp_server: MCPServer):
    """Show available prompts for user selection"""
    print("=== AVAILABLE PROMPTS ===")

    prompts_result = await mcp_server.list_prompts()
    print("User can select from these prompts:")
    for i, prompt in enumerate(prompts_result.prompts, 1):
        print(f"  {i}. {prompt.name} - {prompt.description}")
    print()

次に get_prompt(名前, 引数) で具体的なプロンプト本文を取得します。

    try:
        prompt_result = await mcp_server.get_prompt(prompt_name, kwargs)
        content = prompt_result.messages[0].content
        if hasattr(content, "text"):
            instructions = content.text
        else:
            instructions = str(content)

取得した文字列を、そのまま Agent の instructions に渡します。

    instructions = await get_instructions_from_prompt(
        mcp_server,
        "generate_code_review_instructions",
        focus="security vulnerabilities",
        language="python",
    )

    agent = Agent(
        name="Code Reviewer Agent",
        instructions=instructions,  # Instructions from MCP prompt
        model_settings=ModelSettings(tool_choice="auto"),
    )

そしてこの Agent に、わざと脆弱なコード（ユーザー入力をそのまま os.system に渡すコマンドインジェクションの典型例）をレビューさせます。

実行手順

1. OPENAI_API_KEY を設定します
2. リポジトリルートで以下を実行します（プロンプトサーバーは自動起動されます）

uv run python examples/mcp/prompt_server/main.py

期待される動作・出力例

まず利用可能なプロンプトの一覧が表示され、続いてセキュリティ観点のコードレビュー結果が出力されます。

=== AVAILABLE PROMPTS ===
User can select from these prompts:
  1. generate_code_review_instructions - Generate agent instructions for code review tasks

=== CODE REVIEW DEMO ===
Getting instructions from prompt: generate_code_review_instructions
Generated instructions
Running: Please review this code: ...
1. Overall Assessment ...
(コマンドインジェクション脆弱性の指摘と修正案が続く)

つまずきポイント

• プロンプト取得（get_prompt）は Agent 実行前に「自分のコードで」明示的に呼ぶ点に注意してください。ツールと違って LLM が自動で選ぶものではなく、ユーザー（開発者）が制御する機能です

list_prompts() から get_prompt() を経て instructions が組み上がるまでの流れは、次のように整理できます。

tool_filter_example

MCP サーバーが公開するツールのうち一部だけを Agent に見せるツールフィルタリングの example です。ファイルシステムサーバーは書き込み系ツールも持っていますが、読み取り系だけを許可し、書き込みを遮断します。あわせて、ツール実行前に承認を要求する require_approval も登場します。

コード解説

サーバー構築時に tool_filter と require_approval を指定します。

    async with MCPServerStdio(
        name="Filesystem Server with filter",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
            "cwd": samples_dir,
        },
        require_approval="always",
        tool_filter=create_static_tool_filter(
            allowed_tool_names=["read_file", "list_directory"],
            blocked_tool_names=["write_file"],
        ),
    ) as server:

• create_static_tool_filter は静的（実行中に変化しない）な許可リスト・拒否リストを作るヘルパー関数です。allowed_tool_names と blocked_tool_names を両方指定した場合、先に許可リストで絞り込み、その結果からさらに拒否リストのツールを除外します。結果として、この Agent からは read_file と list_directory しか見えません
• require_approval="always" は「すべてのツール呼び出しの前に承認を要求する」設定です。承認が必要になると Agent の実行は一時停止し、結果の interruptions（中断情報）に承認待ちのツール呼び出しが入ります

承認待ちを処理するループが次の関数です。

async def run_with_auto_approval(agent: Agent[Any], message: str) -> str | None:
    """Run and auto-approve interruptions."""

    result = await Runner.run(agent, message)
    while result.interruptions:
        state = result.to_state()
        for interruption in result.interruptions:
            print(f"Approving a tool call... (name: {interruption.name})")
            state.approve(interruption, always_approve=True)
        result = await Runner.run(agent, state)
    return cast(str | None, result.final_output)

• result.interruptions が空でない間、result.to_state() で実行状態を取り出し、state.approve(...) で承認してから Runner.run(agent, state) で中断地点から再開します。always_approve=True は「同名ツールは以後自動承認」の指定です
• この example では機械的に全承認していますが、approve の代わりに reject を呼べば拒否もできます。人間に判断を仰ぐ本格的な例は次の 6.10 で扱います

メイン処理では、まず許可されている「一覧表示」を実行し、次にわざと「ファイル作成」を依頼して、フィルタで遮断されることを確認します。

実行手順

1. Node.js（npx）をインストールします
2. OPENAI_API_KEY を設定します
3. リポジトリルートで以下を実行します

uv run python examples/mcp/tool_filter_example/main.py

期待される動作・出力例

View trace: https://platform.openai.com/logs/trace?trace_id=trace_...

Approving a tool call... (name: list_directory)
The allowed directory contains: books.txt, favorite_songs.txt

Attempting to write a file (should be blocked):
I cannot create the file because write operations are blocked by the tool filter. ...

1 回目の依頼ではツール実行前に承認ログが出てからファイル一覧が表示され、2 回目の依頼では「書き込みツールが使えないため実行できない」という説明が返ります。

つまずきポイント

• フィルタは「LLM にツールの存在自体を見せない」仕組みです。遮断されたツールについて Agent は「使えるが拒否された」のではなく「そもそも知らない」状態になるため、instructions で「使えないツールを求められたらフィルタで遮断されている旨を説明せよ」と指示しています

tool_filter による絞り込みと require_approval による承認は、それぞれ独立した制御の二段構えになっています。

get_all_mcp_tools_example

これまでの example は mcp_servers に渡して「実行のたびにツール一覧を取得」していましたが、この example では MCPUtil.get_all_function_tools で MCP ツールを事前に取得（プリフェッチ）し、通常の tools として Agent に渡すパターンを示します。さらに、特定ツールだけに承認を要求し、人間が y/n で承認する Human-in-the-loop（HITL。処理の途中に人間の判断を挟む仕組み）の完全な流れも実演します。

コード解説

ツールの事前取得は次の関数で行います。

async def list_tools(server: MCPServer, *, convert_to_strict: bool) -> list[Any]:
    """Fetch all MCP tools from the server."""

    run_context: RunContextWrapper[dict[str, str]] = RunContextWrapper(context={})
    agent = Agent(name="ToolFetcher", instructions="Prefetch MCP tools.", mcp_servers=[server])

    return await MCPUtil.get_all_function_tools(
        [server],
        convert_schemas_to_strict=convert_to_strict,
        run_context=run_context,
        agent=agent,
    )

• MCPUtil.get_all_function_tools は、MCP サーバー群のツールを SDK の function tool オブジェクトのリストに変換して返します。convert_schemas_to_strict=True を指定すると、ツールの引数スキーマを strict JSON schema（OpenAI のモデルが引数を厳密に守るための形式）へ可能な範囲で変換します
• 取得したツールは Agent(tools=all_tools) のように通常のツールとして渡せます。mcp_servers を使わないため、実行のたびの list_tools() 呼び出しが発生しません

サーバー構築時の承認設定は、6.9 より細かい「特定ツールのみ」の形式です。

    async with MCPServerStdio(
        name="Filesystem Server",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
            "cwd": samples_dir,
        },
        require_approval={"always": {"tool_names": ["read_text_file"]}},
    ) as server:

require_approval は "always" / "never" の一括指定のほか、このような {"always": {"tool_names": [...]}} 形式や、{"ツール名": "always"} のようなツール別指定も受け付けます。ここでは read_text_file（ファイルシステムサーバーのファイル読み取りツール）だけが承認対象です。

承認は今回、本物の人間に問い合わせます。

    while True:
        user_input = input(f"Approve tool call '{interruption_name}'? (y/n): ").strip().lower()
        if user_input == "y":
            return True
        if user_input == "n":
            return False
        print("Please enter 'y' or 'n'.")

そして resolve_interruptions 関数が、承認なら state.approve(interruption)、拒否なら state.reject(interruption) を呼んで実行を再開します。

後半では、実行中のサーバーに対して動的にフィルタを適用し、ツール一覧を取り直します。

            # Apply a static tool filter and refetch tools.
            server.tool_filter = create_static_tool_filter(
                allowed_tool_names=["read_file", "list_directory"]
            )
            filtered_tools = await list_tools(server, convert_to_strict=False)

tool_filter はサーバーオブジェクトの属性として後から差し替えられることが分かります。フィルタ後のツールで作った Agent に「ファイルを作成して」と依頼し、作成系ツールがないため断られる、という流れは 6.9 と同様です。

実行手順

1. Node.js（npx）をインストールします
2. OPENAI_API_KEY を設定します
3. リポジトリルートで以下を実行します

uv run python examples/mcp/get_all_mcp_tools_example/main.py

4. 実行中に Approve tool call 'read_text_file'? (y/n): と聞かれたら y を入力して承認します（n で拒否した場合の挙動も試してみてください）
5. 対話なしで動かしたい場合は EXAMPLES_INTERACTIVE_MODE=auto を設定すると自動承認されます

期待される動作・出力例

=== Fetching all tools with strict schemas ===
Found NN tool(s):
- read_file: Read the complete contents of a file ...
- write_file: ...
（ファイルシステムサーバーの全ツールが列挙される）

Running: List files in this allowed directory: ... Then read one of those files.

Approve tool call 'read_text_file'? (y/n): y
Approving a tool call... (name: read_text_file)
（ファイル一覧と、読んだファイルの内容の説明）

=== After applying tool filter ===
Found 2 tool(s):
- read_file
- list_directory

Running: Create a file named "..." with the text "hello". ...
（作成ツールがないため実行できない旨の説明）

つまずきポイント

• 事前取得したツールは取得時点のスナップショットです。サーバー側のツール構成が変わっても自動では追従しないため、必要に応じて取得し直してください
• 一覧に出るツール名（read_text_file など）はファイルシステムサーバーのバージョンによって増減・変更されることがあります

manager_example

実運用に最も近い example です。Web アプリケーション（FastAPI。Python の Web フレームワーク）の中で MCPServerManager を使い、複数の MCP サーバーの接続・切断を一元管理します。この example だけは、MCP サーバーとアプリを別々のターミナルで手動起動します。

構成は 3 ファイルです。

• mcp_server.py: add と echo の 2 ツールを持つ Streamable HTTP サーバー（26 行）
• app.py: MCPServerManager を組み込んだ FastAPI アプリ
• smoke_test.py: モデルを呼ばずに統合を検証するテストスクリプト

コード解説（mcp_server.py）

全 26 行の最小サーバーです。

import os

from mcp.server.mcpserver import MCPServer

STREAMABLE_HTTP_HOST = os.getenv("STREAMABLE_HTTP_HOST", "127.0.0.1")
STREAMABLE_HTTP_PORT = int(os.getenv("STREAMABLE_HTTP_PORT", "8000"))

mcp = MCPServer("FastAPI Example Server")


@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b


@mcp.tool()
def echo(message: str) -> str:
    return f"echo: {message}"


if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host=STREAMABLE_HTTP_HOST,
        port=STREAMABLE_HTTP_PORT,
    )

コード解説（app.py）

FastAPI の lifespan（アプリの起動から終了までの寿命に合わせて資源を管理する仕組み）の中で MCPServerManager を使います。

@asynccontextmanager
async def lifespan(app: FastAPI):
    server = MCPServerStreamableHttp({"url": MCP_SERVER_URL})
    inactive_server = MCPServerStreamableHttp({"url": INACTIVE_MCP_SERVER_URL})
    servers = [server, inactive_server]
    if USE_MCP_MANAGER:
        async with MCPServerManager(
            servers=servers,
            connect_in_parallel=True,
        ) as manager:
            app.state.mcp_manager = manager
            app.state.mcp_servers = servers
            yield
        return

重要なのは、わざと存在しないサーバー（http://localhost:8001/mcp、inactive_server）も登録している点です。MCPServerManager は次の振る舞いをします。

• 登録された全サーバーへの接続を試み、成功したものだけを manager.active_servers として公開する（既定の drop_failed_servers=True の動作）
• 失敗したサーバーは manager.failed_servers と manager.errors に記録される。既定（strict=False）では一部の接続失敗でアプリ全体は落ちない
• connect_in_parallel=True でサーバーごとの接続を並行実行する
• reconnect(failed_only=True) で失敗したサーバーだけ再接続を試みられる

つまり「10 個の MCP サーバーのうち 1 個が落ちていてもサービスは残り 9 個で動き続け、後から復旧を試みる」という、実運用に必須の耐障害性が手に入ります。

エンドポイントでは active_servers を Agent に渡します。

    agent = Agent(
        name="FastAPI Agent",
        instructions="Use the MCP tools when needed.",
        mcp_servers=servers,
        model_settings=ModelSettings(tool_choice="auto"),
    )
    result = await Runner.run(starting_agent=agent, input=req.input)
    return {"output": result.final_output}

また /add エンドポイントでは、Agent を介さずサーバーのツールを直接呼ぶ方法も示しています。

    result = await active_servers[0].call_tool("add", {"a": req.a, "b": req.b})

call_tool(ツール名, 引数の辞書) は、LLM を使わずに MCP ツールを直接実行する低レベル API です。

実行手順

FastAPI は uv sync で開発依存として導入済みのため、追加インストールは不要です。ターミナルを 2 つ使います。

1. ターミナル 1: MCP サーバーを起動します（http://localhost:8000/mcp で待ち受けます）

uv run python examples/mcp/manager_example/mcp_server.py

2. ターミナル 2: FastAPI アプリを起動します（http://127.0.0.1:9001 で待ち受けます）

uv run python examples/mcp/manager_example/app.py

3. ターミナル 3（またはターミナル 2 を空けて）: 各エンドポイントを curl で叩きます

curl http://127.0.0.1:9001/health
curl http://127.0.0.1:9001/tools
curl -X POST http://127.0.0.1:9001/add \
  -H 'Content-Type: application/json' \
  -d '{"a": 2, "b": 3}'

4. LLM を使う /run を試す場合は、ターミナル 2 で OPENAI_API_KEY を設定してからアプリを起動し、次を実行します

curl -X POST http://127.0.0.1:9001/run \
  -H 'Content-Type: application/json' \
  -d '{"input": "Add 4 and 9."}'

5. 失敗中のサーバーの再接続を試すには次を実行します

curl -X POST http://127.0.0.1:9001/reconnect \
  -H 'Content-Type: application/json' \
  -d '{"failed_only": true}'

6. モデルなしで統合全体を検証したい場合はスモークテストを実行します（サーバーの起動も自動で行われるため、これは単独で動きます）

uv run python -m examples.mcp.manager_example.smoke_test

期待される動作・出力例

/health のレスポンスで、接続に成功したサーバーと失敗したサーバーが区別されていることを確認できます。

{"connected_servers": ["streamable_http: http://localhost:8000/mcp"], "failed_servers": ["streamable_http: http://localhost:8001/mcp"]}

/add は MCP ツールの生の実行結果（5 を含むコンテンツ）を返し、/run は Agent が add ツールを使って導いた自然文の回答（13）を返します。スモークテストは最後に MCP manager example smoke test completed successfully. と表示します。

つまずきポイント

• アプリより先に MCP サーバーを起動してください。逆順だと、起動時接続に失敗して failed_servers に入ります（その場合も /reconnect で復旧できます。これ自体が良い実験になります）
• ポート 8000 や 9001 が他のプロセスに使われていると起動に失敗します。STREAMABLE_HTTP_PORT と MCP_SERVER_URL を揃えて変更してください
• USE_MCP_MANAGER=0 を設定するとマネージャーなしの素朴な接続管理に切り替わり、比較ができます

MCPServerManager が複数サーバーの接続状態をどう管理するかをまとめると、次のようになります。

まとめ

• MCP は「AI アプリケーションの USB-C」と呼ばれる標準プロトコルで、一度作られた MCP サーバーのツールをどのクライアントからでも再利用できます
• SDK では MCPServerStdio（ローカルサブプロセス）、MCPServerSse（SSE。非推奨）、MCPServerStreamableHttp（HTTP 系の推奨方式）の 3 クラスでサーバーに接続し、Agent の mcp_servers に渡すだけで統合できます
• stdio 系 example では npx（Node.js）や uvx（uv 同梱）で公式配布のサーバーを起動します。前提ツールの有無を最初に確認しましょう
• リモート接続では timeout / sse_read_timeout / max_retry_attempts / retry_backoff_seconds_base などの堅牢化オプションが重要です。特殊なネットワーク要件には httpx_client_factory で対応します
• tool_filter（create_static_tool_filter）でツールの公開範囲を絞り、require_approval + interruptions / approve / reject で人間の承認を挟めます。安全な MCP 運用の基本形です
• MCP サーバーはツールのほかプロンプトも提供でき、list_prompts() / get_prompt() で Agent の instructions を動的に生成できます
• 複数サーバーの本番運用では MCPServerManager が接続の成否を管理し、一部サーバーの障害時もサービスを継続できます

理解度チェック

解答と解説

参考リンク

• Model context protocol (MCP)（公式ドキュメント） / 日本語版
• Tools（公式ドキュメント） / 日本語版
• Human-in-the-loop（公式ドキュメント） / 日本語版
• Tracing（公式ドキュメント） / 日本語版
• Examples 一覧（公式ドキュメント） / 日本語版
• Model Context Protocol 公式サイト
• examples/mcp（GitHub）

第7章 ホスト型 MCP（hosted_mcp）

前提知識

この章を読む前に、以下の章の内容を理解しておいてください。

• 第1章: 環境構築（git clone → uv sync）と OPENAI_API_KEY の設定方法
• 第2章: Agent と Runner の基本的な使い方（Runner.run() / Runner.run_streamed()）
• 第6章: MCP（Model Context Protocol）の基本概念と、ローカル MCP サーバー（MCPServerStdio 等）を Agent(mcp_servers=[...]) で接続する方法

特に第6章の「MCP は AI アプリケーションにとっての USB-C ポートのような共通規格」というイメージは、この章でもそのまま使います。

概念解説

ローカル MCP とホスト型 MCP — 「誰が電話をかけるか」の違い

第6章で学んだローカル MCP では、あなたの Python プログラムが MCP サーバーに接続していました。プログラムがサーバーを起動（または接続）し、ツール一覧を取得し、モデルがツールを使いたいと言うたびにあなたのプログラムがツールを呼び出して結果をモデルに返す、という往復が発生します。

一方、この章で扱うホスト型 MCP（hosted MCP）では、接続するのは OpenAI のサーバー側です。あなたのプログラムは HostedMCPTool というツール定義を通じて「このラベルの MCP サーバーをこの URL で使ってください」という設定情報だけを OpenAI の Responses API（OpenAI のモデル呼び出し API。エージェント向けの新しい API 形式です）に渡します。すると、ツール一覧の取得もツールの実行も、すべて OpenAI のインフラ内で完結します。あなたの Python プロセスへの折り返し（round trip）は発生しません。

日常の比喩で言えば、ローカル MCP は「自分で専門家に電話をかけて質問し、回答をアシスタントに伝える」方式です。ホスト型 MCP は「アシスタントに専門家の電話番号を渡して、アシスタント自身に電話をかけてもらう」方式です。自分は取り次ぎ作業から解放されますが、その代わり会話の中身は直接には見えなくなります。

これを図にすると次のようになります。

SDK のソースコード（src/agents/tool.py）でも、HostedMCPTool は次のように説明されています。

A tool that allows the LLM to use a remote MCP server. The LLM will automatically list and call tools, without requiring a round trip back to your code.

両者の違いを表にまとめます。

表の最後の行にある「DeepWiki」と「OpenAI connectors」は、tool_config の書き方も少し異なります。図にすると次のとおりです。

重要な注意点として、ホスト型 MCP では Agent の mcp_servers 引数は使いません。HostedMCPTool は WebSearchTool などと同じ「OpenAI がホストするツール」の一種なので、tools リストに追加します。

approval（承認）フロー — 勝手にツールを実行させないための仕組み

ホスト型 MCP ではツール実行が OpenAI 側で完結するため、放っておくとモデルが外部サーバーのツールをあなたの確認なしに実行できてしまいます。信頼できるサーバーなら問題ありませんが、機密性の高い操作（カレンダーの書き換え、ファイルの削除など）ができるサーバーでは危険です。

そこで tool_config の require_approval で承認ポリシーを設定します。この章の example は、承認の扱い方の 3 パターンをちょうど 1 つずつ見せてくれます。

1. 承認なし（"require_approval": "never"） — 信頼できるサーバー専用。ツールは即座に実行されます（simple.py / connectors.py）
2. コールバックで承認（"always" + on_approval_request） — 承認が必要になるたびに、あなたが用意した Python 関数（コールバック。あるイベントが起きたときに呼び出してもらう関数のことです）が呼ばれ、その戻り値で承認/拒否が決まります（on_approval.py）
3. interruption（中断）で承認 — コールバックを渡さない場合、実行は承認待ちの状態でいったん停止します。返ってきた結果の interruptions を確認し、approve() / reject() を呼んでから実行を再開します（human_in_the_loop.py）

require_approval には "always" / "never" のほか、ツール名ごとにポリシーを変える辞書も指定できます（公式ドキュメント docs/mcp.md 参照）。

3 パターンを図にまとめると、次のようになります。

connectors — Google カレンダー等の「認証つき既製サーバー」

ホスト型 MCP のもう 1 つの形態が OpenAI connectors（コネクタ）です。Google カレンダー・Gmail・Dropbox のような主要 SaaS について、OpenAI が MCP サーバー相当の接続口をあらかじめ用意してくれています。この場合は server_url の代わりに connector_id（例: connector_googlecalendar）と、そのサービスにアクセスするためのアクセストークン（本人に代わって API を呼び出す許可証となる文字列）を authorization に渡します。

比喩で言えば、通常のホスト型 MCP が「専門家の電話番号を渡す」方式だとすると、connectors は「OpenAI が既に提携している専門家窓口を、あなたの会員証（アクセストークン）を添えて利用する」方式です。認証まわりの面倒な処理は Responses API が引き受けてくれます。

各 example の解説

この章の example は examples/hosted_mcp/ ディレクトリにあります。全 example に共通して、公開 MCP サーバーの実例として DeepWiki（https://mcp.deepwiki.com/mcp）が使われています。DeepWiki は GitHub リポジトリの内容について質問に答えてくれる公開 MCP サーバーで、API キー等の認証は不要です。

また、全 example が --stream フラグ（ストリーミング: 結果を一括ではなく、生成されるそばから少しずつ受け取る方式）と --verbose フラグ（実行中の項目を詳細表示）を持つ、共通のコマンドライン構造になっています。

simple.py

承認なし（require_approval: "never"）でホスト型 MCP を使う、最小構成の example です。DeepWiki に「このリポジトリは何の言語で書かれていますか？」と質問します。

コード解説

エージェント定義の中心部分です。

from agents import Agent, HostedMCPTool, ModelSettings, Runner, RunResult, RunResultStreaming

async def main(verbose: bool, stream: bool, repo: str):
    question = f"Which language is the repository {repo} written in?"
    agent = Agent(
        name="Assistant",
        instructions=f"You can use the DeepWiki hosted MCP server to inspect {repo}.",
        model_settings=ModelSettings(tool_choice="required"),
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "deepwiki",
                    "server_url": "https://mcp.deepwiki.com/mcp",
                    "require_approval": "never",
                }
            )
        ],
    )

• HostedMCPTool は tools リストに追加します。tool_config は Responses API に REST で送る JSON と同じ形式の辞書で、"type": "mcp" が必須です
• server_label はこのサーバーを識別するラベル、server_url は公開 URL です
• "require_approval": "never" は「承認不要」の宣言です。ソースコード冒頭のコメントに "You should only use this for trusted MCP servers."（信頼できる MCP サーバーに対してのみ使うこと）とある通り、信頼できるサーバー限定の設定です
• ModelSettings(tool_choice="required") は「モデルは必ず何らかのツールを使うこと」という指定です。これがないと、モデルがツールを使わずに記憶だけで答えてしまう可能性があります

実行部分は、ストリーミングの有無で分岐します。

    run_result: RunResult | RunResultStreaming
    if stream:
        run_result = Runner.run_streamed(agent, question)
        async for event in run_result.stream_events():
            if event.type == "run_item_stream_event":
                print(f"Got event of type {event.item.__class__.__name__}")
        print(f"Done streaming; final result: {run_result.final_output}")
    else:
        run_result = await Runner.run(agent, question)
        print(run_result.final_output)
        # The repository is primarily written in Python...

ホスト型 MCP はストリーミングにも通常のツールと同じように対応しており、run_item_stream_event として MCP のツール一覧取得やツール呼び出しのイベントが流れてきます。

コマンドライン引数として --repo で調査対象リポジトリを変更できます（デフォルトは https://github.com/openai/openai-agents-python）。

実行手順

1. リポジトリのルートディレクトリにいることを確認します（第1章の手順で uv sync 済みの前提です）
2. 環境変数 OPENAI_API_KEY を設定します: export OPENAI_API_KEY=sk-...
3. 次のコマンドで実行します

uv run python -m examples.hosted_mcp.simple

4. ストリーミングで実行する場合は --stream、実行項目の詳細を見る場合は --verbose を付けます

uv run python -m examples.hosted_mcp.simple --stream
uv run python -m examples.hosted_mcp.simple --repo https://github.com/openai/codex

期待される動作・出力例

DeepWiki への問い合わせが OpenAI 側で実行され、承認プロンプトなしで最終回答が表示されます。コード中のコメントにある通り、デフォルトのリポジトリでは次のような出力になります。

The repository is primarily written in Python...

--stream を付けた場合は、ToolCallItem や MessageOutputItem などのイベント型名が順に表示された後、最終結果が表示されます。

つまずきポイント

• 実行にはインターネット接続が必要です。DeepWiki サーバーや対象リポジトリの状態によっては応答に時間がかかることがあります
• uv run python examples/hosted_mcp/simple.py でも動作しますが、この章では他の example（examples.auto_mode を import するためパッケージとして実行する必要があるもの）と合わせて -m 形式に統一しています

on_approval.py

require_approval: "always" と on_approval_request コールバックを組み合わせ、ツール実行のたびに Python 関数で承認可否を判断する example です。実行の流れを止めずに、プログラム側で承認を処理できます。

コード解説

まず承認コールバック関数です。

from agents import (
    Agent,
    HostedMCPTool,
    MCPToolApprovalFunctionResult,
    MCPToolApprovalRequest,
    Runner,
    RunResult,
    RunResultStreaming,
)
from examples.auto_mode import confirm_with_fallback


def prompt_approval(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
    params: object = request.data.arguments or {}
    approved = confirm_with_fallback(
        f"Approve running tool (mcp: {request.data.name}, params: {json.dumps(params)})? (y/n) ",
        default=True,
    )
    result: MCPToolApprovalFunctionResult = {"approve": approved}
    if not approved:
        result["reason"] = "User denied"
    return result

• MCPToolApprovalRequest は承認リクエストを表すクラスで、request.data.name（呼び出そうとしているツール名）と request.data.arguments（引数）が参照できます
• 戻り値の MCPToolApprovalFunctionResult は {"approve": bool} 形式の辞書（正確には TypedDict）で、拒否時には任意で "reason"（拒否理由。モデルに伝わります）を添えられます
• confirm_with_fallback は examples 共通のヘルパーで、通常はターミナルで y/n の入力を求め、環境変数 EXAMPLES_INTERACTIVE_MODE=auto が設定されているときは自動でデフォルト値（ここでは承認）を返します
• コールバックは同期関数でも非同期関数（async def）でも構いません

エージェント定義では、このコールバックを HostedMCPTool に渡します。

    agent = Agent(
        name="MCP Assistant",
        instructions=(
            "You must always use the MCP tools to answer questions. "
            "Use the DeepWiki hosted MCP server to answer questions and do not ask the user for "
            "additional configuration."
        ),
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "deepwiki",
                    "server_url": "https://mcp.deepwiki.com/mcp",
                    "allowed_tools": ["ask_question"],
                    "require_approval": require_approval,
                },
                on_approval_request=prompt_approval,
            )
        ],
    )

require_approval には "always" が入っています。ポイントは、承認ポリシーは tool_config の中（API に送られる設定）、コールバックは HostedMCPTool の引数（SDK がローカルで処理）という役割分担です。承認が要求されるたびに SDK が prompt_approval を呼び、その結果を API に返して実行を継続します。また "allowed_tools": ["ask_question"] は、サーバーが公開する複数のツールのうち ask_question だけをモデルに見せる絞り込みです。承認デモが余計なツール呼び出しに逸れないようにする指定で、承認ポリシーと同じく API に送られる tool_config 側の設定です。

非ストリーミング側の実行部分には、念のための再開ループも書かれています。

    else:
        run_result = await Runner.run(agent, question)
        while run_result.interruptions:
            run_result = await Runner.run(agent, run_result.to_state())
        print(run_result.final_output)

コールバックを渡している場合、承認は実行中に処理されるため通常このループは回りませんが、コールバックで処理されなかった承認要求が interruptions として残った場合に、状態を引き継いで再実行する保険として機能します（この仕組み自体は次の human_in_the_loop.py で詳しく学びます）。

実行手順

1. 環境変数 OPENAI_API_KEY を設定します
2. 次のコマンドで実行します

uv run python -m examples.hosted_mcp.on_approval

3. ツール呼び出しごとに Approve running tool (mcp: ask_question, params: {...})? (y/n) と聞かれるので、y を入力して承認します
4. 対話なしで自動実行したい場合は、環境変数を付けて実行します

EXAMPLES_INTERACTIVE_MODE=auto uv run python -m examples.hosted_mcp.on_approval

期待される動作・出力例

「openai/codex リポジトリは何の言語で書かれているか」という質問に対し、DeepWiki のツール呼び出し前に承認プロンプトが表示されます。承認すると最終回答（Rust が主要言語である旨）が表示されます。n で拒否すると {"approve": False, "reason": "User denied"} がモデルに伝わり、モデルはツール結果なしで応答を組み立てようとします。

つまずきポイント

• この example は from examples.auto_mode import confirm_with_fallback とパッケージ内 import をしているため、必ずリポジトリルートから -m 形式で実行してください。uv run python examples/hosted_mcp/on_approval.py は ModuleNotFoundError: No module named 'examples' で失敗します
• --stream 指定時も承認プロンプトはコールバック経由で出ます。ストリーミング出力の途中にプロンプトが混ざって見えることがありますが、動作としては正常です

human_in_the_loop.py

コールバックを使わず、interruption（中断）ベースで人間の承認を挟む example です。human-in-the-loop（ヒューマン・イン・ザ・ループ）とは、自動処理の途中に人間の判断ポイントを組み込む設計パターンのことです。承認待ちで実行がいったん「停止」し、承認/拒否を記録してから「再開」する、という 2 段階の流れを学びます。

コード解説

エージェント定義には、これまでにない要素が 2 つあります。

from agents.model_settings import MCPToolChoice

    agent = Agent(
        name="MCP Assistant",
        instructions=(
            "You must always use the MCP tools to answer questions. "
            "Use the DeepWiki hosted MCP server to answer questions and do not ask the user for "
            "additional configuration."
        ),
        model_settings=ModelSettings(
            tool_choice=MCPToolChoice(server_label="deepwiki", name="ask_question")
        ),
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "deepwiki",
                    "server_url": "https://mcp.deepwiki.com/mcp",
                    "require_approval": require_approval,
                }
            )
        ],
    )
    resume_config = RunConfig(model_settings=ModelSettings(tool_choice="auto"))

• MCPToolChoice(server_label="deepwiki", name="ask_question") は、"required"（何かしらのツールを使え）よりさらに踏み込んで、「deepwiki サーバーの ask_question という特定のツールを使え」と強制する指定です
• HostedMCPTool に on_approval_request を渡していない点が on_approval.py との違いです。require_approval: "always" なのにコールバックがないため、承認が必要になった時点で実行が中断します
• resume_config は再開時に使う RunConfig（実行単位の設定）で、tool_choice="auto" に緩めています。承認後の再開時にもツール強制が残っていると、モデルが回答を出す代わりに同じツールを何度も呼ぼうとしてしまうためです（コード中のコメントにもその旨が書かれています）

中断と再開のループが、この example の核心です（非ストリーミング側）。

        run_result = await Runner.run(agent, question, max_turns=100)
        while run_result.interruptions:
            state = run_result.to_state()
            for interruption in run_result.interruptions:
                approved = prompt_for_interruption(interruption.name, interruption.arguments)
                if approved:
                    state.approve(interruption)
                else:
                    state.reject(interruption)
            run_result = await Runner.run(
                agent,
                state,
                max_turns=100,
                run_config=resume_config,
            )
        print(run_result.final_output)

流れを整理します。

1. Runner.run() を普通に実行します。承認が必要になると、実行はそこで止まり、結果の run_result.interruptions に承認待ちのツール呼び出し（ToolApprovalItem のリスト）が入ります
2. run_result.to_state() で、実行の途中状態を表す RunState オブジェクトを取り出します
3. 各 interruption について、state.approve(interruption) または state.reject(interruption) で判断を記録します
4. Runner.run(agent, state, ...) に入力文字列の代わりに state を渡すと、中断した箇所から実行が再開されます
5. 再開後にまた承認が必要になるかもしれないので、interruptions が空になるまで while で繰り返します

ストリーミング版（Runner.run_streamed）でもまったく同じパターンで、stream_result.to_state() → approve/reject → Runner.run_streamed(agent, state, ...) と再開します。

承認プロンプト用のヘルパー prompt_for_interruption は、ツール名と引数（JSON 文字列の場合はパースして）を表示して y/n を尋ねる関数です。EOFError / KeyboardInterrupt（Ctrl+C 等）が起きた場合は拒否扱いにする防御的な実装になっています。

実行手順

1. 環境変数 OPENAI_API_KEY を設定します
2. 次のコマンドで実行します（パッケージ内 import があるため -m 形式必須）

uv run python -m examples.hosted_mcp.human_in_the_loop

3. Approve running tool (mcp: ask_question, params: {...})? (y/n) と表示されたら y を入力します
4. 対話なしで試す場合は EXAMPLES_INTERACTIVE_MODE=auto を付けます

EXAMPLES_INTERACTIVE_MODE=auto uv run python -m examples.hosted_mcp.human_in_the_loop --stream

期待される動作・出力例

DeepWiki の ask_question ツール呼び出し前に実行が中断し、承認プロンプトが表示されます。承認すると実行が再開され、「openai/codex は主に Rust で書かれている」という趣旨の最終回答が表示されます。--stream の場合は回答テキストが少しずつ流れた後、Done streaming; final result: ... が表示されます。

つまずきポイント

• on_approval.py（コールバック方式）とこの example（interruption 方式）の使い分け: コールバック方式は「その場で機械的に判断できる」場合（許可リスト照合など）に向き、interruption 方式は「状態をいったん保存して、別の場所・別のタイミングで人間が判断する」場合（Web アプリで承認画面を出す等）に向きます
• 再開時に run_config=resume_config を渡し忘れると、MCPToolChoice によるツール強制が効いたままになり、モデルがツール呼び出し→承認→ツール呼び出し…を繰り返して max_turns（実行ループの上限回数。この example では 100 に引き上げられています）に達するおそれがあります
• state.approve() には always_approve=True という引数もあり、同じツールを以後ずっと自動承認にできます（src/agents/run_state.py 参照）

この中断・再開の流れを図にすると次のようになります。

connectors.py

OpenAI connectors を使って、Google カレンダーにホスト型 MCP としてアクセスする example です。「今日の予定は？」という質問にエージェントが答えます。

コード解説

HostedMCPTool の設定が、これまでの server_url 方式と異なります。

async def main(verbose: bool, stream: bool):
    # 1. Visit https://developers.google.com/oauthplayground/
    # 2. Input https://www.googleapis.com/auth/calendar.events as the required scope
    # 3. Grab the access token starting with "ya29."
    authorization = os.environ["GOOGLE_CALENDAR_AUTHORIZATION"]
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant that can help a user with their calendar.",
        tools=[
            HostedMCPTool(
                tool_config={
                    "type": "mcp",
                    "server_label": "google_calendar",
                    # see https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors
                    "connector_id": "connector_googlecalendar",
                    "authorization": authorization,
                    "require_approval": "never",
                }
            )
        ],
    )

• server_url の代わりに connector_id（ここでは Google カレンダー用の connector_googlecalendar）を指定します。利用可能な connector の一覧は、コメントにある OpenAI 公式ガイド（tools-connectors-mcp）に掲載されています
• authorization には Google のアクセストークンを渡します。このトークンを使って、Responses API があなたの代わりに Google カレンダー API と通信します
• トークンはコードに直書きせず、環境変数 GOOGLE_CALENDAR_AUTHORIZATION から読み込んでいます。認証情報をソースコードに含めないのは、実務でも必ず守るべき習慣です

質問文は実行時の日付から動的に組み立てます。

    today = datetime.now().strftime("%Y-%m-%d")
    run_result: RunResult | RunResultStreaming
    if stream:
        run_result = Runner.run_streamed(agent, f"What is my schedule for {today}?")
        async for event in run_result.stream_events():
            if event.type == "raw_response_event":
                if event.data.type.startswith("response.output_item"):
                    print(json.dumps(event.data.to_dict(), indent=2))
                if event.data.type.startswith("response.mcp"):
                    print(json.dumps(event.data.to_dict(), indent=2))
                if event.data.type == "response.output_text.delta":
                    print(event.data.delta, end="", flush=True)
        print()
    else:
        run_result = await Runner.run(agent, f"What is my schedule for {today}?")
        print(run_result.final_output)

ストリーミング側では、これまでの example より一段低いレイヤーの raw_response_event（Responses API から届く生イベント）を観察しています。response.mcp で始まるイベント（MCP ツール一覧の取得やツール呼び出しの進行状況）を JSON で表示するので、ホスト型 MCP の内部動作を学ぶのに便利です。

実行手順

この example だけは、Google のアクセストークンという事前準備が必要です。コード内のコメントに沿って進めます。

1. ブラウザで Google OAuth 2.0 Playground を開きます
2. Step 1 のスコープ入力欄に https://www.googleapis.com/auth/calendar.events を入力し、「Authorize APIs」で自分の Google アカウントを認可します
3. Step 2 の「Exchange authorization code for tokens」を押し、表示される ya29. で始まるアクセストークンをコピーします
4. 環境変数を設定します

export OPENAI_API_KEY=sk-...
export GOOGLE_CALENDAR_AUTHORIZATION=ya29....

5. 実行します

uv run python -m examples.hosted_mcp.connectors
uv run python -m examples.hosted_mcp.connectors --stream

期待される動作・出力例

エージェントが Google カレンダーの connector 経由で当日の予定を検索し、「今日の予定は 10 時からのミーティングが 1 件です」のような自然文で答えます。予定が何もない日であれば「本日の予定は登録されていません」といった回答になります。--stream では response.mcp_list_tools や response.mcp_call 系のイベント JSON が先に流れ、最後に回答テキストが表示されます。

つまずきポイント

• アクセストークンは短時間（通常 1 時間程度）で失効します。実行時に認証エラーが出たら、OAuth Playground でトークンを取得し直してください。OAuth Playground はあくまで学習・検証用であり、本番アプリでは正式な OAuth フロー（refresh token による更新等）を実装する必要があります
• GOOGLE_CALENDAR_AUTHORIZATION が未設定だと、os.environ[...] の時点で KeyError になります
• スコープを間違える（例: calendar.readonly にする）と、connector が必要とする操作が許可されずエラーになることがあります。コメント指定どおり calendar.events を使ってください
• デバッグしたいときは、ファイル冒頭のコメントアウトされた logging.basicConfig(level=logging.DEBUG) を有効にすると通信の詳細が見えます

connectors の認証仲介を図にすると次のとおりです。

まとめ

• ホスト型 MCP（HostedMCPTool）は、MCP サーバーへの接続とツール実行を OpenAI のサーバー側に任せる方式です。ローカル MCP（第6章）と違い、あなたのコードへの往復なしにツールが実行されます
• HostedMCPTool は Agent(tools=[...]) に追加し、tool_config に "type": "mcp"、server_label、server_url（または connector_id + authorization）、require_approval を指定します
• 承認フローは 3 パターン: 承認なし（"never"、信頼できるサーバー限定）、コールバック承認（on_approval_request で {"approve": bool} を返す）、interruption 承認（result.interruptions → to_state() → approve()/reject() → state を渡して再実行）
• connectors は Google カレンダー等の既製サービス向けで、connector_id とアクセストークンを渡すと Responses API が認証を仲介してくれます。トークンは環境変数で渡し、コードに直書きしません
• ModelSettings の tool_choice は "required"（何かツールを使う）だけでなく、MCPToolChoice(server_label=..., name=...) で特定 MCP ツールの使用を強制できます。中断からの再開時は RunConfig で "auto" に戻すのが定石です

理解度チェック