openai-agents 0.2.8__tar.gz → 0.2.10__tar.gz

{openai_agents-0.2.8 → openai_agents-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.2.8
+Version: 0.2.10
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -21,7 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.11.0; python_version >= '3.10'
-Requires-Dist: openai<2,>=1.99.6
+Requires-Dist: openai<2,>=1.102.0
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
@@ -30,6 +30,9 @@ Provides-Extra: litellm
 Requires-Dist: litellm<2,>=1.67.4.post1; extra == 'litellm'
 Provides-Extra: realtime
 Requires-Dist: websockets<16,>=15.0; extra == 'realtime'
+Provides-Extra: sqlalchemy
+Requires-Dist: asyncpg>=0.29.0; extra == 'sqlalchemy'
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
 Provides-Extra: viz
 Requires-Dist: graphviz>=0.17; extra == 'viz'
 Provides-Extra: voice
@@ -58,29 +61,28 @@ Explore the [examples](examples) directory to see the SDK in action, and read ou
 
 ## Get started
 
-1. Set up your Python environment
+To get started, set up your Python environment (Python 3.9 or newer required), and then install OpenAI Agents SDK package.
 
--   Option A: Using venv (traditional method)
+### venv
 
 ```bash
-python -m venv env
-source env/bin/activate  # On Windows: env\Scripts\activate
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install openai-agents
 ```
 
--   Option B: Using uv (recommended)
+For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
 
-```bash
-uv venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-```
+### uv
 
-2. Install Agents SDK
+If you're familiar with [uv](https://docs.astral.sh/uv/), using the tool would be even similar:
 
 ```bash
-pip install openai-agents
+uv init
+uv add openai-agents
 ```
 
-For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
+For voice support, install with the optional `voice` group: `uv add 'openai-agents[voice]'`.
 
 ## Hello world example
 

{openai_agents-0.2.8 → openai_agents-0.2.10}/README.md

@@ -19,29 +19,28 @@ Explore the [examples](examples) directory to see the SDK in action, and read ou
 
 ## Get started
 
-1. Set up your Python environment
+To get started, set up your Python environment (Python 3.9 or newer required), and then install OpenAI Agents SDK package.
 
--   Option A: Using venv (traditional method)
+### venv
 
 ```bash
-python -m venv env
-source env/bin/activate  # On Windows: env\Scripts\activate
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install openai-agents
 ```
 
--   Option B: Using uv (recommended)
+For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
 
-```bash
-uv venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-```
+### uv
 
-2. Install Agents SDK
+If you're familiar with [uv](https://docs.astral.sh/uv/), using the tool would be even similar:
 
 ```bash
-pip install openai-agents
+uv init
+uv add openai-agents
 ```
 
-For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
+For voice support, install with the optional `voice` group: `uv add 'openai-agents[voice]'`.
 
 ## Hello world example
 

{openai_agents-0.2.8 → openai_agents-0.2.10}/docs/ja/agents.md

@@ -4,16 +4,16 @@ search:
 ---
 # エージェント
 
-エージェントはアプリにおける中核的な構成要素です。エージェントは、 instructions と tools で構成された大規模言語モデル ( LLM ) です。
+エージェントはアプリの中核となる構成要素です。エージェントは、instructions とツールで構成された大規模言語モデル（LLM）です。
 
-## 基本構成
+## 基本設定
 
 エージェントで最も一般的に設定するプロパティは次のとおりです。
 
--   `name`: エージェントを識別する必須の文字列です。
--   `instructions`: developer メッセージ、または system prompt とも呼ばれます。
--   `model`: 使用する LLM と、 temperature、 top_p などのモデル調整パラメーターを設定する任意の `model_settings`。
--   `tools`: エージェントがタスク達成のために使用できるツールです。
+-   `name`: エージェントを識別する必須の文字列。
+-   `instructions`: developer message または system prompt としても知られます。
+-   `model`: 使用する LLM、および temperature、top_p などのモデル調整パラメーターを設定する任意の `model_settings`。
+-   `tools`: エージェントがタスク達成のために使用できるツール。
 
 ```python
 from agents import Agent, ModelSettings, function_tool
@@ -33,7 +33,7 @@ agent = Agent(
 
 ## コンテキスト
 
-エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態をまとめたものとして機能します。コンテキストには任意の Python オブジェクトを提供できます。
+エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行に必要な依存関係と状態をまとめて保持します。コンテキストとしては任意の Python オブジェクトを提供できます。
 
 ```python
 @dataclass
@@ -52,7 +52,7 @@ agent = Agent[UserContext](
 
 ## 出力タイプ
 
-既定では、エージェントはプレーンテキスト ( `str` ) を出力します。特定のタイプの出力を生成したい場合は、 `output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトの使用ですが、 Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型 ( dataclass、 list、 TypedDict など ) をサポートします。
+デフォルトでは、エージェントはプレーンテキスト（`str`）出力を生成します。特定のタイプの出力をエージェントに生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択は [Pydantic](https://docs.pydantic.dev/) オブジェクトの使用ですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型（dataclasses、list、TypedDict など）をサポートします。
 
 ```python
 from pydantic import BaseModel
@@ -73,11 +73,11 @@ agent = Agent(
 
 !!! note
 
-    `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。
+    `output_type` を渡すと、通常のプレーンテキスト応答ではなく、モデルに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示します。
 
 ## ハンドオフ
 
-ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、関連がある場合にエージェントはそれらへ委譲できます。これは、単一のタスクに特化したモジュール式のエージェントをオーケストレーションする強力なパターンです。詳しくは [handoffs](handoffs.md) のドキュメントを参照してください。
+ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを提供すると、エージェントは関連があればそれらに委任できます。これは、単一のタスクに特化して優れた、モジュール式で専門特化したエージェントをオーケストレーションする強力なパターンです。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。
 
 ```python
 from agents import Agent
@@ -98,7 +98,7 @@ triage_agent = Agent(
 
 ## 動的 instructions
 
-多くの場合、エージェント作成時に instructions を指定しますが、関数を通じて動的な instructions を提供することもできます。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が利用可能です。
+多くの場合、エージェント作成時に instructions を指定できますが、関数経由で動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも利用できます。
 
 ```python
 def dynamic_instructions(
@@ -113,17 +113,17 @@ agent = Agent[UserContext](
 )
 ```
 
-## ライフサイクルイベント (フック)
+## ライフサイクルイベント（hooks）
 
-エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログ記録したい、または特定のイベント発生時にデータを事前取得したい場合です。 `hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。
+ときには、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントを記録したり、特定のイベント発生時にデータを事前取得したりします。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。
 
 ## ガードレール
 
-ガードレールにより、エージェント実行と並行してユーザー入力に対するチェックや検証を行い、生成後のエージェント出力にも同様の処理を行えます。たとえば、ユーザー入力やエージェント出力の関連性をスクリーニングできます。詳しくは [guardrails](guardrails.md) のドキュメントを参照してください。
+ガードレールにより、エージェントの実行と並行して ユーザー入力 に対するチェック/検証を行い、またエージェントの出力が生成された後にもチェックを行えます。たとえば、ユーザー入力とエージェント出力の関連性をスクリーニングできます。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。
 
 ## エージェントのクローン/コピー
 
-エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
+エージェントの `clone()` メソッドを使うと、エージェントを複製し、任意で好きなプロパティを変更できます。
 
 ```python
 pirate_agent = Agent(
@@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone(
 
 ## ツール使用の強制
 
-ツールのリストを指定しても、 LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです。
+ツールのリストを提供しても、LLM が必ずツールを使うとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです。
 
-1. `auto`: ツールを使用するかどうかを LLM に委ねます。
-2. `required`: LLM にツールの使用を要求します ( どのツールを使うかは賢く選択できます )。
-3. `none`: ツールを使用しないことを要求します。
-4. 特定の文字列 ( 例: `my_tool` ) を設定: LLM にその特定のツールの使用を要求します。
+1. `auto`: ツールを使用するかどうかを LLM に任せます。
+2. `required`: ツールの使用を必須にします（ただしどのツールを使うかは賢く選べます）。
+3. `none`: ツールを使用「しない」ことを必須にします。
+4. 具体的な文字列（例: `my_tool`）を設定すると、その特定のツールの使用を必須にします。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -163,11 +163,11 @@ agent = Agent(
 )
 ```
 
-## ツール使用の挙動
+## ツール使用の動作
 
-`Agent` の構成にある `tool_use_behavior` パラメーターは、ツール出力の処理方法を制御します。
-- `"run_llm_again"`: 既定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。
-- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしに最終応答として使用します。
+`Agent` の設定にある `tool_use_behavior` パラメーターは、ツール出力の扱いを制御します。
+- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。
+- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしで最終応答として使用します。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -185,7 +185,7 @@ agent = Agent(
 )
 ```
 
-- `StopAtTools(stop_at_tool_names=[...])`: 指定されたいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。
+- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。
 ```python
 from agents import Agent, Runner, function_tool
 from agents.agent import StopAtTools
@@ -207,7 +207,7 @@ agent = Agent(
     tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
 )
 ```
-- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。
+- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM 継続かを判断するカスタム関数。
 
 ```python
 from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -245,4 +245,4 @@ agent = Agent(
 
 !!! note
 
-    無限ループを防ぐため、フレームワークはツール呼び出し後に自動的に `tool_choice` を "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが起きるのは、ツール結果が LLM に送られ、`tool_choice` のために LLM が再びツール呼び出しを生成し続けるためです。
+    無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループは、ツール結果が LLM に送られ、`tool_choice` により LLM が再度ツール呼び出しを生成し続けることで発生します。

openai_agents-0.2.10/docs/ja/config.md

@@ -0,0 +1,98 @@
+---
+search:
+  exclude: true
+---
+# SDK の設定
+
+## API キーとクライアント
+
+デフォルトでは、SDK はインポートされるとすぐに、LLM リクエストと トレーシング のための `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。
+
+```python
+from agents import set_default_openai_key
+
+set_default_openai_key("sk-...")
+```
+
+また、使用する OpenAI クライアントを構成することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーから API キーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。
+
+```python
+from openai import AsyncOpenAI
+from agents import set_default_openai_client
+
+custom_client = AsyncOpenAI(base_url="...", api_key="...")
+set_default_openai_client(custom_client)
+```
+
+最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。[set_default_openai_api()][agents.set_default_openai_api] 関数を使用して、Chat Completions API を使うように上書きできます。
+
+```python
+from agents import set_default_openai_api
+
+set_default_openai_api("chat_completions")
+```
+
+## トレーシング
+
+トレーシング はデフォルトで有効です。デフォルトでは、上記の OpenAI API キー（つまり、環境変数または設定したデフォルトキー）を使用します。トレーシング に使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。
+
+```python
+from agents import set_tracing_export_api_key
+
+set_tracing_export_api_key("sk-...")
+```
+
+[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシング を完全に無効にすることもできます。
+
+```python
+from agents import set_tracing_disabled
+
+set_tracing_disabled(True)
+```
+
+## デバッグロギング
+
+SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。
+
+詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
+
+```python
+from agents import enable_verbose_stdout_logging
+
+enable_verbose_stdout_logging()
+```
+
+また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。
+
+```python
+import logging
+
+logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger
+
+# To make all logs show up
+logger.setLevel(logging.DEBUG)
+# To make info and above show up
+logger.setLevel(logging.INFO)
+# To make warning and above show up
+logger.setLevel(logging.WARNING)
+# etc
+
+# You can customize this as needed, but this will output to `stderr` by default
+logger.addHandler(logging.StreamHandler())
+```
+
+### ログ内の機微データ
+
+一部のログには機微データ（たとえば ユーザー データ）が含まれる場合があります。これらのデータがログに記録されないようにするには、次の環境変数を設定してください。
+
+LLM の入力と出力のロギングを無効にするには:
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
+```
+
+ツールの入力と出力のロギングを無効にするには:
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
+```

openai_agents-0.2.10/docs/ja/context.md

@@ -0,0 +1,82 @@
+---
+search:
+  exclude: true
+---
+# コンテキスト管理
+
+コンテキストは多義的な用語です。考慮すべき主なコンテキストは 2 つあります:
+
+1. コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時や `on_handoff` のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。
+2. LLM に利用できるコンテキスト: これは、LLM が応答を生成する際に参照できるデータです。
+
+## ローカルコンテキスト
+
+これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作は次のとおりです:
+
+1. 任意の Python オブジェクトを作成します。一般的なパターンは、dataclass や Pydantic オブジェクトを使うことです。
+2. そのオブジェクトを各種の実行メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。
+3. すべてのツール呼び出しやライフサイクルフックなどには、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。
+
+最も重要な点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは、同じ型のコンテキストを使わなければなりません。
+
+コンテキストは次のような用途に使えます:
+
+-   実行に関するコンテキストデータ（例: ユーザー名 / UID など、ユーザーに関する情報）
+-   依存関係（例: ロガーオブジェクト、データ取得機構など）
+-   ヘルパー関数
+
+!!! danger "Note"
+
+    コンテキストオブジェクトは LLM に送信されません。ローカルなオブジェクトであり、読み書きやメソッド呼び出しのみが可能です。
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from agents import Agent, RunContextWrapper, Runner, function_tool
+
+@dataclass
+class UserInfo:  # (1)!
+    name: str
+    uid: int
+
+@function_tool
+async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:  # (2)!
+    """Fetch the age of the user. Call this function to get user's age information."""
+    return f"The user {wrapper.context.name} is 47 years old"
+
+async def main():
+    user_info = UserInfo(name="John", uid=123)
+
+    agent = Agent[UserInfo](  # (3)!
+        name="Assistant",
+        tools=[fetch_user_age],
+    )
+
+    result = await Runner.run(  # (4)!
+        starting_agent=agent,
+        input="What is the age of the user?",
+        context=user_info,
+    )
+
+    print(result.final_output)  # (5)!
+    # The user John is 47 years old.
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。
+2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っているのが分かります。ツールの実装はコンテキストから読み取ります。
+3. 型チェッカーがエラーを検出できるように、エージェントにジェネリクス `UserInfo` を指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。
+4. コンテキストは `run` 関数に渡されます。
+5. エージェントはツールを正しく呼び出して年齢を取得します。
+
+## エージェント / LLM のコンテキスト
+
+LLM が呼び出されると、参照できるのは会話履歴にあるデータのみです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できる形で提供する必要があります。方法はいくつかあります:
+
+1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でもかまいません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。
+2. `Runner.run` 関数を呼び出す際の `input` に追加します。これは `instructions` の手法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できます。
+3. 関数ツール経由で公開します。これはオンデマンドのコンテキストに有用で、LLM が必要に応じてツールを呼び出してデータを取得できます。
+4. リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）や Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに役立ちます。

openai_agents-0.2.10/docs/ja/examples.md

@@ -0,0 +1,47 @@
+---
+search:
+  exclude: true
+---
+# コード例
+
+[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。
+
+## カテゴリー
+
+- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
+  このカテゴリーの例は、一般的な エージェント の設計パターンを示します。例:
+
+    - 決定論的なワークフロー
+    - ツールとしての エージェント
+    - エージェント の並列実行
+
+- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
+  SDK の基礎的な機能を示す例です。例:
+
+    - 動的な システムプロンプト
+    - ストリーミング 出力
+    - ライフサイクルイベント
+
+- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
+  Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法と、それらを エージェント に統合する方法を学べます。
+
+- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
+  OpenAI 以外のモデルを SDK で使う方法を紹介します。
+
+- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
+  エージェント のハンドオフ の実用例をご覧ください。
+
+- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
+  MCP で エージェント を構築する方法を学べます。
+
+- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** および **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
+  実運用での用途を示す、さらに作り込まれた 2 つの例
+
+    - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。
+    - **research_bot**: 簡易な ディープリサーチ のクローン。
+
+- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
+  当社の TTS と STT モデルを用いた音声 エージェント の例。
+
+- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
+  SDK を使ってリアルタイム体験を構築する方法を示す例。

openai_agents-0.2.10/docs/ja/guardrails.md

@@ -0,0 +1,158 @@
+---
+search:
+  exclude: true
+---
+# ガードレール
+
+ガードレールはエージェントと _ 並行して _ 実行され、 ユーザー 入力のチェックや検証を行えます。たとえば、 とても賢い（つまり遅く/高コストな）モデルを使って カスタマーリクエスト を支援する エージェント があるとします。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるよう依頼するのは避けたいはずです。そこで、 高速/低コスト なモデルでガードレールを実行できます。ガードレールが不正な利用を検知した場合、すぐにエラーを発生させ、 高コスト なモデルの実行を停止して時間や費用を節約できます。
+
+ガードレールには 2 種類あります。
+
+1. 入力ガードレールは最初の ユーザー 入力で実行されます
+2. 出力ガードレールは最終的な エージェント 出力で実行されます
+
+## 入力ガードレール
+
+入力ガードレールは次の 3 段階で実行されます。
+
+1. まず、ガードレールは エージェント に渡されたものと同じ入力を受け取ります。
+2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。
+3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、適切に ユーザー へ応答するか、例外を処理できます。
+
+!!! Note
+
+    入力ガードレールは ユーザー 入力での実行を想定しているため、 エージェント のガードレールはその エージェント が * 最初 * の エージェント の場合にのみ実行されます。なぜ `guardrails` プロパティが エージェント 上にあり、`Runner.run` へ渡さないのか疑問に思うかもしれません。これは、ガードレールが実際の エージェント と密接に関連する傾向があるためです。 エージェント ごとに異なるガードレールを実行するので、コードを同じ場所に置くことが可読性の観点から有用です。
+
+## 出力ガードレール
+
+出力ガードレールは次の 3 段階で実行されます。
+
+1. まず、ガードレールは エージェント によって生成された出力を受け取ります。
+2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。
+3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、適切に ユーザー へ応答するか、例外を処理できます。
+
+!!! Note
+
+    出力ガードレールは最終的な エージェント 出力での実行を想定しているため、 エージェント のガードレールはその エージェント が * 最後 * の エージェント の場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際の エージェント と密接に関連する傾向があるため、コードを同じ場所に置くことが可読性の観点から有用です。
+
+## トリップワイヤー
+
+入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでそれを示せます。トリップワイヤーが作動したガードレールを検知した時点で、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、 エージェント の実行を停止します。
+
+## ガードレールの実装
+
+入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、その内部で エージェント を実行して実現します。
+
+```python
+from pydantic import BaseModel
+from agents import (
+    Agent,
+    GuardrailFunctionOutput,
+    InputGuardrailTripwireTriggered,
+    RunContextWrapper,
+    Runner,
+    TResponseInputItem,
+    input_guardrail,
+)
+
+class MathHomeworkOutput(BaseModel):
+    is_math_homework: bool
+    reasoning: str
+
+guardrail_agent = Agent( # (1)!
+    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( # (2)!
+    ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
+) -> GuardrailFunctionOutput:
+    result = await Runner.run(guardrail_agent, input, context=ctx.context)
+
+    return GuardrailFunctionOutput(
+        output_info=result.final_output, # (3)!
+        tripwire_triggered=result.final_output.is_math_homework,
+    )
+
+
+agent = Agent(  # (4)!
+    name="Customer support agent",
+    instructions="You are a customer support agent. You help customers with their questions.",
+    input_guardrails=[math_guardrail],
+)
+
+async def main():
+    # This should trip the guardrail
+    try:
+        await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
+        print("Guardrail didn't trip - this is unexpected")
+
+    except InputGuardrailTripwireTriggered:
+        print("Math homework guardrail tripped")
+```
+
+1. この エージェント をガードレール関数内で使用します。
+2. これは エージェント の入力/コンテキストを受け取り、結果を返すガードレール関数です。
+3. ガードレール結果に追加情報を含めることができます。
+4. これはワークフローを定義する実際の エージェント です。
+
+出力ガードレールも同様です。
+
+```python
+from pydantic import BaseModel
+from agents import (
+    Agent,
+    GuardrailFunctionOutput,
+    OutputGuardrailTripwireTriggered,
+    RunContextWrapper,
+    Runner,
+    output_guardrail,
+)
+class MessageOutput(BaseModel): # (1)!
+    response: str
+
+class MathOutput(BaseModel): # (2)!
+    reasoning: str
+    is_math: bool
+
+guardrail_agent = Agent(
+    name="Guardrail check",
+    instructions="Check if the output includes any math.",
+    output_type=MathOutput,
+)
+
+@output_guardrail
+async def math_guardrail(  # (3)!
+    ctx: RunContextWrapper, agent: Agent, output: MessageOutput
+) -> GuardrailFunctionOutput:
+    result = await Runner.run(guardrail_agent, output.response, context=ctx.context)
+
+    return GuardrailFunctionOutput(
+        output_info=result.final_output,
+        tripwire_triggered=result.final_output.is_math,
+    )
+
+agent = Agent( # (4)!
+    name="Customer support agent",
+    instructions="You are a customer support agent. You help customers with their questions.",
+    output_guardrails=[math_guardrail],
+    output_type=MessageOutput,
+)
+
+async def main():
+    # This should trip the guardrail
+    try:
+        await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?")
+        print("Guardrail didn't trip - this is unexpected")
+
+    except OutputGuardrailTripwireTriggered:
+        print("Math output guardrail tripped")
+```
+
+1. これは実際の エージェント の出力型です。
+2. これはガードレールの出力型です。
+3. これは エージェント の出力を受け取り、結果を返すガードレール関数です。
+4. これはワークフローを定義する実際の エージェント です。