diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml index 2def4f03e..327209110 100644 --- a/.github/workflows/update-docs.yml +++ b/.github/workflows/update-docs.yml @@ -55,6 +55,10 @@ jobs: with: commit-message: "Update all translated document pages" title: "Update all translated document pages" - body: "Automated update of translated documentation" + body: | + Automated update of translated documentation. + + Triggered by commit: [${{ github.event.head_commit.id }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.event.head_commit.id }}). + Message: `${{ github.event.head_commit.message }}` branch: update-translated-docs-${{ github.run_id }} delete-branch: true diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 5e371b584..999a2b49e 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる基本コンポーネントです。エージェントは、instructions とツールで設定された大規模言語モデル（LLM）です。 +エージェントはアプリの中核となる基本コンポーネントです。エージェントは、instructions とツールで構成された大規模言語モデル（ LLM ）です。 -## 基本設定 +## 基本構成 エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージまたは システムプロンプト とも呼ばれます。 -- `model`: 使用する LLM と、temperature、top_p などのモデル調整パラメーターを設定する任意の `model_settings`。 -- `tools`: エージェントがタスクを達成するために使用できるツールです。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: developer メッセージまたは 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/) でラップできる任意の型（dataclasses、lists、TypedDict など）をサポートします。 +既定では、エージェントはプレーンテキスト（つまり `str`）の出力を生成します。特定のタイプの出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使うことですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型（dataclasses、lists、TypedDict など）をサポートします。 ```python from pydantic import BaseModel @@ -73,20 +73,20 @@ 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) を使用するように指示されます。 -## マルチエージェントシステムの設計パターン +## マルチエージェント システムの設計パターン -マルチエージェントシステムの設計方法は多数ありますが、一般的に適用できるパターンとして次の 2 つがよく見られます。 +マルチエージェント システムの設計方法は多様ですが、一般的に広く適用できるパターンが 2 つあります。 -1. マネージャー（ツールとしてのエージェント）: 中央のマネージャー/オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を保持します。 -2. ハンドオフ: ピアのエージェントが、会話を引き継ぐ専門のエージェントに制御を引き渡します。これは分散型です。 +1. マネージャー（エージェントをツールとして使用）: 中央のマネージャー／オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を保持します。 +2. ハンドオフ: ピアのエージェントが制御を専門のエージェントに引き渡し、そのエージェントが会話を引き継ぎます。これは分散型です。 -詳細は [エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) を参照してください。 +詳細は [エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)をご覧ください。 -### マネージャー（ツールとしてのエージェント） +### マネージャー（エージェントをツールとして使用） -`customer_facing_agent` はすべてのユーザーとのやり取りを処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントを参照してください。 +`customer_facing_agent` はすべてのユーザーとの対話を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントをお読みください。 ```python from agents import Agent @@ -115,7 +115,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフが発生すると、委譲先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに優れたモジュール式で専門的なエージェントが可能になります。詳細は [ハンドオフ](handoffs.md) ドキュメントを参照してください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンは、単一のタスクに特化して優れた性能を発揮する、モジュール式で専門的なエージェントを可能にします。詳細は [ハンドオフ](handoffs.md) ドキュメントをお読みください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェントを作成するときに instructions を指定できます。ただし、関数を介して動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用可能です。 +多くの場合、エージェントを作成するときに instructions を指定できますが、関数を介して動的な instructions を提供することもできます。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用できます。 ```python def dynamic_instructions( @@ -153,13 +153,13 @@ agent = Agent[UserContext]( ## ライフサイクルイベント（フック） -場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベントが発生したときにデータを事前取得したりできます。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック/検証を実行し、エージェントの出力が生成された後にも実行できます。たとえば、ユーザーの入力とエージェントの出力が関連するかどうかをスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントを参照してください。 +ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック／検証を行い、さらにエージェントの出力が生成された後のチェック／検証も実行できます。たとえば、ユーザーの入力とエージェントの出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントをお読みください。 -## エージェントのクローン/コピー +## エージェントのクローン／コピー エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 @@ -178,12 +178,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`: LLM にツールを使用しないことを要求します。 -4. 特定の文字列（例: `my_tool`）を設定すると、LLM にその特定のツールを使用することを要求します。 +1. `auto`: ツールを使用するかどうかを LLM に委ねます。 +2. `required`: LLM にツールの使用を必須にします（どのツールを使うかは賢く判断できます）。 +3. `none`: LLM にツールを使用しないことを必須にします。 +4. 特定の文字列（例: `my_tool`）を設定すると、LLM にその特定のツールの使用を必須にします。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -201,11 +201,11 @@ agent = Agent( ) ``` -## ツール使用の挙動 +## ツール使用時の動作 -`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱いを制御します。 +`Agent` 構成の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 -- `"run_llm_again"`: デフォルト。ツールが実行され、LLM が結果を処理して最終応答を生成します。 +- `"run_llm_again"`: 既定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 - `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、追加の LLM 処理なしで最終応答として使用します。 ```python @@ -224,7 +224,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出された場合に停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool @@ -248,7 +248,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを決定するカスタム関数です。 +- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを判断するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -286,4 +286,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループの原因は、ツール結果が LLM に送られ、`tool_choice` により LLM が再度ツール呼び出しを生成し続けてしまうためです。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループは、ツール結果が LLM に送られ、`tool_choice` のために LLM がさらに別のツール呼び出しを生成し続けることが原因です。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index b520f3bd1..f60585fc3 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポートされた直後から、LLM リクエストと トレーシング 用に `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 +デフォルトでは、SDK はインポート直後から LLM リクエストとトレーシングのために、環境変数 `OPENAI_API_KEY` を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーを使って `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使うには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 +最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使うには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシング はデフォルトで有効です。デフォルトでは、上記の OpenAI API キー（つまり、環境変数または設定したデフォルトキー）を使用します。トレーシング に使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 +トレーシングはデフォルトで有効です。デフォルトでは上記の OpenAI API キー（つまり、環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシング を完全に無効化することもできます。 +トレーシングを完全に無効化するには、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 ```python from agents import set_tracing_disabled @@ -50,9 +50,9 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグログ +## デバッグ ログ -SDK にはハンドラー未設定の Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られ、それ以外のログは抑制されます。 +SDK にはハンドラー未設定の Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られますが、その他のログは抑制されます。 詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機微情報 +### ログ内の機微なデータ -一部のログには機微情報（例: ユーザー データ）が含まれる場合があります。これらのデータがログに出力されないようにするには、以下の環境変数を設定してください。 +一部のログには機微なデータ（例: ユーザー データ）が含まれる場合があります。これらのデータがログに記録されないようにするには、以下の環境変数を設定してください。 -LLM の入力および出力のログを無効化するには: +LLM の入力と出力のロギングを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力および出力のログを無効化するには: +ツールの入力と出力のロギングを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 1dd8d54d0..2de596e96 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語は多義的です。考慮すべきコンテキストには主に 2 つのクラスがあります。 +コンテキストという用語は多義的です。重要になるコンテキストには主に 2 つのクラスがあります。 -1. コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック中、ライフサイクルフック内などで必要になる可能性のあるデータや依存関係です。 -2. LLM に利用可能なコンテキスト: これは、応答生成時に LLM が参照できるデータです。 +1. コードでローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に提供されるコンテキスト: 応答を生成する際に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表されます。動作は次のとおりです。 +これは [`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` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。よくあるパターンとしては dataclass や Pydantic オブジェクトを使います。 +2. そのオブジェクトを各種実行メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 +3. すべてのツール呼び出しやライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` からアクセスできます。 -最も **重要** な点: あるエージェント実行に関わるすべてのエージェント、ツール関数、ライフサイクルなどは、同じコンテキストの型を使用しなければなりません。 +最も **重要** な注意点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクル等は同じ種類（_type_）のコンテキストを使用しなければなりません。 -コンテキストは次のような用途に使えます: +コンテキストは次のような用途に使えます。 -- 実行のための状況依存データ（例: ユーザー名/uid やその他のユーザー情報） -- 依存関係（例: ロガーオブジェクト、データ取得クラスなど） +- 実行のための文脈データ（例: ユーザー名 / uid や、ユーザーに関するその他の情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） - ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に送信される **わけではありません**。これはあくまでローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから読み取ります。 -3. 型チェッカーでエラーを検出できるよう、エージェントにジェネリックの `UserInfo` を付けます（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 -4. コンテキストは `run` 関数に渡されます。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、ツールの実装はコンテキストから読み取ります。 +3. 型チェッカーがエラーを検出できるよう、エージェントにジェネリックの `UserInfo` を付与します（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント/LLM のコンテキスト +## エージェント / LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。したがって、LLM に新しいデータを利用可能にしたい場合は、その履歴で参照できる形で提供する必要があります。これにはいくつかの方法があります。 +LLM が呼び出されると、LLM が参照できるデータは会話履歴のものに **限られます**。つまり、LLM に新しいデータを利用可能にしたい場合は、その履歴で参照できる形で提供する必要があります。いくつか方法があります。 -1. エージェントの `instructions` に追加します。これは "system prompt" や "developer message" とも呼ばれます。system prompt は静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。これは常に有用な情報（例: ユーザーの名前や現在の日付）に一般的な手法です。 -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 検索）から関連データを取得できる特別なツールです。これは、応答を関連する文脈データで「グラウンディング」するのに有用です。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な戦術です。 +2. `Runner.run` 関数を呼ぶ際の `input` に追加します。これは `instructions` の戦術に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 上でより下位のメッセージとして扱えます。 +3. 関数ツールを通じて公開します。これはオンデマンドのコンテキストに有用です。LLM が必要なときにデータを要求し、ツールを呼び出してそのデータを取得できます。 +4. リトリーバル（retrieval）や Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）または Web（Web 検索）から関連データを取得できる特別なツールです。関連する文脈データに基づいて応答を「グラウンディング」するのに役立ちます。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 9e51aa9d8..38105db08 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,46 +4,44 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK の多様なサンプル実装をご覧ください。これらのコード例は、さまざまなパターンや機能を示す複数の カテゴリー に整理されています。 - +[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 の基礎的な機能を示します + SDK の基礎的な機能を紹介します。例えば - - 動的な system prompt + - 動的な システムプロンプト - ストリーミング出力 - ライフサイクルイベント - **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法を学び、 - それらを エージェント に統合します。 + Web 検索 や ファイル検索 などの OpenAI がホストするツールの実装方法と、それらをエージェントに統合する方法を学びます。 - **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - SDK で OpenAI 以外のモデルを使用する方法を探ります。 + SDK で OpenAI 以外のモデルを使う方法を紹介します。 - **[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 で エージェント を構築する方法を学びます。 + 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 つのコード例 + 実運用に近いアプリケーションを示す、より作り込まれたコード例が 2 つあります - - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 + - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 - **research_bot**: シンプルな ディープリサーチ のクローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 当社の TTS および STT モデルを使った音声 エージェント のコード例をご覧ください。 + TTS と STT のモデルを用いた音声エージェントの例をご覧ください。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使用してリアルタイム体験を構築する方法を示すコード例。 \ No newline at end of file + SDK を使ってリアルタイム体験を構築する方法の例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index fb98e3c99..47ae0c1b3 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは、エージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を行います。例えば、カスタマー対応に非常に賢い（そのぶん遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を手伝わせるような依頼をするのは避けたいはずです。そこで、高速/低コストなモデルでガードレールを実行できます。ガードレールが悪用を検知した場合、即座にエラーを送出し、高価なモデルの実行を止めて時間やコストを節約できます。 +ガードレールはエージェントと_並行して_動作し、ユーザー入力のチェックや検証を行います。たとえば、顧客からのリクエストに対応するために非常に賢い（そのため遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーに、そのモデルで数学の宿題を手伝わせるようなリクエストは避けたいはずです。そのために、高速/低コストなモデルでガードレールを実行できます。ガードレールが悪用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。 ガードレールには 2 種類あります: 1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェント出力に対して実行されます +2. 出力ガードレールは最終的なエージェントの出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 ステップで実行されます: +入力ガードレールは次の 3 ステップで動作します: -1. まず、ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 +1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの適切な応答や例外処理が行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理を行えます。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールは、そのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行することになるので、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントのガードレールはそのエージェントが*最初の*エージェントである場合にのみ動作します。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行することになるので、コードを同じ場所に置くほうが読みやすくなります。 ## 出力ガードレール -出力ガードレールは 3 ステップで実行されます: +出力ガードレールは次の 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] 例外が送出されるため、ユーザーへの適切な応答や例外処理が行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理を行えます。 !!! Note - 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントのガードレールは、そのエージェントが「最後の」エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的なエージェントの出力に対して実行されることを意図しているため、エージェントのガードレールはそのエージェントが*最後の*エージェントである場合にのみ動作します。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所に置くほうが読みやすくなります。 ## トリップワイヤー -入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが発動したガードレールを検知するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが作動したガードレールを検出するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行することで実現します。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、水面下でエージェントを実行することでこれを行います。 ```python from pydantic import BaseModel @@ -96,7 +96,7 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果に追加情報を含めることができます。 +3. ガードレール結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index e5ae1b584..196342abf 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # ハンドオフ -ハンドオフにより、エージェントが別のエージェントにタスクを委任できます。これは、異なるエージェントがそれぞれ別の領域を専門にしている状況で特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に扱うエージェントがいるかもしれません。 +ハンドオフは、あるエージェントが別のエージェントにタスクを委譲できる仕組みです。これは、異なるエージェントがそれぞれ別の分野に特化している状況で特に有用です。例えば、カスタマーサポートアプリでは、注文状況、払い戻し、FAQ などを個別に担当するエージェントが存在し得ます。 -ハンドオフは LLM に対してツールとして表現されます。たとえば、`Refund Agent` というエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM にとってツールとして表現されます。例えば、`Refund Agent` というエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、これは `Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持っており、これは `Agent` を直接渡すか、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すことができます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加えて、任意のオーバーライドや入力フィルターを指定できます。 +ハンドオフは Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数で作成できます。この関数では、ハンドオフ先のエージェントに加えて、オプションのオーバーライドや入力フィルターを指定できます。 -### 基本的な使い方 +### 基本的な使用方法 -シンプルなハンドオフの作成方法は次のとおりです。 +以下は、シンプルなハンドオフの作成方法です。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のようにエージェントを直接使うことも、`handoff()` 関数を使うこともできます。 +1. `billing_agent` のようにエージェントを直接利用することも、`handoff()` 関数を使うこともできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数ではさまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフ先となるエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に解決されます。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼ばれたことが分かった直後にデータ取得を開始する、といった用途に便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフが想定する入力の型（任意）です。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングします。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうかです。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 +- `agent`: ハンドオフ先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使用され、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 +- `on_handoff`: ハンドオフ実行時に呼び出されるコールバック関数です。ハンドオフが呼ばれたタイミングでデータ取得を開始する、といった用途に便利です。この関数はエージェント コンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで想定される入力の型（オプション）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングします。詳細は下記を参照してください。 +- `is_enabled`: ハンドオフを有効にするかどうか。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフ入力 +## ハンドオフの入力 -状況によっては、ハンドオフ呼び出し時に LLM にデータを提供してほしい場合があります。たとえば「エスカレーション エージェント」へのハンドオフを想像してください。記録できるように、理由を提供してほしいことがあります。 +状況によっては、ハンドオフ呼び出し時に LLM によっていくつかのデータを提供してほしいことがあります。例えば「エスカレーション エージェント」へのハンドオフを想定すると、記録のために理由を受け取りたい場合があります。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を閲覧できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を閲覧できるかのように動作します。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] で実装済みです。 +いくつかの一般的なパターン（例えば履歴からすべてのツール呼び出しを除去するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. これは、`FAQ agent` が呼び出されたときに履歴からすべてのツールを自動的に削除します。 +1. これは、`FAQ agent` が呼び出されたときに履歴からすべてのツールを自動的に除去します。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、あるいは [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動的に追加できます。 +LLM にハンドオフを正しく理解させるため、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] の推奨プレフィックスを利用するか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index bbd9e131d..4269af102 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、以前のエージェント実験である [Swarm](https://github.com/openai/swarm/tree/main) の本番対応版アップグレードです。Agents SDK はごく少数の基本コンポーネントから成ります: +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、最小限の抽象化で軽量かつ使いやすいパッケージにより、エージェント型 AI アプリを構築できるようにします。これは、以前の エージェント 向け実験である [Swarm](https://github.com/openai/swarm/tree/main) を本番運用向けに強化した後継です。Agents SDK はごく少数の基本コンポーネントで構成されています: -- **エージェント**: instructions とツールを備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できる仕組み -- **ガードレール**: エージェントの入力と出力の検証を可能にする仕組み -- **セッション**: エージェントの実行をまたいで会話履歴を自動的に維持します +- **Agents**、instructions と tools を備えた LLM +- **Handoffs**、特定のタスクを他の エージェント に委譲できる仕組み +- **Guardrails**、エージェントの入力と出力の検証を可能にする仕組み +- **Sessions**、エージェントの実行間で会話履歴を自動的に維持する仕組み -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係性を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェントのフローを可視化・デバッグできるほか、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールと エージェント 間の複雑な関係を表現でき、急な学習曲線なしに実用的なアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェント フローの可視化とデバッグ、評価や、アプリケーションに合わせたモデルの微調整まで行えます。 -## Agents SDK を使う理由 +## Agents SDK の利点 -この SDK には 2 つの設計原則があります: +SDK には次の 2 つの設計原則があります: -1. 使う価値があるだけの機能を備えつつ、学習を容易にするための最小限の基本コンポーネントにとどめること。 -2. すぐに使えて高品質に動作しつつ、起きることを正確にカスタマイズできること。 +1. 使う価値があるだけの機能を備えつつ、学習が早いよう基本コンポーネントは少数に保つ。 +2. すぐ使える一方で、挙動を細部までカスタマイズできる。 -SDK の主な特長は次のとおりです: +SDK の主な機能は次のとおりです: -- エージェントループ: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを処理する組み込みのエージェントループ。 -- Python ファースト: 新しい抽象を学ぶのではなく、言語の組み込み機能を使ってエージェントをオーケストレーションし、連携できます。 -- ハンドオフ: 複数のエージェント間で調整・委譲するための強力な機能。 -- ガードレール: エージェントと並行して入力の検証やチェックを実行し、失敗した場合は早期に打ち切ります。 -- セッション: エージェントの実行をまたいだ会話履歴の自動管理により、手動での状態管理が不要になります。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースのバリデーションを提供します。 -- トレーシング: ワークフローの可視化、デバッグ、監視を可能にする組み込みのトレーシング。さらに OpenAI の評価、ファインチューニング、蒸留ツール群も活用できます。 +- エージェント ループ: ツール呼び出し、結果の LLM への送信、LLM が完了するまでのループ処理を行う組み込みのエージェント ループ。 +- Python ファースト: 新しい抽象を学ぶのではなく、言語の標準機能で エージェント のオーケストレーションや連携を記述可能。 +- ハンドオフ: 複数の エージェント 間での調整と委譲を可能にする強力な機能。 +- ガードレール: 入力の検証とチェックを エージェント と並行実行し、失敗した場合は早期に中断。 +- セッション: エージェント 実行間の会話履歴を自動管理し、手動の状態管理を不要に。 +- 関数ツール: 任意の Python 関数をツール化し、スキーマ自動生成と Pydantic による検証を提供。 +- トレーシング: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツール群を活用可能にする組み込みのトレーシング。 ## インストール @@ -36,7 +36,7 @@ SDK の主な特長は次のとおりです: pip install openai-agents ``` -## Hello world の例 +## Hello World の例 ```python from agents import Agent, Runner diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 46d314781..bdf6e1d16 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,188 +4,314 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP のドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーションのための USB‑C ポートのようなものだと考えてください。USB‑C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI +> applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP +> provides a standardized way to connect AI models to different data sources and tools. -Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用して、エージェントにツールやプロンプトを提供できます。 +Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、独自の MCP サーバーを構築して、ファイルシステム、HTTP、あるいはコネクタをバックエンドに持つツールをエージェントに公開できます。 -## MCP サーバー +## MCP 連携の選択 -現在、MCP 仕様は使用するトランスポートメカニズムに基づいて 3 種類のサーバーを定義しています: +MCP サーバーをエージェントに組み込む前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは Python SDK がサポートするオプションの概要です。 -1. **stdio** サーバーはアプリケーションのサブプロセスとして実行されます。いわば「ローカル」で動作します。 -2. **HTTP over SSE** サーバーはリモートで実行され、URL で接続します。 -3. **Streamable HTTP** サーバーは、MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 +| 必要なこと | 推奨オプション | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| OpenAI の Responses API に、モデルの代わりにパブリック到達可能な MCP サーバーを呼び出させたい | **Hosted MCP server tools**（ホスト型 MCP サーバー ツール） via [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| ローカルまたはリモートで自分が運用する Streamable HTTP サーバーに接続したい | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Server-Sent Events を用いる HTTP を実装するサーバーと通信したい | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| ローカルプロセスを起動して stdin/stdout 経由で通信したい | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +以下では各オプションについて、設定方法や、どのトランスポートを選ぶべきかを説明します。 -たとえば、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)は次のように使用します。 +## 1. Hosted MCP server tools + +Hosted ツールは、ツールの往復処理全体を OpenAI のインフラに委ねます。あなたのコードがツールの列挙と呼び出しを行う代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] はサーバーのラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、あなたの Python プロセスへの追加のコールバックなしにそれらを実行します。Hosted ツールは現在、Responses API の hosted MCP 連携に対応した OpenAI モデルで動作します。 + +### 基本の hosted MCP ツール + +エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` の dict は REST API に送信する JSON を反映します: ```python -from agents.run_context import RunContextWrapper +import asyncio + +from agents import Agent, HostedMCPTool, Runner + +async def main() -> None: + agent = Agent( + name="Assistant", + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "never", + } + ) + ], + ) -async with MCPServerStdio( - params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], - } -) as server: - # Note: In practice, you typically add the server to an Agent - # and let the framework handle tool listing automatically. - # Direct calls to list_tools() require run_context and agent parameters. - run_context = RunContextWrapper(context=None) - agent = Agent(name="test", instructions="test") - tools = await server.list_tools(run_context, agent) + result = await Runner.run(agent, "Which language is this repository written in?") + print(result.final_output) + +asyncio.run(main()) ``` -## MCP サーバーの使用 +ホストされたサーバーは自動的に自身のツールを公開します。`mcp_servers` に追加する必要はありません。 + +### ストリーミングによる hosted MCP 結果 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーで `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーで `call_tool()` を呼び出します。 +Hosted ツールは関数ツールとまったく同じ方法で結果のストリーミングに対応します。`Runner.run_streamed` に `stream=True` を渡すと、モデルが処理中でも増分の MCP 出力を消費できます: ```python +result = Runner.run_streamed(agent, "Summarise this repository's top languages") +async for event in result.stream_events(): + if event.type == "run_item_stream_event": + print(f"Received: {event.item}") +print(result.final_output) +``` + +### 任意の承認フロー + +サーバーが機微な操作を行える場合、各ツール実行前に人間もしくはプログラムによる承認を必須にできます。`tool_config` の `require_approval` を単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict で設定します。判断を Python 内で行うには、`on_approval_request` コールバックを指定します。 + +```python +from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest + +SAFE_TOOLS = {"read_project_metadata"} + +def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult: + if request.data.name in SAFE_TOOLS: + return {"approve": True} + return {"approve": False, "reason": "Escalate to a human reviewer"} -agent=Agent( +agent = Agent( name="Assistant", - instructions="Use the tools to achieve the task", - mcp_servers=[mcp_server_1, mcp_server_2] + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "always", + }, + on_approval_request=approve_tool, + ) + ], ) ``` -## ツールのフィルタリング +コールバックは同期・非同期のどちらでもよく、モデルが継続実行に必要な承認データを求めるたびに呼び出されます。 + +### コネクタ連携の hosted サーバー + +Hosted MCP は OpenAI コネクタにも対応します。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホストされたサーバーがコネクタのツールを公開します。 + +```python +import os + +HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "google_calendar", + "connector_id": "connector_googlecalendar", + "authorization": os.environ["GOOGLE_CALENDAR_AUTHORIZATION"], + "require_approval": "never", + } +) +``` -MCP サーバーでツールフィルターを設定することで、エージェントで利用可能なツールを絞り込めます。SDK は静的および動的なツールフィルタリングの両方をサポートします。 +ストリーミング、承認、コネクタを含む完全な Hosted ツールのサンプルは +[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 -### 静的ツールフィルタリング +## 2. Streamable HTTP MCP servers -単純な許可/ブロックのリストには、静的フィルタリングを使用します: +ネットワーク接続を自分で管理したい場合は +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、低レイテンシを保ちながら自前のインフラ内でサーバーを稼働させたい場合に最適です。 ```python -from agents.mcp import create_static_tool_filter +import asyncio +import os + +from agents import Agent, Runner +from agents.mcp import MCPServerStreamableHttp +from agents.model_settings import ModelSettings + +async def main() -> None: + token = os.environ["MCP_SERVER_TOKEN"] + async with MCPServerStreamableHttp( + name="Streamable HTTP Python Server", + params={ + "url": "http://localhost:8000/mcp", + "headers": {"Authorization": f"Bearer {token}"}, + "timeout": 10, + }, + cache_tools_list=True, + max_retry_attempts=3, + ) as server: + agent = Agent( + name="Assistant", + instructions="Use the MCP tools to answer the questions.", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), + ) + + result = await Runner.run(agent, "Add 7 and 22.") + print(result.final_output) + +asyncio.run(main()) +``` + +コンストラクタは追加のオプションを受け取ります: + +- `client_session_timeout_seconds` は HTTP の読み取りタイムアウトを制御します。 +- `use_structured_content` は、テキスト出力よりも `tool_result.structured_content` を優先するかどうかを切り替えます。 +- `max_retry_attempts` と `retry_backoff_seconds_base` は `list_tools()` と `call_tool()` に自動リトライを追加します。 +- `tool_filter` により、一部のツールのみを公開できます（[ツールのフィルタリング](#tool-filtering) を参照）。 + +## 3. HTTP with SSE MCP servers + +MCP サーバーが HTTP with SSE トランスポートを実装している場合は、 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 -# Only expose specific tools from this server -server = MCPServerStdio( +```python +workspace_id = "demo-workspace" + +async with MCPServerSse( + name="SSE Python Server", params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "url": "http://localhost:8000/sse", + "headers": {"X-Workspace": workspace_id}, }, - tool_filter=create_static_tool_filter( - allowed_tool_names=["read_file", "write_file"] + cache_tools_list=True, +) as server: + agent = Agent( + name="Assistant", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), ) -) + result = await Runner.run(agent, "What's the weather in Tokyo?") + print(result.final_output) +``` + +## 4. stdio MCP servers -# Exclude specific tools from this server -server = MCPServerStdio( +ローカルのサブプロセスとして動作する MCP サーバーには [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたまま維持し、コンテキストマネージャーの終了時に自動的にクローズします。これは、迅速なプロトタイプや、サーバーがコマンドラインのエントリポイントのみを公開する場合に有用です。 + +```python +from pathlib import Path + +current_dir = Path(__file__).parent +samples_dir = current_dir / "sample_files" + +async with MCPServerStdio( + name="Filesystem Server via npx", params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], }, - tool_filter=create_static_tool_filter( - blocked_tool_names=["delete_file"] +) as server: + agent = Agent( + name="Assistant", + instructions="Use the files in the sample directory to answer questions.", + mcp_servers=[server], ) -) - + result = await Runner.run(agent, "List the files available to you.") + print(result.final_output) ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合の処理順序は次のとおりです:** -1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールだけを残します -2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定したツールを除外します +## ツールのフィルタリング -たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、利用可能なのは `read_file` と `write_file` のみになります。 +各 MCP サーバーはツールフィルタをサポートしており、エージェントに必要な機能のみを公開できます。フィルタリングは構築時にも、実行ごとの動的な方法でも可能です。 -### 動的ツールフィルタリング +### 静的なツールフィルタリング -より複雑なフィルタリングロジックには、関数を使った動的フィルターを使用します: +[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、許可/ブロックの単純なリストを設定します: ```python -from agents.mcp import ToolFilterContext - -# Simple synchronous filter -def custom_filter(context: ToolFilterContext, tool) -> bool: - """Example of a custom tool filter.""" - # Filter logic based on tool name patterns - return tool.name.startswith("allowed_prefix") - -# Context-aware filter -def context_aware_filter(context: ToolFilterContext, tool) -> bool: - """Filter tools based on context information.""" - # Access agent information - agent_name = context.agent.name - - # Access server information - server_name = context.server_name - - # Implement your custom filtering logic here - return some_filtering_logic(agent_name, server_name, tool) - -# Asynchronous filter -async def async_filter(context: ToolFilterContext, tool) -> bool: - """Example of an asynchronous filter.""" - # Perform async operations if needed - result = await some_async_check(context, tool) - return result - -server = MCPServerStdio( +from pathlib import Path + +from agents.mcp import MCPServerStdio, create_static_tool_filter + +samples_dir = Path("/path/to/files") + +filesystem_server = MCPServerStdio( params={ "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], }, - tool_filter=custom_filter # or context_aware_filter or async_filter + tool_filter=create_static_tool_filter(allowed_tool_names=["read_file", "write_file"]), ) ``` -`ToolFilterContext` では次にアクセスできます: -- `run_context`: 現在の実行コンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後で残りの集合からブロック対象のツールを除外します。 -## プロンプト +### 動的なツールフィルタリング -MCP サーバーは、エージェントの instructions を動的に生成するためのプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instructions テンプレートを作成できます。 +より高度なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。これは同期・非同期のいずれでもよく、ツールを公開すべき場合に `True` を返します。 -### プロンプトの使用 +```python +from pathlib import Path -プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します: +from agents.mcp import MCPServerStdio, ToolFilterContext -- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示 -- `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得 +samples_dir = Path("/path/to/files") -```python -# List available prompts -prompts_result = await server.list_prompts() -for prompt in prompts_result.prompts: - print(f"Prompt: {prompt.name} - {prompt.description}") +async def context_aware_filter(context: ToolFilterContext, tool) -> bool: + if context.agent.name == "Code Reviewer" and tool.name.startswith("danger_"): + return False + return True + +async with MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], + }, + tool_filter=context_aware_filter, +) as server: + ... +``` + +フィルタコンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 -# Get a specific prompt with parameters +## プロンプト + +MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは次の 2 つのメソッドを公開します: + +- `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 +- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。 + +```python prompt_result = await server.get_prompt( "generate_code_review_instructions", - {"focus": "security vulnerabilities", "language": "python"} + {"focus": "security vulnerabilities", "language": "python"}, ) instructions = prompt_result.messages[0].content.text -# Use the prompt-generated instructions with an Agent agent = Agent( name="Code Reviewer", - instructions=instructions, # Instructions from MCP prompt - mcp_servers=[server] + instructions=instructions, + mcp_servers=[server], ) ``` ## キャッシュ -エージェントが実行されるたびに、MCP サーバーで `list_tools()` が呼び出されます。特にサーバーがリモートの場合、これは待ち時間の原因になり得ます。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないと確信できる場合にのみ実行してください。 - -キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出せます。 +すべてのエージェント実行は各 MCP サーバーに対して `list_tools()` を呼び出します。リモートサーバーは無視できないレイテンシをもたらす可能性があるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変わらないと確信できる場合にのみ `True` に設定してください。後で新しいリストを強制するには、サーバーインスタンスで `invalidate_tools_cache()` を呼び出します。 -## エンドツーエンドのコード例 +## トレーシング -[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) に完全に動作するコード例があります。 +[トレーシング](./tracing.md) は MCP のアクティビティを自動的に捕捉します。含まれるもの: -## トレーシング +1. ツールを列挙するための MCP サーバーへの呼び出し。 +2. ツール呼び出しに関する MCP 関連情報。 -[トレーシング](./tracing.md) は MCP の操作を自動的に捕捉します。含まれる内容: +![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) -1. ツール一覧の取得のための MCP サーバー呼び出し -2. 関数呼び出しに関する MCP 関連情報 +## 参考資料 -![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) \ No newline at end of file +- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様および設計ガイド。 +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP のサンプル。 +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む完全な hosted MCP のデモ。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 231df20a8..c167032f3 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、2 つの形態で OpenAI モデルの即時利用が含まれます。 +Agents SDK には、OpenAI モデルのサポートが 2 種類用意されています。 -- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を用いて OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を用いて OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] ## OpenAI モデル -`Agent` を初期化する際にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント的ワークフローにおける予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化する際にモデルを指定しない場合は、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント ワークフローの予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 -### 既定の OpenAI モデル +### デフォルトの OpenAI モデル -カスタムモデルを設定していないすべてのエージェントに対して特定のモデルを一貫して使用したい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 +カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使用したい場合は、エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -この方法で GPT-5 のいずれかの reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用すると、SDK は既定で妥当な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` をともに `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 +この方法で GPT-5 のいずれかの推論モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用すると、SDK は既定で適切な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 -より低レイテンシや特定の要件がある場合は、別のモデルと設定を選択できます。デフォルトモデルの reasoning 努力度を調整するには、独自の `ModelSettings` を渡してください。 +より低レイテンシや特定の要件がある場合は、別のモデルや設定を選択できます。デフォルトモデルの推論負荷を調整するには、独自の `ModelSettings` を渡します。 ```python from openai.types.shared import Reasoning @@ -44,52 +44,52 @@ my_agent = Agent( ) ``` -特に低レイテンシを狙う場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) モデルを `reasoning.effort="minimal"` で使用すると、デフォルト設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning 努力度をサポートしていないため、この Agents SDK は既定で `"low"` に設定しています。 +特に低レイテンシを重視する場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) モデルにおいて `reasoning.effort="minimal"` を使用すると、デフォルト設定よりも高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索 や画像生成など）は `"minimal"` の推論負荷をサポートしていないため、この Agents SDK のデフォルトは `"low"` になっています。 #### 非 GPT-5 モデル -カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `ModelSettings` に戻します。 +カスタムの `model_settings` を指定せずに GPT-5 以外のモデル名を渡した場合、SDK はどのモデルでも互換性のある汎用的な `ModelSettings` にフォールバックします。 ## 非 OpenAI モデル -[LiteLLM 連携](./litellm.md) を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、litellm の依存関係グループをインストールします。 +[LiteLLM 連携](./litellm.md) を介して、ほとんどの他社製モデルを使用できます。まず、litellm の依存関係グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて [サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 +次に、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) を使用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使うその他の方法 +### 非 OpenAI モデルを使う他の方法 -他の LLM プロバイダーを統合する方法はさらに 3 つあります（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーを統合する方法が 3 つあります（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に該当します。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルにあります。これにより、「この実行のすべてのエージェントにカスタムモデルプロバイダーを使用する」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] は、特定の Agent インスタンスでモデルを指定できるようにします。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの利用可能なモデルを簡単に使う方法は、[LiteLLM 連携](./litellm.md) を利用することです。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に使用します。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行のすべての エージェント にカスタムモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] では、特定の Agent インスタンスでモデルを指定できます。これにより、エージェント ごとに異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使うには、[LiteLLM 連携](./litellm.md) が便利です。 -`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` によるトレーシングの無効化、または [別のトレーシング プロセッサー](../tracing.md) の設定を推奨します。 +`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシング を無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 !!! note - これらの code examples では、Responses API をサポートしていない LLM プロバイダーがほとんどであるため、Chat Completions API/モデルを使用しています。もしお使いの LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの例では、Responses API をまだサポートしていない LLM プロバイダーが多数あるため、Chat Completions API/モデルを使用しています。お使いの LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 ## モデルの組み合わせ -単一のワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小型で高速なモデルを使用し、複雑なタスクには大型で高性能なモデルを使用できます。[`Agent`][agents.Agent] を構成する際には、以下のいずれかの方法で特定のモデルを選択できます。 +1 つのワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。例えば、振り分けには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使う、といった使い分けです。[`Agent`][agents.Agent] を構成する際は、次のいずれかの方法で特定のモデルを選べます。 1. モデル名を渡す。 -2. 任意のモデル名と、それを Model インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 -3. 直接 [`Model`][agents.models.interface.Model] 実装を提供する。 +2. 任意のモデル名に加えて、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - 当社の SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形態をサポートしますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは単一のモデル形態の使用を推奨します。ワークフローがモデル形態の混在を必要とする場合は、使用するすべての機能が双方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしますが、両者でサポートする機能やツールが異なるため、各ワークフローでは単一のモデル形状を使うことを推奨します。ワークフローでモデル形状を混在させる必要がある場合は、使用しているすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -122,10 +122,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデルの名前を直接設定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +1. OpenAI モデルの名前を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに構成したい場合は、温度などの任意のモデル構成パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。 +エージェント で使うモデルをさらに構成したい場合は、`temperature` などの任意のモデル構成パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで利用できない場合は、`extra_args` を使ってそれらを渡せます。 +また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡すこともできます。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 他社 LLM プロバイダー使用時の一般的な問題 +## 他社製 LLM プロバイダー利用時の一般的な問題 ### トレーシング クライアントのエラー 401 -トレースは OpenAI のサーバーにアップロードされ、OpenAI の API キーを持っていない場合、トレーシング関連のエラーが発生します。解決策は 3 つあります。 +トレーシング 関連のエラーが発生する場合、トレースは OpenAI の サーバー にアップロードされる一方で、OpenAI の API キーがないことが原因です。解決策は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. トレーシング 用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK は既定で Responses API を使用しますが、ほとんどの他社 LLM プロバイダーはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決策は 2 つあります。 +SDK はデフォルトで Responses API を使用しますが、他社製 LLM プロバイダーの多くはまだ未対応です。その結果、404 などの問題が発生する場合があります。解決するには次のいずれかを行ってください。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 ### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その結果、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。 ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダーの制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないというものです。私たちはこれに対する修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダーに依存することをおすすめします。そうでない場合、JSON の不正形式によりアプリがしばしば壊れてしまいます。 +これは一部のモデルプロバイダー側の制約で、JSON 出力自体には対応していても、出力に使用する `json_schema` を指定できない場合があります。現在この問題の解決に取り組んでいますが、JSON schema 出力をサポートするプロバイダーに依存することを推奨します。そうしないと、JSON が不正（malformed）であることが多く、アプリが頻繁に壊れてしまいます。 -## プロバイダーをまたいだモデルの混在 +## プロバイダーをまたぐモデルの混在 -モデルプロバイダー間の機能差異に注意しないと、エラーに直面する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしますが、多くの他社プロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 +モデルプロバイダー間の機能差異に注意しないと、エラーに遭遇する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 および Web 検索 をサポートしますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制約に注意してください。 -- サポートされていない `tools` を理解しないプロバイダーへ送信しないでください -- テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- structured な JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがあります \ No newline at end of file +- サポートされていない `tools` を理解しないプロバイダーに送信しない +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングする +- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 9cc8e02c2..6806e42ee 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM 経由の任意モデル利用 +# LiteLLM 経由で任意のモデルの利用 !!! note - LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダで問題が発生する可能性があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) で報告してください。迅速に対応します。 + LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する場合があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) にご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK で任意の AI モデルを使えるように、LiteLLM 連携を追加しました。 ## セットアップ -`litellm` を利用可能にする必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 +`litellm` が利用可能であることを確認する必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば次のように入力できます。 +これは完全に動作するサンプルです。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます。 -- モデルに `openai/gpt-4.1`、API キーに OpenAI の API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic の API キー -- など +- `openai/gpt-4.1` をモデルに、OpenAI の API キー +- `anthropic/claude-3-5-sonnet-20240620` をモデルに、Anthropic の API キー +- など -LiteLLM でサポートされているモデルの一覧は、[litellm のプロバイダ ドキュメント](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM がサポートするモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 7e2de1e80..fdef525c7 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントがどの順序で実行され、次に何をするかをどのように決めるか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内のエージェントの流れのことです。どのエージェントを、どの順序で実行し、次に何をするかをどのように決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる方法: LLM の知能を用いて計画・推論し、それに基づいて次の実行ステップを決めます。 -2. コードでオーケストレーションする方法: コードでエージェントの流れを決定します。 +1. LLM に意思決定を任せる: LLM の知能を使って計画・推論し、それに基づいて取るべき手順を決定します。 +2. コードによるオーケストレーション: コードでエージェントの流れを決定します。 これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、ツール、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はツールを使って行動やデータ取得を行い、ハンドオフでサブエージェントにタスクを委譲しながら、タスクに取り組む計画を自律的に立てられます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクに対して、LLM が自律的にタスクの進め方を計画し、ツールでアクションやデータ取得を行い、ハンドオフでサブエージェントにタスクを委譲できることを意味します。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 -- Web 検索でオンライン情報を探す -- ファイル検索と取得で独自データや接続を横断的に検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画立案、レポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索 によるオンライン情報の収集 +- ファイル検索 と取得によるプロプライエタリデータや接続先の横断検索 +- コンピュータ操作 によるコンピュータ上でのアクション実行 +- コード実行 によるデータ分析 +- 計画立案、レポート作成などに優れた特化エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に依存したい場合に有効です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知能に依拠したい場合に有効です。重要なポイントは次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、使い方、どのパラメーター内で動作すべきかを明確にします。 -2. アプリをモニタリングして改善を繰り返す。問題が起きる箇所を把握し、プロンプトを反復改善します。 -3. エージェントが内省して改善できるようにする。例: ループで実行して自己批評させる、エラーメッセージを与えて改善させる、など。 -4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越したエージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行力を向上できます。 +1. 良いプロンプトに投資してください。利用可能なツール、使い方、順守すべきパラメーターを明確にします。 +2. アプリを監視し、反復改善してください。どこで問題が起きたかを把握し、プロンプトを改善します。 +3. エージェントが内省して改善できるようにしてください。たとえばループで実行して自己批評させる、エラーメッセージを与えて改善させる、などです。 +4. 何でもこなす汎用エージェントではなく、単一のタスクに特化して優れたエージェントを用意しましょう。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資してください。エージェントの学習と性能向上に役立ちます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の面で、より決定的かつ予測可能になります。ここでの一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの観点で、より決定的で予測しやすくなります。よくあるパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次に使うエージェントを選ぶ、といった方法です。 -- 複数のエージェントをチェーンして、あるエージェントの出力を次のエージェントの入力へと変換する。ブログ記事の執筆タスクを、調査 → アウトライン作成 → 本文執筆 → 批評 → 改善、という一連のステップに分解できます。 -- タスクを実行するエージェントと、評価・フィードバックを行うエージェントを `while` ループで回し、評価者が一定の基準を満たしたと判断するまで繰り返す。 -- 複数のエージェントを並列実行する（例: `asyncio.gather` のような Python の基本コンポーネントを使用）。相互依存のない複数タスクがある場合、速度向上に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成します。たとえば、エージェントにタスクをいくつかの カテゴリー に分類させ、そのカテゴリーに基づいて次のエージェントを選ぶことができます。 +- あるエージェントの出力を次のエージェントの入力に変換して、複数のエージェントを連鎖させます。ブログ記事執筆のようなタスクを、調査をする - アウトラインを書く - 本文を書く - 批評する - 改善する、という一連のステップに分解できます。 +- 評価とフィードバックを行うエージェントと組み合わせて、タスクを実行するエージェントを `while` ループで回し、評価者が所定の基準を満たしたと判断するまで続けます。 +- 複数のエージェントを並列実行します。たとえば、Python の基本コンポーネント (primitives) である `asyncio.gather` などを使います。相互に依存しない複数のタスクがある場合の高速化に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) にいくつかの code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) にサンプルコードを多数用意しています。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 60fad9973..459621594 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは 1 回だけ実行すれば十分です。 +これは一度だけ行えば大丈夫です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行します。 +新しいターミナル セッションを開始するたびに実行してください。 ```bash source .venv/bin/activate @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -お持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +お持ちでない場合は、OpenAI API キーを作成するために[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初の エージェント の作成 +## 最初のエージェントの作成 -エージェント は instructions、名前、および任意の設定（例: `model_config`）で定義します。 +エージェントは instructions、名前、任意の config（例えば `model_config`）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## さらにいくつかの エージェント を追加 +## いくつかのエージェントを追加 -追加の エージェント も同様に定義できます。`handoff_descriptions` は、ハンドオフ のルーティングを判断するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## ハンドオフ の定義 +## ハンドオフの定義 -各 エージェント で、タスクを前進させる方法を決める際に選択できる、送信側の ハンドオフ オプションの在庫（一覧）を定義できます。 +各エージェントで、タスクを前進させるために選択できる送信側ハンドオフの選択肢の一覧を定義できます。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## エージェント オーケストレーションの実行 -ワークフローが実行され、トリアージ エージェント が 2 つの専門 エージェント 間を正しくルーティングすることを確認しましょう。 +ワークフローが実行され、トリアージ エージェントが 2 つの専門エージェントの間で正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -95,7 +95,7 @@ async def main(): ## ガードレールの追加 -入力または出力に対して実行するカスタム ガードレールを定義できます。 +入力または出力で実行するカスタム ガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてを組み合わせる +## すべてをまとめる -すべてを組み合わせ、ハンドオフ と入力 ガードレール を使用してワークフロー全体を実行しましょう。 +ハンドオフと入力ガードレールを使用して、すべてを組み合わせてワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェント 実行中に何が起きたかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動し、エージェント 実行のトレースを表示します。 +エージェント実行中に何が起きたかを確認するには、OpenAI ダッシュボードの Trace viewer に移動し、エージェント実行のトレースを表示してください。 ## 次のステップ -より複雑な エージェント フローの構築方法を学びましょう: +より複雑なエージェント フローの作り方を学びましょう: -- エージェント の設定方法について学ぶ: [エージェント](agents.md)。 -- [エージェント の実行](running_agents.md)について学ぶ。 -- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md)について学ぶ。 \ No newline at end of file +- [エージェント](agents.md)の設定について学ぶ。 +- [エージェントの実行](running_agents.md)について学ぶ。 +- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md)について学ぶ。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index a3875ddb1..4eb34548d 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,59 +4,59 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の realtime 機能を使って音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、互換性を損なう変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、リアルタイムで音声とテキスト入力を処理し、リアルタイム音声で応答する会話フローを実現します。OpenAI の Realtime API と持続的な接続を維持し、低レイテンシで自然な音声対話を可能にし、割り込みにも適切に対応します。 +Realtime エージェントは、会話フローを可能にし、音声およびテキスト入力をリアルタイムに処理し、リアルタイム音声で応答します。OpenAI の Realtime API と永続的な接続を維持し、低レイテンシで自然な音声対話や割り込みへのスムーズな対応ができます。 ## アーキテクチャ ### コアコンポーネント -realtime システムは、いくつかの主要コンポーネントで構成されます。 +realtime システムは複数の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェントです。 -- **RealtimeRunner**: 構成を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 1 回の対話セッションです。通常は ユーザー が会話を開始するたびに作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッションです。通常は ユーザー が会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤のモデルインターフェース（通常は OpenAI の WebSocket 実装）です。 ### セッションフロー -一般的な realtime セッションは、次のフローに従います。 +一般的な realtime セッションは次のフローに従います。 -1. **RealtimeAgent を作成** し、instructions、tools、handoffs を設定します。 -2. **RealtimeRunner をセットアップ** し、エージェントと構成オプションを指定します。 -3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返されます。 -4. **音声またはテキストメッセージを送信** します。`send_audio()` または `send_message()` を使用します。 -5. **イベントをリッスン** します。セッションを反復処理してイベントを受け取ります。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. **割り込みに対応** します。ユーザー がエージェントの発話に重ねて話した場合、現在の音声生成は自動的に停止します。 +1. instructions、tools、handoffs を指定して **RealtimeAgent を作成** します。 +2. エージェントと設定オプションで **RealtimeRunner をセットアップ** します。 +3. `await runner.run()` を使って **セッションを開始** し、RealtimeSession を受け取ります。 +4. `send_audio()` または `send_message()` を使って **音声またはテキストメッセージを送信** します。 +5. セッションを反復処理して **イベントを受信** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザー がエージェントにかぶせて話した場合の **割り込みを処理** します。現在の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、realtime モデルとの持続的な接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 -## エージェントの設定 +## エージェント設定 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。完全な API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェントレベルではなく、セッションレベルで構成します。 -- structured outputs はサポートされません（`outputType` は未対応です）。 -- 音声はエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 -- その他の機能（tools、handoffs、instructions）は同じように動作します。 +- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 +- structured outputs はサポートされません（`outputType` は未対応）。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- その他の機能（tools、handoffs、instructions）は同様に動作します。 -## セッションの設定 +## セッション設定 ### モデル設定 -セッション構成では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-4o-realtime-preview` など）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、対応するモダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の両方で設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、対応するモダリティ（テキストや音声）を設定できます。音声フォーマットは入力と出力の両方で設定可能で、デフォルトは PCM16 です。 -### オーディオ設定 +### 音声設定 -オーディオ設定は、セッションが音声の入出力をどのように処理するかを制御します。Whisper などのモデルを使用した入力音声の書き起こし、言語設定、専門用語の精度を高めるための書き起こしプロンプトを設定できます。ターン検出設定により、エージェントが応答を開始・終了するタイミングを制御できます（音声活動検出のしきい値、無音時間、検出音声の前後パディングのオプションを含む）。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、ドメイン固有用語の精度向上のための文字起こしプロンプトを指定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出された音声の前後のパディングなどを調整して、エージェントがいつ応答を開始・終了するかを制御します。 ## ツールと関数 @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、専門化されたエージェント間で会話を引き継ぐことができます。 +ハンドオフにより、専門特化したエージェント間で会話を引き継げます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションは、セッションオブジェクトを反復処理することでリッスンできるイベントを ストリーミング します。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に処理すべき主要イベントは次のとおりです。 +セッションはイベントをストリーミングし、セッションオブジェクトを反復処理することでリッスンできます。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。主に処理すべきイベントは次のとおりです。 -- **audio**: エージェントの応答からの raw 音声データ -- **audio_end**: エージェントの発話が完了 -- **audio_interrupted**: ユーザー がエージェントを割り込み -- **tool_start/tool_end**: ツール実行のライフサイクル -- **handoff**: エージェントのハンドオフが発生 -- **error**: 処理中にエラーが発生 +- **audio**: エージェントの応答からの raw 音声データ +- **audio_end**: エージェントの発話終了 +- **audio_interrupted**: ユーザー によるエージェントの割り込み +- **tool_start/tool_end**: ツール実行のライフサイクル +- **handoff**: エージェントのハンドオフが発生 +- **error**: 処理中にエラーが発生 -イベントの詳細は、[`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] をご覧ください。 +完全なイベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -Realtime エージェントでサポートされるのは出力 ガードレール のみです。パフォーマンス問題を避けるため、これらの ガードレール はデバウンスされ、リアルタイム生成中に（毎語ではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、構成可能です。 +Realtime エージェントでは出力用の ガードレール のみがサポートされます。これらのガードレールはデバウンスされ、リアルタイム生成時のパフォーマンス問題を避けるために（すべての単語ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレール は `RealtimeAgent` に直接アタッチするか、セッションの `run_config` 経由で提供できます。両方のソースからの ガードレール は併せて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて指定できます。両方のソースからのガードレールは併用されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレール がトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンスの動作により、安全性とリアルタイム性能要件のバランスを取ります。テキストエージェントと異なり、realtime エージェントは ガードレール が作動しても Exception を発生させません。 +ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイムのパフォーマンス要件のバランスをとります。テキストエージェントと異なり、realtime エージェントはガードレールが発動しても **Exception** をスローしません。 -## オーディオ処理 +## 音声処理 [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使って音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使ってテキストを送信します。 -音声出力については、`audio` イベントをリッスンし、任意のオーディオライブラリで音声データを再生します。ユーザー がエージェントを割り込んだ際に即座に再生を停止し、キューにある音声をクリアするため、`audio_interrupted` イベントを必ずリッスンしてください。 +音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで再生します。ユーザー がエージェントを割り込んだ際に即時に再生を停止し、キューにある音声をクリアするため、`audio_interrupted` イベントを必ずリッスンしてください。 ## 直接モデルアクセス -基盤となるモデルにアクセスして、カスタムリスナーを追加したり高度な操作を実行したりできます。 +基盤となるモデルにアクセスして、カスタムリスナーを追加したり、高度な操作を実行したりできます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、接続を低レベルに制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、接続を低レベルで制御する必要がある高度なユースケースに向けて、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## コード例 +## 例 -完全に動作するコード例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。UI コンポーネントあり／なしのデモを含みます。 \ No newline at end of file +完全な動作する code examples は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI コンポーネントの有無それぞれのデモが含まれます。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index d5b771b83..73ed8570f 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,26 +4,26 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声対話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントの作成方法を説明します。 +Realtime エージェントは、 OpenAI の Realtime API を使用して AI 音声会話を実現します。このガイドでは、最初の Realtime 音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、重大な変更が入る可能性があります。 +Realtime エージェントはベータ版です。実装の改良に伴い、互換性のない変更が入る可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 ## インストール -まだの場合は、OpenAI Agents SDK をインストールします: +まだの場合は、 OpenAI Agents SDK をインストールします: ```bash pip install openai-agents ``` -## 最初のリアルタイムエージェントの作成 +## はじめての Realtime エージェントの作成 ### 1. 必要なコンポーネントのインポート @@ -32,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. リアルタイムエージェントの作成 +### 2. Realtime エージェントの作成 ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. ランナーのセットアップ +### 3. Runner のセットアップ ```python runner = RealtimeRunner( @@ -81,7 +81,7 @@ asyncio.run(main()) ## 完全なコード例 -以下は動作する完全な例です: +動作する完全なコード例は次のとおりです: ```python import asyncio @@ -139,40 +139,40 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-4o-realtime-preview`) -- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストおよび/または音声を有効化 (`["text", "audio"]`) +- `model_name`: 利用可能な Realtime モデルから選択 (例: `gpt-4o-realtime-preview`) +- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストや音声の有効化 (`["text", "audio"]`) -### 音声設定 +### オーディオ設定 -- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力音声の形式 -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力音声の形式 +- `input_audio_transcription`: 書き起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声活動のしきい値 (0.0-1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前の音声パディング +- `type`: 検出方法 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動の閾値 (0.0–1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [リアルタイムエージェントの詳細](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダ内の動作する sample code を参照 -- エージェントにツールを追加 -- エージェント間のハンドオフを実装 -- 安全性のためのガードレールを設定 +- [Realtime エージェントについて詳しく学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作するコード例を参照 +- エージェントにツールを追加 +- エージェント間のハンドオフを実装 +- 安全性のためのガードレールを設定 ## 認証 -OpenAI API キーが環境に設定されていることを確認してください: +環境に OpenAI API キーが設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション作成時に直接渡します: +また、セッション作成時に直接渡すこともできます: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 7d8fb0fdd..4cbaf6485 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,29 +4,29 @@ search: --- # リリースプロセス/変更履歴 -本プロジェクトは、`0.Y.Z` という形式のセマンティック バージョニングを一部変更して採用しています。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 +本プロジェクトは、`0.Y.Z` という形式の、やや変更したセマンティック バージョニングに従います。先頭の `0` は、この SDK が依然として急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 ## マイナー（`Y`）バージョン -ベータではない公開インターフェースに対する **破壊的変更** の場合、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれることがあります。 +ベータではない公開インターフェースに対する **breaking changes** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には breaking changes が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 +breaking changes を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 ## パッチ（`Z`）バージョン -後方互換のある変更では `Z` を増やします。 +後方互換のある変更については `Z` を増やします。 - バグ修正 - 新機能 - 非公開インターフェースの変更 - ベータ機能の更新 -## 破壊的変更の履歴 +## 互換性を壊す変更の変更履歴 ### 0.2.0 -このバージョンでは、以前は引数として `Agent` を受け取っていた一部の箇所が、代わりに `AgentBase` を受け取るようになりました。たとえば、MCP サーバーでの `list_tools()` 呼び出しです。これは純粋に型に関する変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正してください。 +このバージョンでは、以前は引数として `Agent` を受け取っていたいくつかの箇所が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、MCP サーバーでの `list_tools()` 呼び出しです。これは純粋に型に関する変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承するすべてのクラスにこれらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承するクラスには、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index ce8e74e31..7b30edc6f 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -この SDK は、ターミナル上でエージェントの挙動をすばやく対話的にテストできる `run_demo_loop` を提供します。 +この SDK は、`run_demo_loop` を提供しており、ターミナル上でエージェントの挙動を素早く対話的にテストできます。 ```python import asyncio @@ -18,6 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間の会話履歴を保持します。デフォルトでは、生成されたモデル出力をそのままストリーミングします。上記の例を実行すると、`run_demo_loop` は対話的なチャットセッションを開始します。入力を継続的に求め、ターン間の会話全体の履歴を記憶するため（エージェントは何が議論されたかを把握できます）、エージェントの応答は生成され次第リアルタイムに自動であなたへストリーミングされます。 +`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成と同時にモデル出力をストリーミングします。上記の例を実行すると、`run_demo_loop` は対話型チャットセッションを開始します。継続的に入力を求め、ターン間の会話全体の履歴を記憶するため（エージェントは何が議論されたかを把握できます）、生成されると同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 -このチャットセッションを終了するには、`quit` または `exit` と入力して（Enter キーを押す）か、`Ctrl-D` キーボードショートカットを使用します。 \ No newline at end of file +このチャットセッションを終了するには、`quit` または `exit` と入力して（Enter を押す）か、`Ctrl-D` キーボードショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index dd9d14085..e88e9b68a 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -9,48 +9,48 @@ search: - [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） - [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれます。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、最も有用な情報の多くはそこに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行された エージェント の最終出力が含まれます。これは次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 -- 最後の エージェント に `output_type` が定義されていない場合は `str` -- エージェント に出力型が定義されている場合は、`last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `output_type` が定義されていない場合は `str` +- エージェントに出力タイプが定義されている場合は、`last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。これは ハンドオフ のために静的型付けできません。ハンドオフ が発生すると、どの エージェント でも最後の エージェント になり得るため、可能な出力型の集合を静的に知ることはできません。 + `final_output` の型は `Any` です。ハンドオフがあるため、静的な型付けはできません。ハンドオフが発生する場合、どのエージェントが最後になるか分からないため、可能な出力タイプの集合を静的に特定できないためです。 ## 次ターンの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、提供した元の入力と、エージェント の実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、ある エージェント 実行の出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが簡単になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、提供した元の入力に、エージェントの実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが簡単になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行された エージェント が含まれます。アプリケーションによっては、次回 ユーザー が何かを入力する際に役立つことが多いです。たとえば、フロントラインのトリアージ エージェント が言語別の エージェント に ハンドオフ する場合、最後の エージェント を保存しておき、次回 ユーザー がメッセージを送るときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、これは次回 ユーザー が入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージ用エージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存しておき、次回 ユーザー がエージェントにメッセージを送る際に再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した生のアイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを表します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM が ハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM のツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフ が発生したことを示します。raw アイテムは ハンドオフ ツール呼び出しに対するツールのレスポンスです。アイテムからソース/ターゲットの エージェント にもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツールのレスポンスです。アイテムからツールの出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は、LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。生のアイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフ ツールを呼び出したことを示します。生のアイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。生のアイテムはハンドオフ ツール呼び出しに対するツール応答です。アイテムから送信元/宛先のエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。生のアイテムはツールの応答です。アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。生のアイテムは生成された推論です。 ## その他の情報 -### ガードレールの結果 +### ガードレール結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、該当する場合に ガードレール の結果が含まれます。ガードレール の結果には、記録または保存したい有用な情報が含まれることがあるため、これらを利用できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果（ある場合）が含まれます。ガードレール結果には、ログや保存に役立つ情報が含まれることがあるため、参照できるようにしています。 -### raw 応答 +### 生の応答 [`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。ほとんどの場合これは不要ですが、必要に応じて利用できます。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。ほとんどの場合は不要ですが、必要に応じて参照できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index f6fb1c75c..4c78483fe 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -8,7 +8,7 @@ search: 1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM を ストリーミング モードで呼び出し、受信したイベントを逐次 ストリーミング します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミング モードで呼び出し、受信したイベントを順次ストリーミングします。 ```python from agents import Agent, Runner @@ -27,49 +27,49 @@ async def main(): ## エージェントループ -`Runner` の run メソッドを使用する際は、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または OpenAI Responses API のアイテムのリストのいずれかです。 +`Runner` の run メソッドを使うときは、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）または入力アイテムのリスト（OpenAI Responses API のアイテム）です。 -Runner は次のループを実行します。 +runner は次のループを実行します。 1. 現在のエージェントと現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 - 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新してループを再実行します。 - 3. LLM が ツール呼び出し を生成した場合、それらを実行して結果を追加し、ループを再実行します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新してループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行して結果を追加し、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、かつツール呼び出しが存在しないことです。 + LLM の出力が「最終出力」と見なされる規則は、望ましい型のテキスト出力を生成し、ツール呼び出しがない場合です。 ## ストリーミング -ストリーミング を使用すると、LLM の実行中に ストリーミング イベントも受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に、生成されたすべての新規出力を含む実行の完全な情報が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングを使用すると、LLM の実行に伴うストリーミング イベントを追加で受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 ## 実行設定 `run_config` パラメーターでは、エージェント実行のグローバル設定を構成できます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関わらず、使用するグローバルな LLM モデルを設定できます。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダで、既定は OpenAI です。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関係なく、使用するグローバルな LLM モデルを設定できます。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 - [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力の ガードレール のリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフ に入力フィルターが設定されていない場合に適用するグローバル入力フィルターです。入力フィルターにより、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化します。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力／出力のガードレールのリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに入力フィルターが未設定の場合に適用する、すべてのハンドオフに対するグローバルな入力フィルターです。入力フィルターを使うと、新しいエージェントに送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化できます。 - [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングにおけるワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使用できます。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングにおけるワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` を設定することを推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 -## 会話/チャットスレッド +## 会話／チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（つまり 1 回以上の LLM 呼び出し）が実行される可能性がありますが、チャット会話における 1 つの論理ターンを表します。例: +任意の run メソッドの呼び出しは、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）の実行につながる場合がありますが、チャット会話における 1 回の論理的なターンを表します。例: -1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへ ハンドオフ。2 番目のエージェントがさらにツールを実行し、その後に出力を生成。 +1. ユーザー ターン: ユーザーがテキストを入力 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフし、2 番目のエージェントがさらにツールを実行してから出力を生成します。 -エージェントの実行の最後に、ユーザーに何を表示するかを選べます。たとえば、エージェントが生成したすべての新規アイテムを表示するか、最終出力だけを表示するかです。いずれにしても、その後にユーザーが追質問をする可能性があり、その場合は再度 run メソッドを呼び出します。 +エージェント実行の最後に、ユーザーに何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムをユーザーに表示する、または最終出力のみを表示する、などです。いずれにせよ、ユーザーがフォローアップの質問をするかもしれないので、その場合は再度 run メソッドを呼び出せます。 -### 手動での会話管理 +### 手動の会話管理 次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使えば、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動処理できます。 +より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動で扱えます。 ```python from agents import Agent, Runner, SQLiteSession @@ -104,6 +104,7 @@ async def main(): # Create session instance session = SQLiteSession("conversation_123") + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session) @@ -116,26 +117,26 @@ async def main(): # California ``` -Sessions は自動的に次を行います。 +Sessions は自動で次を行います。 -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- 異なるセッション ID ごとに個別の会話を維持 +- 各実行の前に会話履歴を取得 +- 各実行の後に新しいメッセージを保存 +- セッション ID ごとに別々の会話を維持 詳細は [Sessions のドキュメント](sessions.md) を参照してください。 -## 長時間実行エージェントと human-in-the-loop +## 長時間実行エージェントとヒューマン・イン・ザ・ループ -Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop タスクを含む、耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を、ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) をご覧ください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使用すると、ヒューマン・イン・ザ・ループのタスクを含む、永続的で長時間実行のワークフローを実行できます。長時間実行タスクを完了するために Temporal と Agents SDK が連携して動作するデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で確認でき、[こちらのドキュメント](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)も参照してください。 ## 例外 -SDK は特定の場合に例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 +この SDK は、特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかの特定の例外はすべてこの型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡した `max_turns` 制限を超えた場合に送出されます。指定されたやり取り回数内にタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。例: - - 不正な JSON: 特定の `output_type` が定義されている場合に、ツール呼び出しや直接の出力で不正な JSON 構造が提供されたとき。 - - 予期しないツール関連の失敗: モデルが期待どおりの方法でツールを使用できなかったとき -- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（この SDK を用いてコードを書く人）が誤りを犯した場合に送出されます。これは通常、不適切なコード実装、無効な設定、または SDK の API の誤用が原因です。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ、入力 ガードレール または出力 ガードレール の条件が満たされたときに送出されます。入力 ガードレール は処理前に受信メッセージを検査し、出力 ガードレール はエージェントの最終応答を配信前に検査します。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外はすべて、この型から派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに渡した `max_turns` の上限をエージェントの実行が超えたときに送出されます。これは、指定された対話ターン数内にエージェントがタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤のモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。次を含みます。 + - 不正な JSON: 特定の `output_type` が定義されている場合に特に、ツール呼び出しや直接の出力でモデルが不正な JSON 構造を返したとき。 + - 予期しないツール関連の失敗: モデルが期待どおりの方法でツールを使用できなかったとき。 +- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（この SDK を使ってコードを書く人）がエラーを起こしたときに送出されます。これは通常、誤ったコード実装、無効な設定、または SDK の API の誤用に起因します。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ、入力ガードレールまたは出力ガードレールの条件が満たされたときに送出されます。入力ガードレールは処理前に受信メッセージを検査し、出力ガードレールは配信前にエージェントの最終応答を検査します。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index c4c79a5f4..16b6466fd 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -OpenAI Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 +Agents SDK には、複数のエージェント実行にまたがって会話履歴を自動で維持するための組み込みセッションメモリがあり、ターン間で手動で `.to_input_list()` を扱う必要がなくなります。 -セッションは特定のセッションに対して会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、チャットアプリケーションや、エージェントに以前のやり取りを記憶してほしいマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話の構築に特に有用です。 ## クイックスタート @@ -51,11 +51,11 @@ print(result.final_output) # "Approximately 39 million" セッションメモリが有効な場合: -1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）はすべて自動的にセッションに保存されます。 -3. **コンテキストの維持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーが自動的にそのセッションの会話履歴を取得し、入力アイテムの先頭に追加します。 +2. **各実行の後**: 実行中に生成された新規アイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）は、すべて自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの以降の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出して、実行間で会話状態を管理する必要がなくなります。 +これにより、ターン間で `.to_input_list()` を手動で呼び出し、会話状態を管理する必要がなくなります。 ## メモリ操作 @@ -88,7 +88,7 @@ await session.clear_session() ### 修正のための pop_item の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に特に便利です: +`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたい場合に特に役立ちます: ```python from agents import Agent, Runner, SQLiteSession @@ -128,8 +128,8 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API メモリ -[OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api) を使用して、独自のデータベースを管理せずに -会話状態を永続化します。これは、会話履歴の保存にすでに OpenAI ホストのインフラに依存している場合に役立ちます。 +[OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api) を使用して、 +独自のデータベースを管理せずに会話状態を永続化します。これは、会話履歴の保存にすでに OpenAI がホストするインフラストラクチャに依存している場合に便利です。 ```python from agents import OpenAIConversationsSession @@ -190,11 +190,11 @@ result2 = await Runner.run( ### SQLAlchemy ベースのセッション -より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）をセッションストレージとして使用できます。 +より高度なユースケース向けに、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、セッションストレージに SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 -**例 1: `from_url` とインメモリ SQLite の使用** +**例 1: インメモリ SQLite で `from_url` を使用** -これは最も簡単な開始方法で、開発やテストに最適です。 +これは最も簡単な方法で、開発とテストに最適です。 ```python import asyncio @@ -215,9 +215,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy エンジンの使用** +**例 2: 既存の SQLAlchemy エンジンを使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性が高いです。これをセッションに直接渡すことができます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っていることが多いでしょう。これをそのままセッションに渡せます。 ```python import asyncio @@ -248,7 +248,7 @@ if __name__ == "__main__": ## カスタムメモリ実装 -[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに準拠するクラスを作成して、独自のセッションメモリを実装できます: ```python from agents.memory.session import SessionABC @@ -295,19 +295,19 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理するのに役立つ意味のあるセッション ID を使用します: +会話を整理しやすい、意味のあるセッション ID を使用します: -- ユーザー単位: `"user_12345"` -- スレッド単位: `"thread_abc123"` -- コンテキスト単位: `"support_ticket_456"` +- User ベース: `"user_12345"` +- スレッドベース: `"thread_abc123"` +- コンテキストベース: `"support_ticket_456"` ### メモリの永続化 -- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します -- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します -- 既存のデータベースを持つ本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True")`）を使用します -- OpenAI ホストのストレージを使用したい場合は（`OpenAIConversationsSession()`）、OpenAI Conversations API に履歴を保存します -- より高度なユースケース向けに、他の本番システム（Redis、Django など）用のカスタムセッションバックエンドの実装を検討します +- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用 +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用 +- 既存のデータベースを利用する本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 +- OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用して、会話履歴を OpenAI Conversations API に保存することも可能 +- さらに高度なユースケース向けに、他の本番システム（Redis、Django など）用のカスタムセッションバックエンドの実装を検討 ### セッション管理 @@ -333,9 +333,9 @@ result2 = await Runner.run( ) ``` -## 完全な例 +## 完全なコード例 -セッションメモリが動作する完全な例を次に示します: +セッションメモリの動作を示す完全なコード例です: ```python import asyncio @@ -399,7 +399,7 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントについては、以下を参照してください: +詳細な API ドキュメントは次を参照してください: - [`Session`][agents.memory.Session] - プロトコルインターフェース - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index f46de4652..47f853667 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングにより、進行中のエージェントの run の更新を購読できます。これは、エンドユーザーに進捗や部分的な応答を表示するのに役立ちます。 +ストリーミングを使うと、エージェントの実行が進む間、その更新を購読できます。これはエンドユーザーに進行状況や部分的な応答を表示するのに役立ちます。 ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これは [`RunResultStreaming`][agents.result.RunResultStreaming] を返します。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 ## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。形式は OpenAI Responses API で、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、応答メッセージが生成され次第ユーザーにストリーミングしたい場合に便利です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これは OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、生成され次第、応答メッセージをユーザーにストリーミングしたい場合に便利です。 -たとえば、次の例は LLM によって生成されたテキストをトークンごとに出力します。 +たとえば、次は LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Run アイテムイベントとエージェントイベント +## 実行アイテムイベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は現在のエージェントが変更されたとき（たとえばハンドオフの結果として）の更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」といったレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（たとえばハンドオフの結果として）の更新を提供します。 -たとえば、次の例は raw イベントを無視し、ユーザーに更新をストリーミングします。 +たとえば、次は raw イベントを無視し、ユーザーに更新をストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 81c5265b8..7eaaac171 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント によるアクションの実行、例えばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作 を可能にします。Agent SDK には 3 つのツールクラスがあります。 +ツールは エージェント にアクションを実行させます。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agent SDK には 3 つのツールのクラスがあります: -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で実行されます。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供します。 -- Function calling: 任意の Python 関数をツールとして利用できます。 -- ツールとしてのエージェント: エージェントをツールとして利用でき、ハンドオフ せずにエージェントが他のエージェントを呼び出せます。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は リトリーバル、Web 検索、コンピュータ操作 をホスト型ツールとして提供します。 +- Function calling: 任意の Python 関数をツールとして使用できます。 +- ツールとしてのエージェント: エージェント をツールとして使用でき、ハンドオフ せずに他の エージェント を呼び出せます。 ## ホスト型ツール -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供します。 +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合に、いくつかの組み込みツールを提供します: - [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web を検索させます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストア から情報を取得できます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を取得できます。 - [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を可能にします。 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバーのツールをモデルに公開します。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバー のツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はあなたのマシン上でシェルコマンドを実行します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして使用できます。Agents SDK が自動的にセットアップします。 +任意の Python 関数をツールとして使用できます。Agents SDK が自動的にツールを設定します: -- ツール名は Python 関数名になります（任意で名前を指定可能） -- ツールの説明は関数の docstring から取得します（任意で説明を指定可能） +- ツール名は Python 関数名になります（または任意の名前を指定できます） +- ツールの説明は関数の docstring から取得します（または説明を指定できます） - 関数入力のスキーマは、関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り関数の docstring から取得します +- 各入力の説明は、無効化しない限り、関数の docstring から取得されます -Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、`pydantic` でスキーマを作成します。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、スキーマ作成には `pydantic` を使用します。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 任意の Python 型を関数の引数に使用でき、関数は同期でも非同期でも構いません。 -2. docstring があれば、説明および引数説明の取得に使用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring スタイルなどのオーバーライドも設定できます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期どちらでも構いません。 +2. Docstring がある場合、説明および引数の説明の取得に使用します。 +3. 関数は任意で `context` を取れます（最初の引数である必要があります）。ツール名や説明、docstring スタイルなどのオーバーライドも設定できます。 4. デコレートした関数をツールのリストに渡せます。 -??? note "出力を表示" +??? note "展開して出力を見る" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を指定する必要があります。 +Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。以下を指定する必要があります: - `name` - `description` - 引数の JSON スキーマである `params_json_schema` -- [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツールの出力を文字列として返す非同期関数 `on_invoke_tool` +- [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツール出力を文字列で返す非同期関数 `on_invoke_tool` ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 自動引数解析と docstring 解析 +### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマ抽出のために関数シグネチャを自動解析し、ツールおよび各引数の説明抽出のために docstring を解析します。注意点は次のとおりです。 +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび個別の引数の説明を抽出するために docstring を解析します。注意点: -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を理解し、全体のスキーマを表現する Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDicts など、ほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 +1. シグネチャの解析は `inspect` モジュールで行います。型アノテーションから引数の型を理解し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDicts など、ほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。サポートされている docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますがベストエフォートであり、`function_tool` を呼び出す際に明示的に設定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することも可能です。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 ## ツールとしてのエージェント -ワークフローによっては、ハンドオフ ではなく、中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。エージェントをツールとしてモデル化することで実現できます。 +一部のワークフローでは、制御をハンドオフ するのではなく、中央の エージェント が専門特化した エージェント 群のオーケストレーションを行いたい場合があります。エージェント をツールとしてモデリングすることで実現できます。 ```python from agents import Agent, Runner @@ -269,7 +269,7 @@ async def main(): ### ツール化エージェントのカスタマイズ -`agent.as_tool` 関数は、エージェントを簡単にツール化するためのユーティリティです。ただし、すべての設定をサポートするわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 +`agent.as_tool` 関数は、エージェント を簡単にツール化するためのユーティリティです。ただし、すべての設定をサポートするわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### カスタム出力抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。例えば次のような場合に有用です。 +場合によっては、中央の エージェント に返す前に、ツール化した エージェント の出力を加工したいことがあります。たとえば次のような場合に有用です: - サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 -- エージェントの最終回答を変換・再フォーマットする（例: Markdown をプレーンテキストや CSV に変換）。 -- 出力を検証し、エージェントの応答が欠落または不正な場合にフォールバック値を提供する。 +- エージェント の最終回答を変換または再整形する（例: Markdown をプレーンテキストや CSV に変換）。 +- 出力を検証したり、エージェント の応答が欠落・不正な場合にフォールバック値を提供する。 -これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで行えます。 +これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 条件付きツール有効化 -実行時に `is_enabled` パラメーター を使って エージェント ツールを条件付きで有効化・無効化できます。これにより、コンテキスト、ユーザー の嗜好、実行時条件に基づいて LLM に提供するツールを動的に絞り込めます。 +実行時に `is_enabled` パラメーター を使用して エージェント ツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザー の設定、実行時条件に基づいて LLM に提供するツールを動的にフィルタリングできます。 ```python import asyncio @@ -372,24 +372,24 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーター は次を受け付けます。 -- **Boolean values** : `True`（常に有効）または `False`（常に無効） -- **Callable functions** : `(context, agent)` を受け取り boolean を返す関数 -- **Async functions** : 複雑な条件ロジックのための非同期関数 +`is_enabled` パラメーター は次を受け付けます: +- **Boolean 値**: `True`（常に有効）または `False`（常に無効） +- **Callable 関数**: `(context, agent)` を受け取り boolean を返す関数 +- **Async 関数**: 複雑な条件ロジック向けの非同期関数 -無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です。 +無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: - ユーザー 権限に基づく機能ゲーティング -- 環境別のツール可用性（dev と prod） -- A/B テストによるツール構成の比較 +- 環境別のツール可用性（開発 vs 本番） +- 異なるツール構成の A/B テスト - 実行時状態に基づく動的ツールフィルタリング ## 関数ツールにおけるエラー処理 `@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを提供する関数です。 -- 既定（何も渡さない場合）では、エラーが発生したことを LLM に伝える `default_tool_error_function` を実行します。 +- 既定（何も渡さない）では、エラー発生を LLM に伝える `default_tool_error_function` が実行されます。 - 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、あなたが処理する必要があります。これは、モデルが不正な JSON を生成した場合の `ModelBehaviorError`、あなたのコードがクラッシュした場合の `UserError` などになり得ます。 +- 明示的に `None` を渡すと、ツール呼び出しのエラーは再スローされ、呼び出し側で処理できます。モデルが不正な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などが該当します。 ```python from agents import function_tool, RunContextWrapper @@ -412,4 +412,4 @@ def get_user_profile(user_id: str) -> str: ``` -手動で `FunctionTool` オブジェクトを作成する場合は、`on_invoke_tool` 関数内でエラー処理を行う必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index a35cb8883..17fb42f30 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェント実行中に発生するイベントの包括的な記録を収集します。たとえば LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使って、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録（ LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントまで）を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使うと、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。トレーシングを無効化する方法は 2 つあります: + トレーシングは既定で有効です。トレーシングを無効化する方法は 2 つあります。 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます - 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 2. 1 回の実行のみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** +***OpenAI の APIs を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります: - - `workflow_name`: これは論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service"。 - - `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースを関連付けるために使用します。たとえばチャットスレッドの ID など。 - - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースの任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: - - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを表す `trace_id` - - 親スパン (ある場合) を指す `parent_id` - - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報などが含まれます。 +- **トレース (Traces)** は「ワークフロー」の単一のエンドツーエンドの処理を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースを関連付けます。たとえばチャットスレッド ID などが使えます。 + - `disabled`: True の場合、このトレースは記録されません。 + - `metadata`: トレースの任意のメタデータ。 +- **スパン (Spans)** は開始時刻と終了時刻を持つ処理を表します。スパンには次が含まれます: + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを示す `trace_id` + - このスパンの親スパン（ある場合）を指す `parent_id` + - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLM 生成に関する情報を含みます。 ## 既定のトレーシング -デフォルトでは、SDK は次をトレースします: +既定では、 SDK は次をトレースします: -- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます -- エージェントが実行されるたびに、`agent_span()` でラップされます -- LLM 生成は `generation_span()` でラップされます -- 関数ツール呼び出しはそれぞれ `function_span()` でラップされます -- ガードレールは `guardrail_span()` でラップされます -- ハンドオフは `handoff_span()` でラップされます -- 音声入力 (音声認識) は `transcription_span()` でラップされます -- 音声出力 (音声合成) は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の下に親子付けされる場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体は `trace()` でラップされます +- エージェントが実行されるたびに `agent_span()` でラップされます +- LLM の生成は `generation_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます +- ガードレールは `guardrail_span()` でラップされます +- ハンドオフは `handoff_span()` でラップされます +- 音声入力（音声認識）は `transcription_span()` でラップされます +- 音声出力（音声合成）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の子になる場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できます。または、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 +既定では、トレース名は "Agent workflow" です。`trace` を使う場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 -加えて、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定し、トレースを別の宛先へ送信できます (置き換え、または二次宛先として)。 +さらに、[カスタムトレース プロセッサー](#custom-tracing-processors) をセットアップして、他の宛先へトレースを送信できます（置き換え、またはセカンダリ宛先として）。 -## 高レベルのトレース +## より高レベルのトレース -`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `trace()` でラップします。 +`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。これには、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,46 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. `with trace()` 内に 2 回の `Runner.run` 呼び出しを入れているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: +[`trace()`][agents.tracing.trace] 関数でトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: -1. 推奨: トレースをコンテキストマネージャとして使用します。つまり `with trace(...) as my_trace` のようにします。これにより適切なタイミングでトレースが自動で開始・終了します。 +1. 推奨: トレースをコンテキストマネージャとして使用します（例: `with trace(...) as my_trace`）。これにより適切なタイミングで自動的に開始・終了します。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。つまり並行処理でも自動的に機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これは自動的に並行処理で機能することを意味します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が利用可能です。 +さまざまな [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。一般には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。 -スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される最も近い現在のスパンの下にネストされます。 +スパンは自動的に現在のトレースの一部になり、最も近い現在のスパンの下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。 -## 機微データ +## 機微なデータ 一部のスパンは機微なデータを取得する可能性があります。 -`generation_span()` は LLM 生成の入力/出力を、`function_span()` は関数呼び出しの入力/出力を保存します。機微なデータを含む場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらに機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によって、そのデータの取得を無効化できます。 -同様に、音声スパンにはデフォルトで入力および出力音声の base64 エンコード済み PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。 +同様に、音声スパンは既定で入力および出力音声の base64 エンコードの PCM データを含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して、この音声データの取得を無効化できます。 -## カスタム トレーシング プロセッサー +## カスタムトレーシング プロセッサー -トレーシングの高レベルアーキテクチャは次のとおりです: +トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時に、トレースを作成する責任を持つグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 -- `TraceProvider` には [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。これがスパンとトレースをバッチで OpenAI バックエンドにエクスポートします。 +- 初期化時に、トレース作成を担うグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 +- `TraceProvider` は [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成され、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。エクスポーターはスパンとトレースを OpenAI バックエンドへバッチでエクスポートします。 -デフォルト設定をカスタマイズして、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポーターの動作変更を行うには、次の 2 つの方法があります: +既定のセットアップをカスタマイズして、代替または追加のバックエンドにトレースを送る、あるいはエクスポーターの動作を変更するには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備できたときに受け取る「追加」のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理が可能になります。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに「置き換え」られます。これを行うと、OpenAI バックエンドにトレースは送信されません。送信したい場合は、それを行う `TracingProcessor` を含める必要があります。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが用意でき次第それらを受け取る「追加の」トレースプロセッサーを追加できます。これにより、 OpenAI のバックエンドへ送信するのに加えて独自の処理も実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、既定のプロセッサーを独自のトレースプロセッサーで「置き換え」られます。OpenAI バックエンドへトレースを送信するには、その役割を果たす `TracingProcessor` を含める必要があります。 -## Non-OpenAI モデルでのトレーシング +## 非 OpenAI モデルでのトレーシング -OpenAI の API キーを Non‑OpenAI モデルで使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 +OpenAI の API キーを非 OpenAI モデルで使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -124,28 +124,28 @@ agent = Agent( ) ``` -## 注意 -- OpenAI Traces ダッシュボードで無料のトレースを表示します。 +## メモ +- 無料のトレースは Openai Traces ダッシュボードで閲覧できます。 ## 外部トレーシング プロセッサー一覧 -- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) -- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) -- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) -- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) -- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) +- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 4fb6fa954..509ae2f1b 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -4,21 +4,21 @@ search: --- # 使用状況 -Agents SDK は各実行のトークン使用状況を自動的に追跡します。実行コンテキストからアクセスでき、コストの監視、上限の適用、分析の記録に使えます。 +Agents SDK は各実行ごとにトークン使用状況を自動追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。 ## 追跡対象 -- **requests**: 実行された LLM API 呼び出しの数 -- **input_tokens**: 送信した入力トークンの合計 -- **output_tokens**: 受信した出力トークンの合計 -- **total_tokens**: 入力 + 出力 -- **details**: +- **requests** : 実行された LLM API 呼び出し数 +- **input_tokens** : 送信された入力トークン総数 +- **output_tokens** : 受信した出力トークン総数 +- **total_tokens** : 入力 + 出力 +- **details** : - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` ## 実行からの使用状況へのアクセス -`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況にアクセスします。 +`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況を参照します。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 +使用状況は実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 ## セッションでの使用状況へのアクセス -`Session`（例: `SQLiteSession`）を使う場合、`Runner.run(...)` への各呼び出しは、その実行専用の使用状況を返します。セッションは文脈用に会話履歴を保持しますが、各実行の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行に対する使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -46,11 +46,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、その実行のみを表します。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況の指標は、その実行に限られます。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 -## フックでの使用状況 +## フックでの使用状況の利用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用状況を記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトに `usage` が含まれます。これにより、重要なライフサイクル時点で使用状況を記録できます。 ```python class MyHooks(RunHooks): @@ -61,8 +61,8 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは次をご覧ください: +詳細な API ドキュメントは以下を参照してください。 -- [`Usage`][agents.usage.Usage] - 使用状況追跡のデータ構造 +- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況にアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡ライフサイクルへのフック \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 使用状況トラッキングのライフサイクルにフック \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 70562e0b4..76ec80429 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,7 +4,7 @@ search: --- # エージェントの可視化 -エージェントの可視化では、 **Graphviz** を使ってエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を使用してエージェントとその関係を構造化したグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックスで表現されます。 -- **MCP サーバー** は灰色のボックスで表現されます。 -- **ツール** は緑の楕円で表現されます。 -- **ハンドオフ** は一方のエージェントから別のエージェントへの有向エッジです。 +- **エージェント** は黄色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 +- **ツール** は緑の楕円で表されます。 +- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジで表されます。 ### 使用例 @@ -67,27 +67,27 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェント グラフ](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -これは、 **トリアージ エージェント** の構造と、そのサブエージェントやツールへの接続を視覚的に表現するグラフを生成します。 +これは、 **triage エージェント** と、そのサブエージェントやツールへの接続の構造を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されるグラフには次が含まれます: +生成されたグラフには以下が含まれます: -- エントリーポイントを示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた **長方形** のエージェント。 -- 緑で塗りつぶされた **楕円** のツール。 -- 灰色で塗りつぶされた **長方形** の MCP サーバー。 -- 相互作用を示す有向エッジ: - - エージェント間のハンドオフには **実線の矢印**。 - - ツールの呼び出しには **点線の矢印**。 - - MCP サーバーの呼び出しには **破線の矢印**。 -- 実行の終了地点を示す **終了ノード** (`__end__`)。 +- エントリーポイントを示す **開始ノード** (`__start__`) +- 黄色で塗りつぶされた **長方形** で表されるエージェント +- 緑で塗りつぶされた **楕円** で表されるツール +- 灰色で塗りつぶされた **長方形** で表される MCP サーバー +- 相互作用を示す有向エッジ: + - エージェント間のハンドオフには **実線の矢印** + - ツール呼び出しには **点線の矢印** + - MCP サーバー呼び出しには **破線の矢印** +- 実行が終了する場所を示す **終了ノード** (`__end__`) -**注:** MCP サーバーは最新版の -`agents` パッケージでレンダリングされます（ **v0.2.8** で確認済み）。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**注:** MCP サーバーは、最近のバージョンの +`agents` パッケージ（ **v0.2.8** で検証済み）でレンダリングされます。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 46be7355b..b9aacd9a9 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント型のワークフローを音声アプリに簡単に変換できるクラスです。実行したいワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声に戻す処理までを行います。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント ワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理まで面倒を見ます。 ```mermaid graph LR @@ -34,28 +34,28 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際には、次のような項目を設定できます。 +パイプラインを作成するとき、次の項目を設定できます: -1. 毎回新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +1. 新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] 2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル -3. 次のような設定を行える [`config`][agents.voice.pipeline_config.VoicePipelineConfig] +3. 次のような項目を設定できる [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - モデル名をモデルにマッピングできるモデルプロバイダー - トレーシング（トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） - - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） + - プロンプト、言語、使用するデータ型など、TTS と STT モデルの設定 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます: -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の書き起こしがあり、その結果だけを生成したい場合に使用します。話者が話し終えたタイミングの検出が不要なケース、例えば事前録音した音声や、ユーザーの発話終了が明確なプッシュ・トゥ・トークのアプリで便利です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、パイプラインは「activity detection（アクティビティ検出）」と呼ばれる処理により、適切なタイミングで自動的にエージェントのワークフローを実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声書き起こしがあり、その結果だけを生成したい場合に使用します。話者が話し終えたタイミングの検出が不要なケース、たとえば事前録音された音声や、ユーザーが話し終えるタイミングが明確なプッシュ・トゥ・トークのアプリで便利です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングの検出が必要な場合に使用します。検出された音声チャンクを逐次プッシュでき、パイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングでエージェント ワークフローを自動的に実行します。 ## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは発生するイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングできるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます: 1. 音声チャンクを含む [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] -2. ターンの開始・終了などライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] +2. ターンの開始や終了などのライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 3. エラーイベントである [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み機能をサポートしていません。代わりに、検出された各ターンごとにワークフローの別個の実行がトリガーされます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを購読してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンのすべての音声がディスパッチされた後にトリガーされます。これらのイベントを利用して、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にミュート解除するといった制御が可能です。 \ No newline at end of file +Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視できます。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンのすべての音声がディスパッチされた後にトリガーされます。これらのイベントを利用して、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべてフラッシュした後にミュート解除するといった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index b9214d304..d855916ed 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK からオプションの音声関連依存関係をインストールします: +Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -主要な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです: +主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです。 -1. 音声をテキストに変換するために音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行して結果を生成します。 -3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 +1. 音声認識モデルを実行して、音声をテキストに変換します。 +2. 通常は エージェント によるワークフローであるあなたのコードを実行し、結果を生成します。 +3. 音声合成モデルを実行して、結果のテキストを音声に戻します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントをセットアップします。すでにこの SDK でエージェントを作成したことがあれば、馴染みのある手順のはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず エージェント をいくつか設定します。これは、この SDK で エージェント を作成したことがあれば馴染みがあるはずです。ここでは、複数の エージェント、ハンドオフ、そして 1 つのツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインをセットアップします。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインを設定します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -このサンプルを実行すると、エージェントがあなたに話しかけます。自分でエージェントに話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話しかけます。自分で エージェント に話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の code examples をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index b60134271..a0596aaef 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 +[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレースされます。 -基本的なトレーシング情報は上記のドキュメントをご覧いただけますが、さらに [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを設定できます。 +基本的なトレーシングの情報は上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを設定できます。 -トレーシングに関連する主なフィールドは次のとおりです: +主なトレーシング関連フィールド: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトでは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしのような、機微な可能性のあるデータをトレースに含めるかどうかを制御します。これは特に音声パイプラインに対する設定であり、ワークフロー内部で行われることには適用されません。 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプラインに特有の設定で、ワークフロー内部で行われることには適用されません。 - [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 音声データをトレースに含めるかどうかを制御します。 - [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースをリンクできるトレースの `group_id` です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるためのトレースの `group_id` です。 - [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file diff --git a/docs/mcp.md b/docs/mcp.md index eef61a047..4d120b484 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -1,187 +1,333 @@ # Model context protocol (MCP) -The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka MCP) is a way to provide tools and context to the LLM. From the MCP docs: +The [Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) standardises how applications expose tools and +context to language models. From the official documentation: -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI +> applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP +> provides a standardized way to connect AI models to different data sources and tools. -The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools and prompts to your Agents. +The Agents Python SDK understands multiple MCP transports. This lets you reuse existing MCP servers or build your own to expose +filesystem, HTTP, or connector backed tools to an agent. -## MCP servers +## Choosing an MCP integration -Currently, the MCP spec defines three kinds of servers, based on the transport mechanism they use: +Before wiring an MCP server into an agent decide where the tool calls should execute and which transports you can reach. The +matrix below summarises the options that the Python SDK supports. -1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally". -2. **HTTP over SSE** servers run remotely. You connect to them via a URL. -3. **Streamable HTTP** servers run remotely using the Streamable HTTP transport defined in the MCP spec. +| What you need | Recommended option | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| Let OpenAI's Responses API call a publicly reachable MCP server on the model's behalf| **Hosted MCP server tools** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| Connect to Streamable HTTP servers that you run locally or remotely | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Talk to servers that implement HTTP with Server-Sent Events | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| Launch a local process and communicate over stdin/stdout | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] classes to connect to these servers. +The sections below walk through each option, how to configure it, and when to prefer one transport over another. -For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem). +## 1. Hosted MCP server tools + +Hosted tools push the entire tool round-trip into OpenAI's infrastructure. Instead of your code listing and calling tools, the +[`HostedMCPTool`][agents.tool.HostedMCPTool] forwards a server label (and optional connector metadata) to the Responses API. The +model lists the remote server's tools and invokes them without an extra callback to your Python process. Hosted tools currently +work with OpenAI models that support the Responses API's hosted MCP integration. + +### Basic hosted MCP tool + +Create a hosted tool by adding a [`HostedMCPTool`][agents.tool.HostedMCPTool] to the agent's `tools` list. The `tool_config` +dict mirrors the JSON you would send to the REST API: ```python -from agents.run_context import RunContextWrapper +import asyncio + +from agents import Agent, HostedMCPTool, Runner + +async def main() -> None: + agent = Agent( + name="Assistant", + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "never", + } + ) + ], + ) -async with MCPServerStdio( - params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], - } -) as server: - # Note: In practice, you typically add the server to an Agent - # and let the framework handle tool listing automatically. - # Direct calls to list_tools() require run_context and agent parameters. - run_context = RunContextWrapper(context=None) - agent = Agent(name="test", instructions="test") - tools = await server.list_tools(run_context, agent) + result = await Runner.run(agent, "Which language is this repository written in?") + print(result.final_output) + +asyncio.run(main()) ``` -## Using MCP servers +The hosted server exposes its tools automatically; you do not add it to `mcp_servers`. -MCP servers can be added to Agents. The Agents SDK will call `list_tools()` on the MCP servers each time the Agent is run. This makes the LLM aware of the MCP server's tools. When the LLM calls a tool from an MCP server, the SDK calls `call_tool()` on that server. +### Streaming hosted MCP results + +Hosted tools support streaming results in exactly the same way as function tools. Pass `stream=True` to `Runner.run_streamed` to +consume incremental MCP output while the model is still working: + +```python +result = Runner.run_streamed(agent, "Summarise this repository's top languages") +async for event in result.stream_events(): + if event.type == "run_item_stream_event": + print(f"Received: {event.item}") +print(result.final_output) +``` + +### Optional approval flows + +If a server can perform sensitive operations you can require human or programmatic approval before each tool execution. Configure +`require_approval` in the `tool_config` with either a single policy (`"always"`, `"never"`) or a dict mapping tool names to +policies. To make the decision inside Python, provide an `on_approval_request` callback. ```python +from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest + +SAFE_TOOLS = {"read_project_metadata"} + +def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult: + if request.data.name in SAFE_TOOLS: + return {"approve": True} + return {"approve": False, "reason": "Escalate to a human reviewer"} -agent=Agent( +agent = Agent( name="Assistant", - instructions="Use the tools to achieve the task", - mcp_servers=[mcp_server_1, mcp_server_2] + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "always", + }, + on_approval_request=approve_tool, + ) + ], ) ``` -## Tool filtering +The callback can be synchronous or asynchronous and is invoked whenever the model needs approval data to keep running. -You can filter which tools are available to your Agent by configuring tool filters on MCP servers. The SDK supports both static and dynamic tool filtering. +### Connector-backed hosted servers -### Static tool filtering +Hosted MCP also supports OpenAI connectors. Instead of specifying a `server_url`, supply a `connector_id` and an access token. The +Responses API handles authentication and the hosted server exposes the connector's tools. + +```python +import os + +HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "google_calendar", + "connector_id": "connector_googlecalendar", + "authorization": os.environ["GOOGLE_CALENDAR_AUTHORIZATION"], + "require_approval": "never", + } +) +``` + +Fully working hosted tool samples—including streaming, approvals, and connectors—live in +[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp). + +## 2. Streamable HTTP MCP servers -For simple allow/block lists, you can use static filtering: +When you want to manage the network connection yourself, use +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]. Streamable HTTP servers are ideal when you control the +transport or want to run the server inside your own infrastructure while keeping latency low. ```python -from agents.mcp import create_static_tool_filter +import asyncio +import os + +from agents import Agent, Runner +from agents.mcp import MCPServerStreamableHttp +from agents.model_settings import ModelSettings + +async def main() -> None: + token = os.environ["MCP_SERVER_TOKEN"] + async with MCPServerStreamableHttp( + name="Streamable HTTP Python Server", + params={ + "url": "http://localhost:8000/mcp", + "headers": {"Authorization": f"Bearer {token}"}, + "timeout": 10, + }, + cache_tools_list=True, + max_retry_attempts=3, + ) as server: + agent = Agent( + name="Assistant", + instructions="Use the MCP tools to answer the questions.", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), + ) + + result = await Runner.run(agent, "Add 7 and 22.") + print(result.final_output) + +asyncio.run(main()) +``` + +The constructor accepts additional options: -# Only expose specific tools from this server -server = MCPServerStdio( +- `client_session_timeout_seconds` controls HTTP read timeouts. +- `use_structured_content` toggles whether `tool_result.structured_content` is preferred over textual output. +- `max_retry_attempts` and `retry_backoff_seconds_base` add automatic retries for `list_tools()` and `call_tool()`. +- `tool_filter` lets you expose only a subset of tools (see [Tool filtering](#tool-filtering)). + +## 3. HTTP with SSE MCP servers + +If the MCP server implements the HTTP with SSE transport, instantiate +[`MCPServerSse`][agents.mcp.server.MCPServerSse]. Apart from the transport, the API is identical to the Streamable HTTP server. + +```python +workspace_id = "demo-workspace" + +async with MCPServerSse( + name="SSE Python Server", params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "url": "http://localhost:8000/sse", + "headers": {"X-Workspace": workspace_id}, }, - tool_filter=create_static_tool_filter( - allowed_tool_names=["read_file", "write_file"] + cache_tools_list=True, +) as server: + agent = Agent( + name="Assistant", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), ) -) + result = await Runner.run(agent, "What's the weather in Tokyo?") + print(result.final_output) +``` -# Exclude specific tools from this server -server = MCPServerStdio( +## 4. stdio MCP servers + +For MCP servers that run as local subprocesses, use [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]. The SDK spawns the +process, keeps the pipes open, and closes them automatically when the context manager exits. This option is helpful for quick +proofs of concept or when the server only exposes a command line entry point. + +```python +from pathlib import Path + +current_dir = Path(__file__).parent +samples_dir = current_dir / "sample_files" + +async with MCPServerStdio( + name="Filesystem Server via npx", params={ - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], }, - tool_filter=create_static_tool_filter( - blocked_tool_names=["delete_file"] +) as server: + agent = Agent( + name="Assistant", + instructions="Use the files in the sample directory to answer questions.", + mcp_servers=[server], ) -) - + result = await Runner.run(agent, "List the files available to you.") + print(result.final_output) ``` -**When both `allowed_tool_names` and `blocked_tool_names` are configured, the processing order is:** -1. First apply `allowed_tool_names` (allowlist) - only keep the specified tools -2. Then apply `blocked_tool_names` (blocklist) - exclude specified tools from the remaining tools +## Tool filtering -For example, if you configure `allowed_tool_names=["read_file", "write_file", "delete_file"]` and `blocked_tool_names=["delete_file"]`, only `read_file` and `write_file` tools will be available. +Each MCP server supports tool filters so that you can expose only the functions that your agent needs. Filtering can happen at +construction time or dynamically per run. -### Dynamic tool filtering +### Static tool filtering -For more complex filtering logic, you can use dynamic filters with functions: +Use [`create_static_tool_filter`][agents.mcp.create_static_tool_filter] to configure simple allow/block lists: ```python -from agents.mcp import ToolFilterContext - -# Simple synchronous filter -def custom_filter(context: ToolFilterContext, tool) -> bool: - """Example of a custom tool filter.""" - # Filter logic based on tool name patterns - return tool.name.startswith("allowed_prefix") - -# Context-aware filter -def context_aware_filter(context: ToolFilterContext, tool) -> bool: - """Filter tools based on context information.""" - # Access agent information - agent_name = context.agent.name - - # Access server information - server_name = context.server_name - - # Implement your custom filtering logic here - return some_filtering_logic(agent_name, server_name, tool) - -# Asynchronous filter -async def async_filter(context: ToolFilterContext, tool) -> bool: - """Example of an asynchronous filter.""" - # Perform async operations if needed - result = await some_async_check(context, tool) - return result - -server = MCPServerStdio( +from pathlib import Path + +from agents.mcp import MCPServerStdio, create_static_tool_filter + +samples_dir = Path("/path/to/files") + +filesystem_server = MCPServerStdio( params={ "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], }, - tool_filter=custom_filter # or context_aware_filter or async_filter + tool_filter=create_static_tool_filter(allowed_tool_names=["read_file", "write_file"]), ) ``` -The `ToolFilterContext` provides access to: -- `run_context`: The current run context -- `agent`: The agent requesting the tools -- `server_name`: The name of the MCP server +When both `allowed_tool_names` and `blocked_tool_names` are supplied the SDK applies the allow-list first and then removes any +blocked tools from the remaining set. -## Prompts +### Dynamic tool filtering + +For more elaborate logic pass a callable that receives a [`ToolFilterContext`][agents.mcp.ToolFilterContext]. The callable can be +synchronous or asynchronous and returns `True` when the tool should be exposed. -MCP servers can also provide prompts that can be used to dynamically generate agent instructions. This allows you to create reusable instruction templates that can be customized with parameters. +```python +from pathlib import Path -### Using prompts +from agents.mcp import MCPServerStdio, ToolFilterContext -MCP servers that support prompts provide two key methods: +samples_dir = Path("/path/to/files") -- `list_prompts()`: Lists all available prompts on the server -- `get_prompt(name, arguments)`: Gets a specific prompt with optional parameters +async def context_aware_filter(context: ToolFilterContext, tool) -> bool: + if context.agent.name == "Code Reviewer" and tool.name.startswith("danger_"): + return False + return True -```python -# List available prompts -prompts_result = await server.list_prompts() -for prompt in prompts_result.prompts: - print(f"Prompt: {prompt.name} - {prompt.description}") +async with MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], + }, + tool_filter=context_aware_filter, +) as server: + ... +``` -# Get a specific prompt with parameters +The filter context exposes the active `run_context`, the `agent` requesting the tools, and the `server_name`. + +## Prompts + +MCP servers can also provide prompts that dynamically generate agent instructions. Servers that support prompts expose two +methods: + +- `list_prompts()` enumerates the available prompt templates. +- `get_prompt(name, arguments)` fetches a concrete prompt, optionally with parameters. + +```python prompt_result = await server.get_prompt( "generate_code_review_instructions", - {"focus": "security vulnerabilities", "language": "python"} + {"focus": "security vulnerabilities", "language": "python"}, ) instructions = prompt_result.messages[0].content.text -# Use the prompt-generated instructions with an Agent agent = Agent( name="Code Reviewer", - instructions=instructions, # Instructions from MCP prompt - mcp_servers=[server] + instructions=instructions, + mcp_servers=[server], ) ``` ## Caching -Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]. You should only do this if you're certain the tool list will not change. - -If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers. - -## End-to-end examples - -View complete working examples at [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp). +Every agent run calls `list_tools()` on each MCP server. Remote servers can introduce noticeable latency, so all of the MCP +server classes expose a `cache_tools_list` option. Set it to `True` only if you are confident that the tool definitions do not +change frequently. To force a fresh list later, call `invalidate_tools_cache()` on the server instance. ## Tracing -[Tracing](./tracing.md) automatically captures MCP operations, including: +[Tracing](./tracing.md) automatically captures MCP activity, including: -1. Calls to the MCP server to list tools -2. MCP-related info on function calls +1. Calls to the MCP server to list tools. +2. MCP-related information on tool calls. ![MCP Tracing Screenshot](./assets/images/mcp-tracing.jpg) + +## Further reading + +- [Model Context Protocol](https://modelcontextprotocol.io/) – the specification and design guides. +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – runnable stdio, SSE, and Streamable HTTP samples. +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – complete hosted MCP demonstrations including approvals and connectors. diff --git a/docs/running_agents.md b/docs/running_agents.md index b86888784..e51b109cf 100644 --- a/docs/running_agents.md +++ b/docs/running_agents.md @@ -100,6 +100,7 @@ async def main(): # Create session instance session = SQLiteSession("conversation_123") + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session) diff --git a/examples/hosted_mcp/connectors.py b/examples/hosted_mcp/connectors.py index 56138cea6..e86cfd8e3 100644 --- a/examples/hosted_mcp/connectors.py +++ b/examples/hosted_mcp/connectors.py @@ -13,7 +13,7 @@ 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 acccess token starting with "ya29." + # 3. Grab the access token starting with "ya29." authorization = os.environ["GOOGLE_CALENDAR_AUTHORIZATION"] agent = Agent( name="Assistant", diff --git a/src/agents/_debug.py b/src/agents/_debug.py index 4da91be48..963c296b8 100644 --- a/src/agents/_debug.py +++ b/src/agents/_debug.py @@ -1,17 +1,28 @@ import os -def _debug_flag_enabled(flag: str) -> bool: +def _debug_flag_enabled(flag: str, default: bool = False) -> bool: flag_value = os.getenv(flag) - return flag_value is not None and (flag_value == "1" or flag_value.lower() == "true") + if flag_value is None: + return default + else: + return flag_value == "1" or flag_value.lower() == "true" -DONT_LOG_MODEL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_MODEL_DATA") +def _load_dont_log_model_data() -> bool: + return _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_MODEL_DATA", default=True) + + +def _load_dont_log_tool_data() -> bool: + return _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_TOOL_DATA", default=True) + + +DONT_LOG_MODEL_DATA = _load_dont_log_model_data() """By default we don't log LLM inputs/outputs, to prevent exposing sensitive information. Set this flag to enable logging them. """ -DONT_LOG_TOOL_DATA = _debug_flag_enabled("OPENAI_AGENTS_DONT_LOG_TOOL_DATA") +DONT_LOG_TOOL_DATA = _load_dont_log_tool_data() """By default we don't log tool call inputs/outputs, to prevent exposing sensitive information. Set this flag to enable logging them. """ diff --git a/src/agents/_run_impl.py b/src/agents/_run_impl.py index 56784004c..a2d872bf1 100644 --- a/src/agents/_run_impl.py +++ b/src/agents/_run_impl.py @@ -330,43 +330,40 @@ async def execute_tools_and_side_effects( ItemHelpers.extract_last_text(message_items[-1].raw_item) if message_items else None ) - # There are two possibilities that lead to a final output: - # 1. Structured output schema => always leads to a final output - # 2. Plain text output schema => only leads to a final output if there are no tool calls - if output_schema and not output_schema.is_plain_text() and potential_final_output_text: - final_output = output_schema.validate_json(potential_final_output_text) - return await cls.execute_final_output( - agent=agent, - original_input=original_input, - new_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - final_output=final_output, - hooks=hooks, - context_wrapper=context_wrapper, - ) - elif ( - not output_schema or output_schema.is_plain_text() - ) and not processed_response.has_tools_or_approvals_to_run(): - return await cls.execute_final_output( - agent=agent, - original_input=original_input, - new_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - final_output=potential_final_output_text or "", - hooks=hooks, - context_wrapper=context_wrapper, - ) - else: - # If there's no final output, we can just run again - return SingleStepResult( - original_input=original_input, - model_response=new_response, - pre_step_items=pre_step_items, - new_step_items=new_step_items, - next_step=NextStepRunAgain(), - ) + # Generate final output only when there are no pending tool calls or approval requests. + if not processed_response.has_tools_or_approvals_to_run(): + if output_schema and not output_schema.is_plain_text() and potential_final_output_text: + final_output = output_schema.validate_json(potential_final_output_text) + return await cls.execute_final_output( + agent=agent, + original_input=original_input, + new_response=new_response, + pre_step_items=pre_step_items, + new_step_items=new_step_items, + final_output=final_output, + hooks=hooks, + context_wrapper=context_wrapper, + ) + elif not output_schema or output_schema.is_plain_text(): + return await cls.execute_final_output( + agent=agent, + original_input=original_input, + new_response=new_response, + pre_step_items=pre_step_items, + new_step_items=new_step_items, + final_output=potential_final_output_text or "", + hooks=hooks, + context_wrapper=context_wrapper, + ) + + # If there's no final output, we can just run again + return SingleStepResult( + original_input=original_input, + model_response=new_response, + pre_step_items=pre_step_items, + new_step_items=new_step_items, + next_step=NextStepRunAgain(), + ) @classmethod def maybe_reset_tool_choice( diff --git a/src/agents/memory/openai_conversations_session.py b/src/agents/memory/openai_conversations_session.py index 9bf5ccdac..ce0621358 100644 --- a/src/agents/memory/openai_conversations_session.py +++ b/src/agents/memory/openai_conversations_session.py @@ -19,9 +19,6 @@ async def start_openai_conversations_session(openai_client: AsyncOpenAI | None = return response.id -_EMPTY_SESSION_ID = "" - - class OpenAIConversationsSession(SessionABC): def __init__( self, diff --git a/src/agents/realtime/session.py b/src/agents/realtime/session.py index c309a2655..32c418fac 100644 --- a/src/agents/realtime/session.py +++ b/src/agents/realtime/session.py @@ -95,6 +95,12 @@ def __init__( self._history: list[RealtimeItem] = [] self._model_config = model_config or {} self._run_config = run_config or {} + initial_model_settings = self._model_config.get("initial_model_settings") + run_config_settings = self._run_config.get("model_settings") + self._base_model_settings: RealtimeSessionModelSettings = { + **(run_config_settings or {}), + **(initial_model_settings or {}), + } self._event_queue: asyncio.Queue[RealtimeSessionEvent] = asyncio.Queue() self._closed = False self._stored_exception: Exception | None = None @@ -619,12 +625,8 @@ async def _get_updated_model_settings_from_agent( starting_settings: RealtimeSessionModelSettings | None, agent: RealtimeAgent, ) -> RealtimeSessionModelSettings: - # Start with run config model settings as base - run_config_settings = self._run_config.get("model_settings", {}) - updated_settings: RealtimeSessionModelSettings = run_config_settings.copy() - # Apply starting settings (from model config) next - if starting_settings: - updated_settings.update(starting_settings) + # Start with the merged base settings from run and model configuration. + updated_settings = self._base_model_settings.copy() instructions, tools, handoffs = await asyncio.gather( agent.get_system_prompt(self._context_wrapper), @@ -635,6 +637,10 @@ async def _get_updated_model_settings_from_agent( updated_settings["tools"] = tools or [] updated_settings["handoffs"] = handoffs or [] + # Apply starting settings (from model config) next + if starting_settings: + updated_settings.update(starting_settings) + disable_tracing = self._run_config.get("tracing_disabled", False) if disable_tracing: updated_settings["tracing"] = None diff --git a/src/agents/run.py b/src/agents/run.py index 4575edb3f..a77900dff 100644 --- a/src/agents/run.py +++ b/src/agents/run.py @@ -411,7 +411,8 @@ async def run( if run_config is None: run_config = RunConfig() - # Prepare input with session if enabled + # Keep original user input separate from session-prepared input + original_user_input = input prepared_input = await self._prepare_input_with_session(input, session) tool_use_tracker = AgentToolUseTracker() @@ -438,6 +439,9 @@ async def run( current_agent = starting_agent should_run_agent_start_hooks = True + # save only the new user input to the session, not the combined history + await self._save_result_to_session(session, original_user_input, []) + try: while True: all_tools = await AgentRunner._get_all_tools(current_agent, context_wrapper) @@ -537,9 +541,7 @@ async def run( output_guardrail_results=output_guardrail_results, context_wrapper=context_wrapper, ) - - # Save the conversation to session if enabled - await self._save_result_to_session(session, input, result) + await self._save_result_to_session(session, [], turn_result.new_step_items) return result elif isinstance(turn_result.next_step, NextStepHandoff): @@ -548,7 +550,7 @@ async def run( current_span = None should_run_agent_start_hooks = True elif isinstance(turn_result.next_step, NextStepRunAgain): - pass + await self._save_result_to_session(session, [], turn_result.new_step_items) else: raise AgentsException( f"Unknown next step type: {type(turn_result.next_step)}" @@ -784,6 +786,8 @@ async def _start_streaming( # Update the streamed result with the prepared input streamed_result.input = prepared_input + await AgentRunner._save_result_to_session(session, starting_input, []) + while True: if streamed_result.is_complete: break @@ -887,24 +891,15 @@ async def _start_streaming( streamed_result.is_complete = True # Save the conversation to session if enabled - # Create a temporary RunResult for session saving - temp_result = RunResult( - input=streamed_result.input, - new_items=streamed_result.new_items, - raw_responses=streamed_result.raw_responses, - final_output=streamed_result.final_output, - _last_agent=current_agent, - input_guardrail_results=streamed_result.input_guardrail_results, - output_guardrail_results=streamed_result.output_guardrail_results, - context_wrapper=context_wrapper, - ) await AgentRunner._save_result_to_session( - session, starting_input, temp_result + session, [], turn_result.new_step_items ) streamed_result._event_queue.put_nowait(QueueCompleteSentinel()) elif isinstance(turn_result.next_step, NextStepRunAgain): - pass + await AgentRunner._save_result_to_session( + session, [], turn_result.new_step_items + ) except AgentsException as exc: streamed_result.is_complete = True streamed_result._event_queue.put_nowait(QueueCompleteSentinel()) @@ -1510,7 +1505,7 @@ async def _save_result_to_session( cls, session: Session | None, original_input: str | list[TResponseInputItem], - result: RunResult, + new_items: list[RunItem], ) -> None: """Save the conversation turn to session.""" if session is None: @@ -1520,7 +1515,7 @@ async def _save_result_to_session( input_list = ItemHelpers.input_to_new_input_list(original_input) # Convert new items to input format - new_items_as_input = [item.to_input_item() for item in result.new_items] + new_items_as_input = [item.to_input_item() for item in new_items] # Save all items from this turn items_to_save = input_list + new_items_as_input diff --git a/src/agents/tool.py b/src/agents/tool.py index 04534bd04..7ba9435ed 100644 --- a/src/agents/tool.py +++ b/src/agents/tool.py @@ -142,7 +142,7 @@ class WebSearchTool: @property def name(self): - return "web_search_preview" + return "web_search" @dataclass diff --git a/src/agents/voice/input.py b/src/agents/voice/input.py index 8613d27ac..8cbc8b735 100644 --- a/src/agents/voice/input.py +++ b/src/agents/voice/input.py @@ -77,12 +77,13 @@ class StreamedAudioInput: """ def __init__(self): - self.queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32]] = asyncio.Queue() + self.queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32] | None] = asyncio.Queue() - async def add_audio(self, audio: npt.NDArray[np.int16 | np.float32]): + async def add_audio(self, audio: npt.NDArray[np.int16 | np.float32] | None): """Adds more audio data to the stream. Args: - audio: The audio data to add. Must be a numpy array of int16 or float32. + audio: The audio data to add. Must be a numpy array of int16 or float32 or None. + If None passed, it indicates the end of the stream. """ await self.queue.put(audio) diff --git a/src/agents/voice/models/openai_stt.py b/src/agents/voice/models/openai_stt.py index b1f1b6da7..19e91d9be 100644 --- a/src/agents/voice/models/openai_stt.py +++ b/src/agents/voice/models/openai_stt.py @@ -88,7 +88,7 @@ def __init__( self._trace_include_sensitive_data = trace_include_sensitive_data self._trace_include_sensitive_audio_data = trace_include_sensitive_audio_data - self._input_queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32]] = input.queue + self._input_queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32] | None] = input.queue self._output_queue: asyncio.Queue[str | ErrorSentinel | SessionCompleteSentinel] = ( asyncio.Queue() ) @@ -226,7 +226,10 @@ async def _handle_events(self) -> None: break event_type = event.get("type", "unknown") - if event_type == "input_audio_transcription_completed": + if event_type in [ + "input_audio_transcription_completed", # legacy + "conversation.item.input_audio_transcription.completed", + ]: transcript = cast(str, event.get("transcript", "")) if len(transcript) > 0: self._end_turn(transcript) @@ -242,7 +245,7 @@ async def _handle_events(self) -> None: await self._output_queue.put(SessionCompleteSentinel()) async def _stream_audio( - self, audio_queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32]] + self, audio_queue: asyncio.Queue[npt.NDArray[np.int16 | np.float32] | None] ) -> None: assert self._websocket is not None, "Websocket not initialized" self._start_turn() diff --git a/tests/realtime/test_session.py b/tests/realtime/test_session.py index cd562c522..66db03ef1 100644 --- a/tests/realtime/test_session.py +++ b/tests/realtime/test_session.py @@ -1606,6 +1606,47 @@ async def mock_get_handoffs(cls, agent, context_wrapper): assert model_settings["tool_choice"] == "required" assert model_settings["output_audio_format"] == "g711_ulaw" + @pytest.mark.asyncio + async def test_model_settings_preserve_initial_settings_on_updates(self): + """Initial model settings should persist when we recompute settings for updates.""" + + agent = RealtimeAgent(name="test_agent", instructions="test") + agent.handoffs = [] + agent.get_system_prompt = AsyncMock(return_value="test_prompt") # type: ignore + agent.get_all_tools = AsyncMock(return_value=[]) # type: ignore + + mock_model = Mock(spec=RealtimeModel) + + initial_settings: RealtimeSessionModelSettings = { + "voice": "initial_voice", + "output_audio_format": "pcm16", + } + + session = RealtimeSession( + model=mock_model, + agent=agent, + context=None, + model_config={"initial_model_settings": initial_settings}, + run_config={}, + ) + + async def mock_get_handoffs(cls, agent, context_wrapper): + return [] + + with pytest.MonkeyPatch().context() as m: + m.setattr( + "agents.realtime.session.RealtimeSession._get_handoffs", + mock_get_handoffs, + ) + + model_settings = await session._get_updated_model_settings_from_agent( + starting_settings=None, + agent=agent, + ) + + assert model_settings["voice"] == "initial_voice" + assert model_settings["output_audio_format"] == "pcm16" + class TestUpdateAgentFunctionality: """Tests for update agent functionality in RealtimeSession""" diff --git a/tests/test_agent_runner.py b/tests/test_agent_runner.py index c8ae5b5f2..661afd6ef 100644 --- a/tests/test_agent_runner.py +++ b/tests/test_agent_runner.py @@ -1,7 +1,10 @@ from __future__ import annotations import json +import tempfile +from pathlib import Path from typing import Any +from unittest.mock import patch import pytest from typing_extensions import TypedDict @@ -20,6 +23,7 @@ RunConfig, RunContextWrapper, Runner, + SQLiteSession, UserError, handoff, ) @@ -192,11 +196,13 @@ async def test_structured_output(): [get_function_tool_call("foo", json.dumps({"bar": "baz"}))], # Second turn: a message and a handoff [get_text_message("a_message"), get_handoff_tool_call(agent_1)], - # Third turn: tool call and structured output + # Third turn: tool call with preamble message [ + get_text_message(json.dumps(Foo(bar="preamble"))), get_function_tool_call("bar", json.dumps({"bar": "baz"})), - get_final_output_message(json.dumps(Foo(bar="baz"))), ], + # Fourth turn: structured output + [get_final_output_message(json.dumps(Foo(bar="baz")))], ] ) @@ -209,10 +215,10 @@ async def test_structured_output(): ) assert result.final_output == Foo(bar="baz") - assert len(result.raw_responses) == 3, "should have three model responses" - assert len(result.to_input_list()) == 10, ( + assert len(result.raw_responses) == 4, "should have four model responses" + assert len(result.to_input_list()) == 11, ( "should have input: 2 orig inputs, function call, function call result, message, handoff, " - "handoff output, tool call, tool call result, final output message" + "handoff output, preamble message, tool call, tool call result, final output" ) assert result.last_agent == agent_1, "should have handed off to agent_1" @@ -780,3 +786,96 @@ async def add_tool() -> str: assert executed["called"] is True assert result.final_output == "done" + + +@pytest.mark.asyncio +async def test_session_add_items_called_multiple_times_for_multi_turn_completion(): + """Test that SQLiteSession.add_items is called multiple times + during a multi-turn agent completion. + + """ + with tempfile.TemporaryDirectory() as temp_dir: + db_path = Path(temp_dir) / "test_agent_runner_session_multi_turn_calls.db" + session_id = "runner_session_multi_turn_calls" + session = SQLiteSession(session_id, db_path) + + # Define a tool that will be called by the orchestrator agent + @function_tool + async def echo_tool(text: str) -> str: + return f"Echo: {text}" + + # Orchestrator agent that calls the tool multiple times in one completion + orchestrator_agent = Agent( + name="orchestrator_agent", + instructions=( + "Call echo_tool twice with inputs of 'foo' and 'bar', then return a summary." + ), + tools=[echo_tool], + ) + + # Patch the model to simulate two tool calls and a final message + model = FakeModel() + orchestrator_agent.model = model + model.add_multiple_turn_outputs( + [ + # First turn: tool call + [get_function_tool_call("echo_tool", json.dumps({"text": "foo"}), call_id="1")], + # Second turn: tool call + [get_function_tool_call("echo_tool", json.dumps({"text": "bar"}), call_id="2")], + # Third turn: final output + [get_final_output_message("Summary: Echoed foo and bar")], + ] + ) + + # Patch add_items to count calls + with patch.object(SQLiteSession, "add_items", wraps=session.add_items) as mock_add_items: + result = await Runner.run(orchestrator_agent, input="foo and bar", session=session) + + expected_items = [ + {"content": "foo and bar", "role": "user"}, + { + "arguments": '{"text": "foo"}', + "call_id": "1", + "name": "echo_tool", + "type": "function_call", + "id": "1", + }, + {"call_id": "1", "output": "Echo: foo", "type": "function_call_output"}, + { + "arguments": '{"text": "bar"}', + "call_id": "2", + "name": "echo_tool", + "type": "function_call", + "id": "1", + }, + {"call_id": "2", "output": "Echo: bar", "type": "function_call_output"}, + { + "id": "1", + "content": [ + { + "annotations": [], + "text": "Summary: Echoed foo and bar", + "type": "output_text", + } + ], + "role": "assistant", + "status": "completed", + "type": "message", + }, + ] + + expected_calls = [ + # First call is the initial input + (([expected_items[0]],),), + # Second call is the first tool call and its result + (([expected_items[1], expected_items[2]],),), + # Third call is the second tool call and its result + (([expected_items[3], expected_items[4]],),), + # Fourth call is the final output + (([expected_items[5]],),), + ] + assert mock_add_items.call_args_list == expected_calls + assert result.final_output == "Summary: Echoed foo and bar" + assert (await session.get_items()) == expected_items + + session.close() diff --git a/tests/test_agent_runner_streamed.py b/tests/test_agent_runner_streamed.py index d4afbd2e0..ff807ca96 100644 --- a/tests/test_agent_runner_streamed.py +++ b/tests/test_agent_runner_streamed.py @@ -207,11 +207,13 @@ async def test_structured_output(): [get_function_tool_call("foo", json.dumps({"bar": "baz"}))], # Second turn: a message and a handoff [get_text_message("a_message"), get_handoff_tool_call(agent_1)], - # Third turn: tool call and structured output + # Third turn: tool call with preamble message [ + get_text_message(json.dumps(Foo(bar="preamble"))), get_function_tool_call("bar", json.dumps({"bar": "baz"})), - get_final_output_message(json.dumps(Foo(bar="baz"))), ], + # Fourth turn: structured output + [get_final_output_message(json.dumps(Foo(bar="baz")))], ] ) @@ -226,10 +228,10 @@ async def test_structured_output(): pass assert result.final_output == Foo(bar="baz") - assert len(result.raw_responses) == 3, "should have three model responses" - assert len(result.to_input_list()) == 10, ( + assert len(result.raw_responses) == 4, "should have four model responses" + assert len(result.to_input_list()) == 11, ( "should have input: 2 orig inputs, function call, function call result, message, handoff, " - "handoff output, tool call, tool call result, final output" + "handoff output, preamble message, tool call, tool call result, final output" ) assert result.last_agent == agent_1, "should have handed off to agent_1" @@ -624,11 +626,10 @@ async def test_streaming_events(): [get_function_tool_call("foo", json.dumps({"bar": "baz"}))], # Second turn: a message and a handoff [get_text_message("a_message"), get_handoff_tool_call(agent_1)], - # Third turn: tool call and structured output - [ - get_function_tool_call("bar", json.dumps({"bar": "baz"})), - get_final_output_message(json.dumps(Foo(bar="baz"))), - ], + # Third turn: tool call + [get_function_tool_call("bar", json.dumps({"bar": "baz"}))], + # Fourth turn: structured output + [get_final_output_message(json.dumps(Foo(bar="baz")))], ] ) @@ -652,7 +653,7 @@ async def test_streaming_events(): agent_data.append(event) assert result.final_output == Foo(bar="baz") - assert len(result.raw_responses) == 3, "should have three model responses" + assert len(result.raw_responses) == 4, "should have four model responses" assert len(result.to_input_list()) == 10, ( "should have input: 2 orig inputs, function call, function call result, message, handoff, " "handoff output, tool call, tool call result, final output" diff --git a/tests/test_debug.py b/tests/test_debug.py new file mode 100644 index 000000000..f9e0ea21e --- /dev/null +++ b/tests/test_debug.py @@ -0,0 +1,54 @@ +import os +from unittest.mock import patch + +from agents._debug import _load_dont_log_model_data, _load_dont_log_tool_data + + +@patch.dict(os.environ, {}) +def test_dont_log_model_data(): + assert _load_dont_log_model_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_MODEL_DATA": "0"}) +def test_dont_log_model_data_0(): + assert _load_dont_log_model_data() is False + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_MODEL_DATA": "1"}) +def test_dont_log_model_data_1(): + assert _load_dont_log_model_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_MODEL_DATA": "true"}) +def test_dont_log_model_data_true(): + assert _load_dont_log_model_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_MODEL_DATA": "false"}) +def test_dont_log_model_data_false(): + assert _load_dont_log_model_data() is False + + +@patch.dict(os.environ, {}) +def test_dont_log_tool_data(): + assert _load_dont_log_tool_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_TOOL_DATA": "0"}) +def test_dont_log_tool_data_0(): + assert _load_dont_log_tool_data() is False + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_TOOL_DATA": "1"}) +def test_dont_log_tool_data_1(): + assert _load_dont_log_tool_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_TOOL_DATA": "true"}) +def test_dont_log_tool_data_true(): + assert _load_dont_log_tool_data() is True + + +@patch.dict(os.environ, {"OPENAI_AGENTS_DONT_LOG_TOOL_DATA": "false"}) +def test_dont_log_tool_data_false(): + assert _load_dont_log_tool_data() is False diff --git a/tests/voice/test_input.py b/tests/voice/test_input.py index d41d870d7..fbef84c1b 100644 --- a/tests/voice/test_input.py +++ b/tests/voice/test_input.py @@ -121,7 +121,14 @@ async def test_streamed_audio_input(self): # Verify the queue contents assert streamed_input.queue.qsize() == 2 # Test non-blocking get - assert np.array_equal(streamed_input.queue.get_nowait(), audio1) + retrieved_audio1 = streamed_input.queue.get_nowait() + # Satisfy type checker + assert retrieved_audio1 is not None + assert np.array_equal(retrieved_audio1, audio1) + # Test blocking get - assert np.array_equal(await streamed_input.queue.get(), audio2) + retrieved_audio2 = await streamed_input.queue.get() + # Satisfy type checker + assert retrieved_audio2 is not None + assert np.array_equal(retrieved_audio2, audio2) assert streamed_input.queue.empty() diff --git a/tests/voice/test_openai_stt.py b/tests/voice/test_openai_stt.py index ecc41f2e2..f1ec04fdc 100644 --- a/tests/voice/test_openai_stt.py +++ b/tests/voice/test_openai_stt.py @@ -184,22 +184,35 @@ async def test_stream_audio_sends_correct_json(): @pytest.mark.asyncio -async def test_transcription_event_puts_output_in_queue(): +@pytest.mark.parametrize( + "created,updated,completed", + [ + ( + {"type": "transcription_session.created"}, + {"type": "transcription_session.updated"}, + {"type": "input_audio_transcription_completed", "transcript": "Hello world!"}, + ), + ( + {"type": "session.created"}, + {"type": "session.updated"}, + { + "type": "conversation.item.input_audio_transcription.completed", + "transcript": "Hello world!", + }, + ), + ], +) +async def test_transcription_event_puts_output_in_queue(created, updated, completed): """ - Test that a 'input_audio_transcription_completed' event + Test that a 'input_audio_transcription_completed' event and + 'conversation.item.input_audio_transcription.completed' yields a transcript from transcribe_turns(). """ mock_ws = create_mock_websocket( [ - json.dumps({"type": "transcription_session.created"}), - json.dumps({"type": "transcription_session.updated"}), - # Once configured, we mock a completed transcription event: - json.dumps( - { - "type": "input_audio_transcription_completed", - "transcript": "Hello world!", - } - ), + json.dumps(created), + json.dumps(updated), + json.dumps(completed), ] )