diff --git a/Makefile b/Makefile index 93bc25332..470d97c14 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ lint: .PHONY: mypy mypy: - uv run mypy . + uv run mypy . --exclude site .PHONY: tests tests: diff --git a/docs/ja/agents.md b/docs/ja/agents.md index cf5ac5d87..871223d9f 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントは、アプリにおける中核的な構成要素です。エージェントは、instructions と tools で構成された大規模言語モデル ( LLM ) です。 +エージェントはアプリの中核となる基本コンポーネントです。エージェントは instructions とツールで構成された大規模言語モデル（ LLM ）です。 ## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです: +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer message または system prompt とも呼ばれます。 -- `model`: 使用する LLM と、temperature、top_p などのモデル調整パラメーターを設定するオプションの `model_settings`。 -- `tools`: エージェントがタスクを達成するために使用できるツール。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: developer メッセージまたは システムプロンプト とも呼ばれます。 +- `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,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するように指示されます。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、関連がある場合にエージェントがそれらに委譲できます。これは、単一のタスクに特化して優れた、モジュール式の専門エージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、関連する場合にエージェントがそれらへ委譲できます。これは、単一のタスクに特化して優れた結果を出す、モジュール型の専門エージェントをオーケストレーションできる強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -98,7 +98,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を提供できます。しかし、関数を通じて動的な instructions を提供することも可能です。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が受け付けられます。 +多くの場合、エージェント作成時に instructions を与えられますが、関数を介して動的に instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用可能です。 ```python def dynamic_instructions( @@ -113,17 +113,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクルイベント（フック） -場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりしたい場合です。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観察したい場合があります。たとえば、イベントを記録したり、特定のイベント発生時にデータを事前取得したりします。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック/検証を行い、出力が生成された後にはエージェントの出力に対するチェック/検証を行えます。たとえば、ユーザーの入力やエージェントの出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 +ガードレールにより、エージェントの実行と並行して ユーザー 入力に対するチェックや検証を、またエージェントの出力が生成された後に出力に対するチェックや検証を実行できます。たとえば、 ユーザー の入力とエージェントの出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 ## エージェントのクローン/コピー -エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを指定しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです: +ツールのリストを指定しても、LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定するとツール使用を強制できます。有効な値は次のとおりです。 1. `auto`: ツールを使用するかどうかを LLM に任せます。 -2. `required`: LLM にツールの使用を要求します (ただし、どのツールを使うかは賢く選べます)。 -3. `none`: LLM にツールを使用しないことを要求します。 -4. 特定の文字列 (例: `my_tool`) を設定: LLM にその特定のツールの使用を要求します。 +2. `required`: LLM にツールの使用を必須にします（ただし、どのツールを使うかは賢く判断します）。 +3. `none`: LLM にツールを使用しないことを必須にします。 +4. 文字列を指定（例: `my_tool`）: その特定のツールを使用することを LLM に必須にします。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -163,10 +163,10 @@ agent = Agent( ) ``` -## ツール使用時の挙動 +## ツール使用の動作 -`Agent` の設定にある `tool_use_behavior` パラメーターは、ツールの出力の扱い方を制御します: -- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 +`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 +- `"run_llm_again"`: デフォルト。ツールを実行し、LLM が結果を処理して最終応答を生成します。 - `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしで最終応答として使用します。 ```python @@ -185,7 +185,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼ばれた場合に停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool from agents.agent import StopAtTools @@ -207,7 +207,7 @@ agent = Agent( tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを判断するカスタム関数。 +- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -245,4 +245,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、`tool_choice` により LLM がさらにツール呼び出しを生成し続けるために発生します。 \ 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 f9a334b79..ed7a81611 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 は環境変数または上で設定したデフォルトキーから API キーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +あるいは、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーから API キーを用いて `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 を使用します。 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って、Chat Completions 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 には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送信され、それ以外のログは抑制されることを意味します。 +SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これにより警告とエラーは `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 logging guide](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 a0c7a0337..a2372c00c 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` からアクセスできます。 - **最重要** な注意点: 特定のエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどは、同じコンテキストの _型_ を使用する必要があります。 + **最重要** な点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは、同じコンテキストの型を使用する必要があります。 -コンテキストは次のような用途に使えます。 +コンテキストは次のような用途に使えます: -- 実行のためのコンテキストデータ（例: ユーザー名/uid や、ユーザー に関するその他の情報） +- 実行のためのコンテキストデータ（例: ユーザー名 / uid など、ユーザーに関するその他の情報） - 依存関係（例: ロガーオブジェクト、データフェッチャーなど） - ヘルパー関数 -!!! danger "注記" +!!! danger "Note" - コンテキストオブジェクトは LLM には送信されません。これは純粋にローカルのオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルなオブジェクトであり、読み取り・書き込み・メソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これがコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから読み取ります。 -3. 型チェッカーがエラーを検出できるよう、エージェントにジェネリクス `UserInfo` を付けています（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +3. 型チェッカーがエラーを検出できるように、エージェントにジェネリクス `UserInfo` を付与しています（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 4. コンテキストは `run` 関数に渡されます。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM コンテキスト +## エージェント / LLM のコンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴に含まれるものだけです。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できる形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴のもの **のみ** です。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できるようにする必要があります。方法はいくつかあります。 -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でも構いません。これは常に有用な情報（例: ユーザー の名前や現在の日付）に一般的な手法です。 -2. `Runner.run` 関数を呼び出すときに `input` に追加します。これは `instructions` の手法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位に配置されるメッセージにできます。 -3. 関数ツール を通じて公開します。これは _オンデマンド_ のコンテキストに有用です。LLM が必要に応じてデータを取得するタイミングを判断し、ツールを呼び出してそのデータを取得できます。 -4. リトリーバル や Web 検索 を使用します。これらは、ファイルやデータベース（リトリーバル）またはウェブ（Web 検索）から関連データを取得できる特別なツールです。これは、応答を関連するコンテキストデータで「グラウンディング」するのに有用です。 \ 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. ファイル検索 または Web 検索 を使用します。これらは、ファイルやデータベース（ファイル検索）または Web（Web 検索）から関連データを取得できる特別なツールです。これは、応答を関連するコンテキストデータに「グラウンディング」するのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index edda2d579..f50e5f3e3 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,44 +4,45 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) のコード例セクションで、さまざまな サンプル実装 をご覧ください。これらのコード例は、異なるパターンや機能を示す複数の カテゴリー に整理されています。 +[リポジトリ](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 の基礎的な機能を紹介します - 動的な システムプロンプト - - ストリーミング出力 - - ライフサイクルイベント + - ストリーミング 出力 + - ライフサイクル イベント - **[ツールのコード例](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 モデル を使う方法を紹介します。 + 非 OpenAI モデルを SDK で利用する方法を紹介します。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェント の ハンドオフ の実用的な例を確認できます。 + エージェント のハンドオフの実用的なコード例をご覧ください。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP で エージェント を構築する方法を学べます。 + 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**: 航空会社向けのカスタマーサービス システムの例。 - - **research_bot**: シンプルな ディープリサーチ のクローン。 + - **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 a4e4bd000..b79317a4e 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと並行して実行され、 ユーザー 入力のチェックや検証を可能にします。たとえば、非常に賢い（つまり遅く/高価な）モデルでカスタマーリクエストを支援するエージェントがあるとします。悪意のある ユーザー がモデルに数学の宿題を手伝わせるよう求めるのは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意のある使用を検出すると、即座にエラーを送出し、高価なモデルの実行を停止して時間やコストを節約します。 +ガードレールは、あなたのエージェントと _並行して_ 実行され、 ユーザー 入力のチェックや検証を行います。たとえば、非常に賢い（したがって遅く/高価な）モデルを使って顧客の問い合わせを支援するエージェントがあるとします。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるよう依頼することは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意のある利用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を停止して時間とコストを節約できます。 ガードレールには 2 つの種類があります: 1. 入力ガードレールは最初の ユーザー 入力で実行されます -2. 出力ガードレールは最終的なエージェント出力で実行されます +2. 出力ガードレールは最終的なエージェントの出力で実行されます ## 入力ガードレール -入力ガードレールは 3 つの手順で実行されます: +入力ガードレールは 3 ステップで実行されます: -1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップします。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、適切に ユーザー に応答するか、例外を処理できます。 +1. まず、ガードレールはエージェントに渡されるのと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これは [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、 ユーザー へ適切に応答したり例外を処理できます。 !!! Note - 入力ガードレールは ユーザー 入力で実行されることを想定しているため、エージェントのガードレールはそのエージェントが最初のエージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか不思議に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するので、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールは ユーザー 入力で実行されることを意図しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントの場合にのみ実行されます。なぜ `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] 例外が送出されるため、適切に ユーザー に応答するか、例外を処理できます。 +1. まず、ガードレールはエージェントが生成した出力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これは [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、 ユーザー へ適切に応答したり例外を処理できます。 !!! Note - 出力ガードレールは最終的なエージェント出力で実行されることを想定しているため、エージェントのガードレールはそのエージェントが最後のエージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに関連する傾向があるため、エージェントごとに異なるガードレールを実行します。したがってコードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的なエージェントの出力で実行されることを意図しているため、エージェントのガードレールはそのエージェントが *最後* のエージェントの場合にのみ実行されます。入力ガードレールと同様、これはガードレールが実際のエージェントに関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことが可読性の向上に役立ちます。 ## トリップワイヤー -入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでそれを示すことができます。トリップワイヤーが作動したガードレールを検知したらすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェント実行を停止します。 +入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーがトリガーされたガードレールを検出した時点で、直ちに {Input,Output}GuardrailTripwireTriggered 例外を発生させ、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、内部でエージェントを実行してこれを行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、水面下でエージェントを実行してこれを行います。 ```python from pydantic import BaseModel diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index fb132874d..979c36345 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# ハンドオフ +# Handoffs -ハンドオフは、ある エージェント が別の エージェント にタスクを委譲することを可能にします。これは、異なる エージェント がそれぞれ別個の分野を専門とするシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱う エージェント が存在するかもしれません。 +Handoffs は、ある エージェント が別の エージェント にタスクを委譲できるようにします。これは、異なる エージェント がそれぞれ別個の分野を専門としているシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に扱う エージェント がいるかもしれません。 -ハンドオフは LLM からはツールとして表現されます。つまり、`Refund Agent` へのハンドオフがある場合、そのツール名は `transfer_to_refund_agent` となります。 +Handoffs は ツール として LLM に提示されます。たとえば、`Refund Agent` に handoff する場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、直接 `Agent` を渡すか、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すことができます。 +すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すか、Handoff をカスタマイズする `Handoff` オブジェクトを渡すことができます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先の エージェント に加えて、任意のオーバーライドや入力フィルターを指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使って handoff を作成できます。この関数では、handoff 先の エージェント に加えて、任意の上書き設定や入力フィルターを指定できます。 ### 基本的な使い方 -シンプルなハンドオフの作成方法は次のとおりです。 +以下のように、シンプルな 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()` 関数による handoffs のカスタマイズ [`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフ先の エージェント です。 +- `agent`: handoff 先の エージェント です。 - `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`: ハンドオフを有効にするかどうか。真偽値または真偽値を返す関数を指定でき、実行時にハンドオフを動的に有効／無効にできます。 +- `on_handoff`: handoff が呼び出されたときに実行されるコールバック関数です。handoff が呼ばれたことが分かった時点でデータ取得を開始する、といった用途に便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: handoff が期待する入力の型（任意）。 +- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は下記を参照してください。 +- `is_enabled`: handoff が有効かどうか。真偽値または真偽値を返す関数を指定でき、実行時に動的に handoff を有効・無効にできます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフ入力 +## Handoff inputs -状況によっては、ハンドオフを呼び出す際に LLM からいくつかのデータを提供させたい場合があります。例えば「エスカレーション エージェント」へのハンドオフでは、記録のために理由を提供させたいかもしれません。 +状況によっては、handoff を呼び出す際に LLM にデータを提供してほしいことがあります。例えば、「Escalation agent」への handoff を考えてみましょう。ログのために理由を提供してもらいたい場合があります。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できるのと同様になります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。 +handoff が発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できるかのように振る舞います。これを変更したい場合は、[`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 が handoffs を正しく理解できるようにするため、エージェント に handoffs に関する情報を含めることを推奨します。[`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 3ce414c9a..3d65818d0 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 -- ** ハンドオフ ** , エージェントが特定のタスクを他のエージェントに委任できる機能 -- ** ガードレール ** , エージェントの入力と出力を検証できる機能 -- ** セッション ** , エージェントの実行間で会話履歴を自動的に維持する機能 +- ** エージェント **: instructions と tools を備えた LLM +- ** ハンドオフ **: 特定のタスクについて、エージェントが他のエージェントへ委譲できる機能 +- ** ガードレール **: エージェントの入力と出力の検証を可能にする機能 +- ** セッション **: エージェントの実行間で会話履歴を自動的に保持する機能 -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実運用レベルのアプリケーションを構築できます。さらに、SDK には内蔵の ** トレーシング ** があり、エージェントのフローを可視化してデバッグできるほか、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 +これらの基本コンポーネントは、 Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実世界のアプリケーションを構築できます。さらに、 SDK には組み込みの ** トレーシング ** が含まれており、エージェントのフローを可視化・デバッグし、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK には次の 2 つの設計原則があります。 +この SDK は、次の 2 つの設計原則に基づいています。 -1. 使う価値があるだけの機能を備えつつ、学習を素早くするために基本コンポーネントは少数に保つこと。 -2. そのままでも十分に機能しつつ、動作を細部までカスタマイズできること。 +1. 使う価値があるだけの十分な機能を備えつつ、学習がすばやく済むよう基本コンポーネントは少数にする。 +2. すぐに使えて優れた体験を提供しつつ、動作を細部までカスタマイズできる。 -SDK の主な機能は次のとおりです。 +主な機能は次のとおりです。 -- エージェント ループ: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループ処理を内蔵。 -- Python ファースト: 新しい抽象化を学ぶのではなく、言語の組み込み機能でエージェントのオーケストレーションや連鎖を実現。 -- ハンドオフ: 複数のエージェント間の調整と委任を可能にする強力な機能。 -- ガードレール: エージェントと並行して入力の検証やチェックを実行し、失敗時は早期に中断。 +- エージェントループ: ツールの呼び出し、結果の LLM への送信、 LLM の完了までのループを処理する組み込みのエージェントループ。 +- Python ファースト: 新しい抽象化を学ぶ必要なく、言語の組み込み機能でエージェントのオーケストレーションとチェーン化が可能。 +- ハンドオフ: 複数のエージェント間の調整と委譲を可能にする強力な機能。 +- ガードレール: 検証をエージェントと並行して実行し、チェックが失敗したら早期に打ち切り。 - セッション: エージェントの実行間で会話履歴を自動管理し、手動の状態管理を不要に。 - 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 -- トレーシング: ワークフローの可視化、デバッグ、監視を可能にし、OpenAI の評価、ファインチューニング、蒸留ツール群も利用可能。 +- トレーシング: ワークフローの可視化・デバッグ・監視を可能にし、 OpenAI の評価、ファインチューニング、蒸留ツール群も利用可能。 ## インストール diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 04b367b69..ecb1c58d2 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,23 +4,23 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。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: -> 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 SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用して、エージェント にツールやプロンプトを提供できます。 ## MCP サーバー -現在、MCP の仕様は使用するトランスポート機構に基づいて 3 種類のサーバーを定義しています: +現在、MCP の仕様は、使用するトランスポート方式に基づいて 3 種類の サーバー を定義しています。 -1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。いわゆる「ローカル」で動作します。 -2. **HTTP over SSE** サーバーはリモートで動作します。URL を介して接続します。 -3. **Streamable HTTP** サーバーは、MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで動作します。 +1. **stdio** サーバーはアプリケーションのサブプロセスとして実行されます。いわゆる「ローカル」で動作すると考えられます。 +2. **HTTP over SSE** サーバーはリモートで実行されます。URL 経由で接続します。 +3. **Streamable HTTP** サーバーは、MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらの サーバー に接続するには、[`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)は次のように使用します。 +たとえば、[official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) は次のように使用します。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK は、エージェントが実行されるたびに MCP サーバー上で `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーで `call_tool()` を呼び出します。 +MCP サーバーは エージェント に追加できます。Agents SDK は、エージェント の実行ごとに MCP サーバー上で `list_tools()` を呼び出します。これにより、LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーで `call_tool()` を呼び出します。 ```python @@ -54,11 +54,11 @@ agent=Agent( ## ツールのフィルタリング -MCP サーバーでツールフィルターを構成することで、エージェントで使用可能なツールを絞り込めます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーでツールフィルターを設定することで、エージェント で利用可能なツールを制限できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 ### 静的ツールフィルタリング -単純な許可/ブロック リストには、静的フィルタリングを使用できます: +単純な許可/ブロック リストには、静的フィルタリングを使用できます。 ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が構成されている場合、処理順序は次のとおりです:** -1. まず `allowed_tool_names`（allowlist）を適用 — 指定したツールのみを残す -2. 次に `blocked_tool_names`（blocklist）を適用 — 残ったツールから指定したものを除外 +**`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` のツールだけになります。 +たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定した場合、`read_file` と `write_file` のツールのみが利用可能になります。 ### 動的ツールフィルタリング -より複雑なフィルタリングロジックには、関数を使った動的フィルターを使用できます: +より複雑なフィルタリングロジックには、関数を用いた動的フィルターを使用できます。 ```python from agents.mcp import ToolFilterContext @@ -134,21 +134,21 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次にアクセスできます: +`ToolFilterContext` では次の情報にアクセスできます。 - `run_context`: 現在の実行コンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +- `agent`: ツールを要求している エージェント +- `server_name`: MCP サーバーの名前 ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instructions テンプレートを作成できます。 +MCP サーバーは、エージェント の指示を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な指示テンプレートを作成できます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、2 つの主要メソッドを提供します: +プロンプトをサポートする MCP サーバーは、次の 2 つの主要なメソッドを提供します。 -- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示 -- `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得 +- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示します +- `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得します ```python # List available prompts @@ -173,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、MCP サーバーで `list_tools()` が呼び出されます。特にサーバーがリモート サーバーの場合、これはレイテンシの要因になり得ます。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないことが確実な場合にのみ実施してください。 +エージェント が実行されるたびに、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()` を呼び出せます。 +キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。 ## エンドツーエンドの code examples -動作する完全な code examples は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で、完全に動作する code examples を参照してください。 ## トレーシング -[トレーシング](./tracing.md) は次の MCP の操作を自動的に捕捉します: +[Tracing](./tracing.md) は、以下を含む MCP の操作を自動的に取得します。 -1. ツール一覧のための MCP サーバーへの呼び出し +1. ツール一覧の取得に対する MCP サーバーへの呼び出し 2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index b73f409a3..6185d0896 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに使える形で 2 通りサポートしています: +Agents SDK には、OpenAI モデル向けの標準サポートが 2 つの形で含まれています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい Responses API を使って OpenAI API を呼び出します (https://platform.openai.com/docs/api-reference/responses)。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。Chat Completions API を使って OpenAI API を呼び出します (https://platform.openai.com/docs/api-reference/chat)。 ## 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) など他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 -### デフォルトの 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 の推論モデル（[`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 の 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")` を呼び出してください。 -さらに低レイテンシや特定の要件のために、別のモデルや設定を選ぶこともできます。デフォルトモデルの推論強度を調整するには、独自の `ModelSettings` を渡します: +レイテンシを下げたい場合や特定の要件がある場合は、別のモデルと設定を選べます。デフォルトモデルの reasoning 努力度を調整するには、独自の `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"` の推論強度をサポートしていないため、本 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"` の reasoning 努力度をサポートしていないため、この 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) を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、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` を設定できるケース向けです。設定可能な sample code は [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` レベルで指定します。これにより、「この実行中のすべてのエージェントにカスタムモデルプロバイダーを使う」と宣言できます。設定可能な sample code は [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 インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使えます。設定可能な sample code は [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] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に適しています。設定可能な code examples は [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` レベルで設定します。これにより、「この実行でのすべての エージェント にカスタムモデルプロバイダーを使う」と指定できます。設定可能な code examples は [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 インスタンスでモデルを指定できます。これにより、エージェント ごとに異なるプロバイダーを組み合わせて使用できます。設定可能な code examples は [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 - これらの例では、Responses API をまだサポートしていない LLM プロバイダーがほとんどであるため、Chat Completions API/モデルを使用しています。お使いの LLM プロバイダーが対応している場合は、Responses の利用をおすすめします。 + これらの code examples では、Responses API をまだサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 ## モデルの組み合わせ -単一のワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。例えば、トリアージには小型で高速なモデルを使い、複雑なタスクにはより大きく高性能なモデルを使うといった形です。[`Agent`][agents.Agent] を構成する際、次のいずれかで特定のモデルを選べます: +単一のワークフロー内で、エージェント ごとに異なるモデルを使用したいことがあります。例えば、トリアージには小さく高速なモデルを使い、複雑なタスクにはより大きく高性能なモデルを使うといった形です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選択できます。 1. モデル名を渡す。 -2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +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 @@ -125,7 +125,7 @@ async def main(): 1. OpenAI モデルの名前を直接設定します。 2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに構成したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。これは、temperature などの任意のモデル構成パラメーターを提供します。 +エージェント で使用するモデルをさらに構成したい場合は、温度 (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 +### トレーシング クライアントのエラー 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/) のものが必要です。 -3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +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 スキーマ出力をサポートしているプロバイダーを利用することをおすすめします。そうでない場合、JSON の形式が不正になりやすく、アプリが頻繁に壊れる原因となるためです。 +これは一部のモデルプロバイダーの制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないという問題です。現在これに対する修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することを推奨します。そうでない場合、不正な JSON によりアプリがしばしば壊れてしまいます。 ## プロバイダーをまたいだモデルの混在 -モデルプロバイダー間の機能差に注意しないと、エラーに直面する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索および Web 検索をサポートしていますが、多くの他社プロバイダーはこれらの機能をサポートしていません。次の制約に注意してください: +モデルプロバイダー間の機能差を把握しておかないと、エラーに直面する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしていますが、多くの他プロバイダーはこれらの機能に対応していません。以下の制約に注意してください。 -- サポートしていない `tools` を理解しないプロバイダーには送らないでください +- サポートしていない `tools` を理解しないプロバイダーに送信しないでください - テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- 構造化された JSON 出力をサポートしていないプロバイダーでは、無効な JSON が出力されることがあります \ No newline at end of file +- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがある点に注意してください。 \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 633221380..cc402f960 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -6,29 +6,29 @@ search: !!! 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]" ``` -完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +完了したら、任意の エージェント で [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 -## コード例 +## 例 -これは完全に動作するコード例です。実行すると、モデル名と 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 9889ad6c1..42b79fee5 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 によるオーケストレーション -エージェントは、指示、ツール、ハンドオフを備えた LLM です。これは、オープンエンドなタスクを与えられたときに、LLM が自律的に計画を立て、ツールでアクションやデータ取得を行い、ハンドオフでサブエージェントへタスクを委任できることを意味します。たとえば、リサーチ用のエージェントには次のようなツールを装備できます。 +エージェントとは、instructions、ツール、ハンドオフを備えた LLM です。これは、オープンエンドなタスクに対して、LLM が自律的にタスクの進め方を計画し、ツールを使って行動やデータ取得を行い、ハンドオフを使ってサブエージェントにタスクを委任できることを意味します。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 -- Web 検索でオンライン情報を見つける -- ファイル検索と取得で自社データや接続先を検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画策定、レポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索によりオンラインで情報を見つける +- ファイル検索と取得によりプロプライエタリデータや接続を検索する +- コンピュータ操作によりコンピュータ上でアクションを実行する +- コード実行によりデータ分析を行う +- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、 LLM の知性に依拠したい場合に有効です。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知能に頼りたい場合に有効です。ここで重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、運用すべきパラメーターを明確にします。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にします。 2. アプリを監視し、反復改善する。問題が起きる箇所を把握し、プロンプトを改善します。 -3. エージェントに内省と改善を許す。例えばループで実行し、自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもこなす汎用エージェントではなく、特定のタスクに特化して卓越したエージェントを用意する。 -5. [evals（評価）](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を高められます。 +3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 +4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して優れたエージェントを用意する。 +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 の基本コンポーネントである `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) に多数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 4f816cfe3..9625e4d84 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 キーの設定 -お持ちでない場合は、OpenAI API キーを作成するために [こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従ってください。 +お持ちでない場合は、[この手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初の エージェント の作成 +## 最初のエージェントの作成 -エージェント は instructions、名前、任意の config（例: `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 @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各 エージェント で、タスクを進める方法を決定するために選択できる、発信側のハンドオフ候補の一覧を定義できます。 +各エージェントで、タスクを進める方法を決定するために選択できる、発信側ハンドオフ オプションのインベントリを定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ 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 @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの閲覧 +## トレースの表示 -エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して、エージェント実行のトレースを閲覧してください。 +エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して、エージェント実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェント フローの作り方を学びましょう: +より複雑なエージェント フローの構築方法: -- [エージェント](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 ac78ed113..52d8abc42 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、ハンドオフで構成されたエージェント。 +- **RealtimeAgent**: instructions、tools、ハンドオフで設定されたエージェント。 - **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一のインタラクションセッション。通常は ユーザー が会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデルのインターフェース（一般的には OpenAI の WebSocket 実装） -### セッションフロー +### セッションの流れ -一般的な realtime セッションは次のフローに従います。 +一般的な realtime セッションは次の流れに従います。 -1. instructions、tools、ハンドオフを用いて **RealtimeAgent を作成** します。 -2. エージェントと構成オプションで **RealtimeRunner をセットアップ** します。 -3. `await runner.run()` を使用して **セッションを開始** し、RealtimeSession を取得します。 -4. `send_audio()` または `send_message()` を使用して **音声またはテキストメッセージを送信** します。 -5. セッションを反復処理して **イベントをリッスン** します。イベントには音声出力、トランスクリプト、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. ユーザー がエージェントの発話に被せて話す **割り込みを処理** します。これにより、現在の音声生成は自動的に停止します。 +1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 +2. **RealtimeRunner を設定** し、エージェントと構成オプションを渡します。 +3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返ります。 +4. **音声またはテキストメッセージを送信** します。`send_audio()` または `send_message()` を使用します。 +5. **イベントをリッスン** します。セッションをイテレートして、音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーなどのイベントを受け取ります。 +6. **割り込みに対応** します。ユーザーがエージェントの発話にかぶせた場合、進行中の音声生成は自動的に停止します。 セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 ## エージェントの設定 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご参照ください。 +RealtimeAgent は通常の Agent クラスと類似していますが、いくつか重要な相違があります。完全な API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご参照ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェントレベルではなく、セッションレベルで設定します。 -- structured output のサポートはありません（`outputType` はサポートされません）。 -- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- ツール、ハンドオフ、instructions など、その他の機能は同じように動作します。 +- モデル選択はエージェントではなくセッション単位で設定します。 +- structured outputs のサポートはありません（`outputType` は非対応）。 +- 声質はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- ツール、ハンドオフ、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**: ユーザー がエージェントを割り込み +- **audio**: エージェントの応答からの raw 音声データ +- **audio_end**: エージェントの発話完了 +- **audio_interrupted**: ユーザーがエージェントを割り込み - **tool_start/tool_end**: ツール実行のライフサイクル -- **handoff**: エージェントのハンドオフが発生 +- **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,17 +152,17 @@ agent = RealtimeAgent( ) ``` -ガードレール がトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を割り込むことがあります。デバウンスの挙動は、安全性とリアルタイムの性能要件のバランスを取るのに役立ちます。テキストエージェントと異なり、realtime エージェントは ガードレール が作動しても 例外 をスローしません。 +ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断することがあります。デバウンス動作は、安全性とリアルタイム性能要件のバランスを取るのに役立ちます。テキストエージェントと異なり、realtime エージェントはガードレールがトリップしても Exception をスローしません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用して音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 +[`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 @@ -171,6 +171,6 @@ session.model.add_listener(my_custom_listener) これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## code examples +## コード例 -完全な動作する code examples は、UI コンポーネントの有無それぞれのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file +完全に動作するコード例は、[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 3e9c42313..1bd1e8ec2 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,10 +4,10 @@ search: --- # クイックスタート -リアルタイム エージェントは、OpenAI の Realtime API を使って AI 音声会話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントを作成する手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、互換性のない変更が発生する場合があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 前提条件 @@ -23,7 +23,7 @@ Realtime エージェントはベータ版です。実装の改善に伴い、 pip install openai-agents ``` -## 最初の リアルタイム エージェントの作成 +## 最初のリアルタイム エージェントの作成 ### 1. 必要なコンポーネントのインポート @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. ランナーの設定 +### 3. Runner のセットアップ ```python runner = RealtimeRunner( @@ -79,7 +79,7 @@ async def main(): asyncio.run(main()) ``` -## 完全なコード例 +## 完全な例 以下は動作する完全な例です: @@ -135,38 +135,38 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 設定オプション +## 構成オプション ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-4o-realtime-preview`) -- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストや音声の有効化 (`["text", "audio"]`) +- `model_name`: 利用可能なリアルタイム モデルから選択（例: `gpt-4o-realtime-preview`） +- `voice`: 音声の選択（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） +- `modalities`: テキスト および/または 音声を有効化（`["text", "audio"]`） ### 音声設定 -- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `input_audio_format`: 入力音声の形式（`pcm16`、`g711_ulaw`、`g711_alaw`） - `output_audio_format`: 出力音声の形式 -- `input_audio_transcription`: 音声書き起こしの設定 +- `input_audio_transcription`: 文字起こしの設定 -### ターン検出 +### 発話区切り検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声活動のしきい値 (0.0–1.0) +- `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) フォルダーの動作するサンプルを確認 +- [リアルタイム エージェントの詳細](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作する code examples を確認 - エージェントにツールを追加 - エージェント間のハンドオフを実装 -- 安全のためのガードレールを設定 +- 安全性のためにガードレールを設定 ## 認証 -OpenAI API キーが環境に設定されていることを確認してください: +OpenAI API キーが環境に設定されていることを確認します: ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/ja/release.md b/docs/ja/release.md index 72e0b8922..e15f96a08 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,29 +4,29 @@ search: --- # リリースプロセス/変更履歴 -このプロジェクトは、`0.Y.Z` という形式を用いた、やや改変した semantic versioning に従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します。 +本プロジェクトは、`0.Y.Z` という形式のやや修正したセマンティックバージョニングに従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 -## マイナー (`Y`) バージョン +## マイナー（`Y`）バージョン -ベータではない公開インターフェースに対する、 **互換性のない変更** がある場合に、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には互換性のない変更が含まれる可能性があります。 +ベータではない公開インターフェースに対する破壊的変更がある場合、マイナー版 `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には、破壊的変更が含まれる可能性があります。 -互換性のない変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 -## パッチ (`Z`) バージョン +## パッチ（`Z`）バージョン -互換性を壊さない変更の場合、`Z` を増分します。 +後方互換な変更には `Z` を増分します。 - バグ修正 - 新機能 - 非公開インターフェースの変更 - ベータ機能の更新 -## 互換性のない変更の変更履歴 +## 破壊的変更の変更履歴 ### 0.2.0 -このバージョンでは、これまで `Agent` を引数として受け取っていた箇所の一部が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、 MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型に関する変更のみであり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 +このバージョンでは、これまで `Agent` を引数（arg）に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。たとえば、 MCP サーバーでの `list_tools()` 呼び出しが該当します。これは純粋に型付け上の変更であり、引き続き受け取るのは `Agent` オブジェクトです。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけで済みます。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 2 つの新しい パラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承するクラスには、これらの パラメーター を追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 2 つの新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` をサブクラス化しているすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 1ae0ccff2..42769bfdb 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 @@ -19,6 +19,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 e128835db..3dba44265 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 実行結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返ります。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] +- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] -これらはいずれも [`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` 型のオブジェクト +- エージェントに出力タイプが定義されている場合は、`last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。これは handoffs のため、静的型付けができません。handoffs が発生する場合、どのエージェントが最後になるかは不定のため、可能な出力型の集合を静的に特定できません。 + `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] です。Run item は、 LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 -- [`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 からのメッセージを示します。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 アイテムは生成された推論です。 ## その他の情報 ### ガードレールの実行結果 -[`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 レスポンス -[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、 LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 +[`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 baacb8776..1c6846924 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -[`Runner`][agents.run.Runner] クラスでエージェントを実行できます。方法は 3 つあります: +エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。オプションは 3 つあります。 -1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 +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 @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳しくは [実行結果ガイド](results.md) を参照してください。 +詳しくは [実行結果ガイド](results.md) をご覧ください。 ## エージェントループ -`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われます）か、OpenAI Responses API のアイテムのリストのいずれかです。 +`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われます）または入力アイテムのリストで、OpenAI Responses API のアイテムです。 -Runner は次のループを実行します: +ランナーは次のループを実行します。 -1. 現在のエージェントと現在の入力で LLM を呼び出します。 +1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し、実行結果を返します。 - 2. LLM がハンドオフした場合、現在のエージェントと入力を更新して、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追加して、ループを再実行します。 + 1. LLM が `final_output` を返した場合、ループは終了し、実行結果を返します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新して、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加して、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」とみなされる条件は、所望の型のテキスト出力を生成し、ツール呼び出しが 1 つもないことです。 + LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、かつツール呼び出しがないことです。 ## ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成された新しい出力を含む実行全体の情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出して取得できます。詳しくは [ストリーミングガイド](streaming.md) を参照してください。 +ストリーミングにより、LLM の実行中にストリーミングイベントを受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に、その実行で生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すことで取得できます。詳しくは [ストリーミングガイド](streaming.md) をご覧ください。 ## 実行設定 -`run_config` パラメーターで、エージェント実行のグローバル設定を構成できます: +`run_config` パラメーターは、エージェント実行のグローバル設定を構成できます。 -- [`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] のドキュメントを参照してください。 +- [`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) を無効化できます。 -- [`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 は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 +- [`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 は任意で、複数の実行をまたいでトレースを関連付けできます。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話/チャットスレッド -いずれの run メソッドを呼び出しても、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される可能性がありますが、チャット会話における 1 回の論理的なターンを表します。例: +任意の run メソッドを呼び出すと、1 つ以上のエージェントが実行される（つまり 1 回以上 LLM が呼び出される）可能性がありますが、これはチャット会話の 1 回の論理ターンを表します。例: 1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行してから出力を生成。 +2. ランナーの実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフし、2 番目のエージェントがさらにツールを実行し、その後に出力を生成します。 -エージェントの実行が終わったら、ユーザーに何を見せるかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを表示する、または最終出力のみを表示する、といった選択です。いずれの場合でも、ユーザーが追質問をするかもしれません。その場合は再度 run メソッドを呼び出せます。 +エージェントの実行の最後に、ユーザーに何を表示するかを選べます。例えば、エージェントが生成したすべての新しいアイテムを表示することも、最終出力のみを表示することもできます。いずれの場合も、ユーザーが追質問をするかもしれません。その場合は再度 run メソッドを呼び出せます。 ### 手動の会話管理 -次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます: +次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って、会話履歴を手動で管理できます。 ```python async def main(): @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[セッション](sessions.md) を使えば `.to_input_list()` を手動で呼び出さずに会話履歴を自動処理できます: +より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出さずに会話履歴を自動処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -116,26 +116,26 @@ async def main(): # California ``` -セッションは自動的に次を行います: +Sessions は自動で次を行います。 -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 +- 各実行の前に会話履歴を取得 +- 各実行の後に新しいメッセージを保存 - 異なるセッション ID ごとに個別の会話を維持 -詳細は [セッションのドキュメント](sessions.md) を参照してください。 +詳細は [Sessions のドキュメント](sessions.md) をご覧ください。 -## 長時間実行のエージェントとヒューマン・イン・ザ・ループ +## 長時間実行エージェントと human-in-the-loop -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) をご覧ください。 +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) をご覧ください。 ## 例外 -この 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 の使用中に誤りを犯したときに送出されます。誤ったコード実装、無効な設定、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 24f5850cb..9d62ab970 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に維持するための組み込みセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 +Agents SDK は、複数のエージェント実行間で会話履歴を自動的に保持する組み込みの session メモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 -セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリやマルチターンの会話を構築する際に特に有用です。 +Sessions は特定の session の会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリが有効な場合: +session メモリが有効な場合: -1. **各実行前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの先頭に付与します。 -2. **各実行後**: 実行中に生成されたすべての新規アイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が自動的にセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションでの後続の実行には全会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: runner は session の会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が自動的に session に保存されます。 +3. **コンテキストの保持**: 同じ session での後続の実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 -これにより、実行間で `.to_input_list()` を手動で呼び出したり会話状態を管理したりする必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出して、実行間の会話状態を管理する必要がなくなります。 ## メモリ操作 ### 基本操作 -セッションは会話履歴を管理するためにいくつかの操作をサポートします: +Sessions は、会話履歴を管理するための複数の操作をサポートします: ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 修正のための `pop_item` の使用 +### 修正のための pop_item の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたいときに特に有用です: +`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したい場合に特に有用です: ```python from agents import Agent, Runner, SQLiteSession @@ -168,13 +168,13 @@ result2 = await Runner.run( ) ``` -### SQLAlchemy 対応セッション +### SQLAlchemy ベースのセッション -さらに高度なユースケースでは、SQLAlchemy 対応のセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）をセッションストレージに利用できます。 +より高度なユースケースでは、SQLAlchemy ベースの session バックエンドを使用できます。これにより、session の保存に SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 -**例 1: `from_url` を使ったインメモリ SQLite** +**例 1: `from_url` とインメモリ SQLite を使用** -これは最も簡単な入門方法で、開発やテストに最適です。 +これは最も簡単な始め方で、開発やテストに最適です。 ```python import asyncio @@ -195,9 +195,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy エンジンを使用** +**例 2: 既存の SQLAlchemy engine を使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性が高いです。これをそのままセッションに渡せます。 +本番アプリケーションでは、既に SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性が高いです。これを session に直接渡せます。 ```python import asyncio @@ -228,7 +228,7 @@ if __name__ == "__main__": ## カスタムメモリ実装 -[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自の session メモリを実装できます: ```python from agents.memory.session import SessionABC @@ -275,18 +275,18 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすい意味のあるセッション ID を使いましょう: +会話を整理しやすい意味のある session ID を使用します: -- ユーザー基準: `"user_12345"` -- スレッド基準: `"thread_abc123"` -- コンテキスト基準: `"support_ticket_456"` +- ユーザー別: `"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)`）を使用 -- さらに高度なユースケースに向けて、他の本番システム（Redis、Django など）用のカスタムセッションバックエンドの実装を検討 +- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します +- 既存のデータベースを SQLAlchemy がサポートする本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します +- より高度なユースケース向けに、他の本番システム（Redis、Django など）用のカスタム session バックエンドの実装を検討します ### セッション管理 @@ -314,7 +314,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリの動作を示す完全な例です: +以下は、session メモリの動作を示す完全な例です: ```python import asyncio @@ -378,8 +378,8 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは以下をご覧ください: +詳細な API ドキュメントは以下を参照してください: - [`Session`][agents.memory.Session] - プロトコルインターフェース - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 対応実装 \ No newline at end of file +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 726e16d24..7391c0a8c 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、進行中の エージェント の実行に対する更新を購読できます。これは、エンド ユーザー に進捗や部分的な応答を表示するのに役立ちます。 +ストリーミングを使うと、エージェント実行の進行に合わせて更新を購読できます。これは、エンドユーザーに進捗更新や部分的な応答を表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これは [`RunResultStreaming`][agents.result.RunResultStreaming] を返します。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより、[`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼ぶと、後述の [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 -## raw レスポンスイベント +## 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 item イベントと エージェント イベント +## 実行アイテムイベントとエージェントイベント -[`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 27b5c28ce..c110ed0ca 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント に行動を取らせます。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 つのツールクラスがあります: +ツールは エージェント に行動を取らせます。たとえば、データ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作 などです。Agents SDK には 3 つのツールのクラスがあります。 -- ホスト型ツール: これらは AI モデルと並んで LLM サーバー 上で動作します。OpenAI は リトリーバル、 Web 検索、そして コンピュータ操作 をホスト型ツールとして提供しています。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は retrieval、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 ベクトルストア から情報を取得できます。 -- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を可能にします。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web 検索 を実行させます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を取得します。 +- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を行います。 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM にサンドボックス環境でコードを実行させます。 - [`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 から取得します（または任意の説明を指定できます） -- 関数入力のスキーマは関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り、関数の docstring から取得します +- ツール名は Python 関数名になります（任意で名前を指定可能） +- ツールの説明は関数の 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,10 +102,10 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、関数は同期でも非同期でも構いません。 -2. docstring があれば、説明および引数の説明として利用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring スタイルなどの上書きも設定できます。 -4. デコレートした関数をツールのリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期どちらでも構いません。 +2. docstring があれば、説明文と引数の説明に利用します。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring の形式などを上書き設定することも可能です。 +4. デコレートした関数をツール一覧に渡せます。 ??? note "出力を表示" @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### カスタム 関数ツール +### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。その場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を指定する必要があります: +Python 関数をツールとして使いたくない場合もあります。必要に応じて直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を指定する必要があります。 - `name` - `description` - `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力の文字列を返す非同期関数） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列の引数を受け取り、ツールの出力を文字列で返す非同期関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。注意点: +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足事項は以下のとおりです。 -1. シグネチャ解析は `inspect` モジュール経由で行います。引数の型は型アノテーションから解釈し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますがベストエフォートであり、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 +1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を解釈し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。対応フォーマットは `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 @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を変更したいことがあります。例えば次のような場合に有用です: +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に有用です。 - サブエージェントのチャット履歴から特定の情報（例: 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: @@ -315,9 +315,9 @@ 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` パラメーター は次を受け付けます: -- **ブール値**: `True`（常に有効）または `False`（常に無効） -- **呼び出し可能関数**: `(context, agent)` を受け取り、真偽値を返す関数 -- **非同期関数**: 複雑な条件ロジック用の非同期関数 +`is_enabled` パラメーター は次を受け付けます。 +- **ブール値**: `True`（常に有効）または `False`（常に無効） +- **呼び出し可能な関数**: `(context, agent)` を受け取り、真偽値を返す関数 +- **非同期関数**: 複雑な条件ロジック用の async 関数 -無効化されたツールは実行時に LLM から完全に隠蔽されるため、次の用途に有用です: +無効化されたツールは実行時に LLM から完全に隠蔽されるため、次の用途に有用です。 - ユーザー 権限に基づく機能ゲーティング -- 環境別のツール提供（dev と prod での違い） +- 環境別のツール可用性（dev と prod） - 異なるツール構成の A/B テスト -- 実行時状態に基づく動的なツールフィルタリング +- 実行時状態に基づく動的ツールフィルタリング ## 関数ツールでのエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラーレスポンスを提供する関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラー応答を提供する関数です。 -- 既定（何も渡さない場合）では、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 -- 独自のエラー関数を渡すと、それが代わりに実行され、そのレスポンスが LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しエラーは再送出され、あなたが処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、あなたのコードがクラッシュした場合は `UserError` などになり得ます。 +- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 +- 独自のエラー関数を渡した場合はそれが実行され、その応答が LLM に送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、呼び出し側で処理する必要があります。これは、モデルが不正な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index d5e1344ce..52912abd1 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,37 +4,37 @@ 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` に設定して無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化できます + 2. 1 回の実行については、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます -***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** +*** ZDR (Zero Data Retention) ポリシーの下で OpenAI の API を使用して運用する組織では、トレーシングは利用できません。 *** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンド処理を表します。スパンで構成されます。トレースには以下のプロパティがあります。 - - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - - `trace_id`: トレースの一意の ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 省略可能なグループ ID。同一の会話からの複数のトレースを関連付けるために使用します。例えば、チャットスレッドの ID を使えます。 +- ** トレース ** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります。 + - `workflow_name`: これは論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースをリンクするために使用します。例えばチャット スレッド ID を使うことができます。 - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースのオプションのメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには以下があります。 + - `metadata`: トレースの任意のメタデータ。 +- ** スパン ** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。 - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` - - 親スパン (あれば) を指す `parent_id` + - 親スパン (ある場合) を指す `parent_id` - スパンに関する情報である `span_data`。例えば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます。 ## デフォルトのトレーシング -デフォルトでは、SDK は次をトレースします。 +デフォルトで、SDK は次をトレースします。 -- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` によってラップされます -- エージェントが実行されるたびに、`agent_span()` でラップされます +- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます +- エージェントが実行されるたびに `agent_span()` でラップされます - LLM 生成は `generation_span()` でラップされます - 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます - ガードレールは `guardrail_span()` でラップされます @@ -43,13 +43,13 @@ Agents SDK には組み込みのトレーシングが含まれており、エー - 音声出力 (text-to-speech) は `speech_span()` でラップされます - 関連する音声スパンは `speech_group_span()` の下に親子付けされる場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定でき、または [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の送信先にプッシュできます (置き換え、またはセカンダリ送信先として)。 +さらに、[custom trace processors](#custom-tracing-processors) を設定して、トレースを別の宛先にプッシュできます (置き換えまたは副次的な宛先として)。 ## 上位レベルのトレース -場合によっては、複数の `run()` 呼び出しを 1 つのトレースの一部にしたいことがあります。その場合は、コード全体を `trace()` でラップします。 +`run()` への複数回の呼び出しを単一のトレースの一部にしたい場合があります。これは、コード全体を `trace()` でラップすることで実現できます。 ```python from agents import Agent, Runner, trace @@ -68,42 +68,43 @@ async def main(): ## トレースの作成 -[`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` を含めない限り、トレースは OpenAI バックエンドに送信されません。 -## Non-OpenAI モデルでのトレーシング -OpenAI の API キーを Non-OpenAI モデルで使用して、トレーシングを無効化することなく、OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。 +## OpenAI 以外のモデルでのトレーシング + +OpenAI の API キーを OpenAI 以外のモデルで使用して、トレーシングを無効にすることなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -125,9 +126,10 @@ 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) diff --git a/docs/ja/usage.md b/docs/ja/usage.md index b5a73de80..c3ced94c4 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?") @@ -32,27 +32,37 @@ print("Total tokens:", usage.total_tokens) 使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 -## セッションでの使用状況アクセス +## セッションでの使用状況へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、同一の実行内の複数ターンにわたって使用状況が蓄積されます。`Runner.run(...)` の各呼び出しは、その時点での実行の累積使用状況を返します。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") first = await Runner.run(agent, "Hi!", session=session) -print(first.context_wrapper.usage.total_tokens) +print(first.context_wrapper.usage.total_tokens) # Usage for first run second = await Runner.run(agent, "Can you elaborate?", session=session) -print(second.context_wrapper.usage.total_tokens) # includes both turns +print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` +なお、セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しが返す使用状況の指標は、その時点の実行結果のみを表します。セッションでは、前のメッセージが各実行の入力として再投入されることがあり、その結果、後続ターンの入力トークン数に影響します。 + ## フックでの使用状況の利用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの要所で使用状況を記録できます。 +`RunHooks` を使用する場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクル時点で使用状況を記録できます。 ```python class MyHooks(RunHooks): async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: u = context.usage print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") -``` \ No newline at end of file +``` + +## API リファレンス + +詳細な API ドキュメントは以下を参照してください: + +- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況へアクセス +- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡ライフサイクルへのフック \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index b1ad4499a..6b646fb56 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,31 +67,31 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![エージェント グラフ](../assets/images/graph.png) -これは、 ** トリアージ エージェント ** の構造と、サブエージェントおよびツールへの接続を視覚的に表すグラフを生成します。 +これは **トリアージ エージェント** と、そのサブエージェントやツールへの接続構造を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されたグラフには次が含まれます: +生成されるグラフには次が含まれます: -- エントリーポイントを示す ** 開始ノード **（`__start__`）。 -- 黄色で塗りつぶされた ** 長方形 ** で表されるエージェント。 -- 緑色で塗りつぶされた ** 楕円 ** で表されるツール。 -- 灰色で塗りつぶされた ** 長方形 ** で表される MCP サーバー。 +- エントリーポイントを示す **開始ノード**（`__start__`）。 +- 黄色で塗りつぶされた **長方形** で表されるエージェント。 +- 緑で塗りつぶされた **楕円** で表されるツール。 +- 灰色で塗りつぶされた **長方形** で表される MCP サーバー。 - 相互作用を示す有向エッジ: - - エージェント間のハンドオフには ** 実線の矢印 **。 - - ツール呼び出しには ** 点線の矢印 **。 - - MCP サーバー呼び出しには ** 破線の矢印 **。 -- 実行が終了する場所を示す ** 終了ノード **（`__end__`）。 + - エージェント間ハンドオフには **実線の矢印**。 + - ツール呼び出しには **点線の矢印**。 + - MCP サーバー呼び出しには **破線の矢印**。 +- 実行の終了箇所を示す **終了ノード**（`__end__`）。 -** 注意: ** MCP サーバーは最近の `agents` パッケージ（ ** v0.2.8 ** で確認済み）でレンダリングされます。可視化に MCP ボックスが表示されない場合は、最新のリリースにアップグレードしてください。 +**注意:** MCP サーバーは最近の `agents` パッケージでレンダリングされます（ **v0.2.8** で検証済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウでグラフを表示するには、次のように記述します: +デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index e6b072230..eec59540b 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,29 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際に、次の項目を設定できます。 +パイプラインを作成するとき、以下を設定できます。 -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] - - モデル名をモデルにマッピングできるモデルプロバイダー - - トレーシング（トレーシングの無効化、音声ファイルのアップロード可否、ワークフロー名、トレース ID など） +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]。次のような項目を設定できます: + - モデルプロバイダー（モデル名をモデルにマッピングできます） + - トレーシング（トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） - 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] は、ユーザーの発話終了を検出する必要がある場合に使います。検出された音声チャンクを逐次プッシュでき、パイプラインが「アクティビティ検出」により適切なタイミングでエージェントのワークフローを自動実行します。 +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] -3. エラーイベントである [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]（音声チャンクを含みます） +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 e2a326d1d..7382ee2d4 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 でエージェントを作成したことがあれば馴染みがあるはずです。ここでは、2 つのエージェント、ハンドオフ、そして 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 @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめ +## 全体の統合 ```python import asyncio @@ -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) にあるサンプルコードを確認してください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 67127da3b..d9a7797d5 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -6,13 +6,13 @@ search: [エージェントのトレーシング](../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]: 音声書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用で、ワークフロー内部で行われる処理には適用されません。 -- [`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` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file +- [`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`。複数のトレースをリンクできます。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加メタデータ。 \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md index fc0fae9e2..4f0a66309 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -30,25 +30,35 @@ Usage is aggregated across all model calls during the run (including tool calls ## Accessing usage with sessions -When you use a `Session` (e.g., `SQLiteSession`), usage continues to accumulate across turns within the same run. Each call to `Runner.run(...)` returns the run’s cumulative usage at that point. +When you use a `Session` (e.g., `SQLiteSession`), each call to `Runner.run(...)` returns usage for that specific run. Sessions maintain conversation history for context, but each run's usage is independent. ```python session = SQLiteSession("my_conversation") first = await Runner.run(agent, "Hi!", session=session) -print(first.context_wrapper.usage.total_tokens) +print(first.context_wrapper.usage.total_tokens) # Usage for first run second = await Runner.run(agent, "Can you elaborate?", session=session) -print(second.context_wrapper.usage.total_tokens) # includes both turns +print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` +Note that while sessions preserve conversation context between runs, the usage metrics returned by each `Runner.run()` call represent only that particular execution. In sessions, previous messages may be re-fed as input to each run, which affects the input token count in consequent turns. + ## Using usage in hooks -If you’re using `RunHooks`, the `context` object passed to each hook contains `usage`. This lets you log usage at key lifecycle moments. +If you're using `RunHooks`, the `context` object passed to each hook contains `usage`. This lets you log usage at key lifecycle moments. ```python class MyHooks(RunHooks): async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: u = context.usage print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") -``` \ No newline at end of file +``` + +## API Reference + +For detailed API documentation, see: + +- [`Usage`][agents.usage.Usage] - Usage tracking data structure +- [`RunContextWrapper`][agents.run.RunContextWrapper] - Access usage from run context +- [`RunHooks`][agents.run.RunHooks] - Hook into usage tracking lifecycle \ No newline at end of file diff --git a/examples/tools/web_search_filters.py b/examples/tools/web_search_filters.py index 22b3864ea..6be30b169 100644 --- a/examples/tools/web_search_filters.py +++ b/examples/tools/web_search_filters.py @@ -1,7 +1,7 @@ import asyncio from datetime import datetime -from openai.types.responses.tool import WebSearchToolFilters +from openai.types.responses.web_search_tool import Filters from openai.types.shared.reasoning import Reasoning from agents import Agent, ModelSettings, Runner, WebSearchTool, trace @@ -18,7 +18,7 @@ async def main(): tools=[ WebSearchTool( # https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#domain-filtering - filters=WebSearchToolFilters( + filters=Filters( allowed_domains=[ "openai.com", "developer.openai.com", diff --git a/pyproject.toml b/pyproject.toml index 25d950b34..600f0cbba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ requires-python = ">=3.9" license = "MIT" authors = [{ name = "OpenAI", email = "support@openai.com" }] dependencies = [ - "openai>=1.102.0,<2", + "openai>=1.104.1,<2", "pydantic>=2.10, <3", "griffe>=1.5.6, <2", "typing-extensions>=4.12.2, <5", diff --git a/src/agents/models/openai_responses.py b/src/agents/models/openai_responses.py index 85d8a0224..0b409f7b0 100644 --- a/src/agents/models/openai_responses.py +++ b/src/agents/models/openai_responses.py @@ -433,7 +433,7 @@ def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, ResponseIncludable | None converted_tool = { "type": "web_search", "filters": tool.filters.model_dump() if tool.filters is not None else None, # type: ignore [typeddict-item] - "user_location": tool.user_location, # type: ignore [typeddict-item] + "user_location": tool.user_location, "search_context_size": tool.search_context_size, } includes = None diff --git a/src/agents/realtime/model.py b/src/agents/realtime/model.py index d7ebe4ffa..c0632aa9b 100644 --- a/src/agents/realtime/model.py +++ b/src/agents/realtime/model.py @@ -118,6 +118,12 @@ class RealtimeModelConfig(TypedDict): the OpenAI Realtime model will use the default OpenAI WebSocket URL. """ + headers: NotRequired[dict[str, str]] + """The headers to use when connecting. If unset, the model will use a sane default. + Note that, when you set this, authorization header won't be set under the hood. + e.g., {"api-key": "your api key here"} for Azure OpenAI Realtime WebSocket connections. + """ + initial_model_settings: NotRequired[RealtimeSessionModelSettings] """The initial model settings to use when connecting.""" diff --git a/src/agents/realtime/openai_realtime.py b/src/agents/realtime/openai_realtime.py index 766c49f8d..b9048a1ec 100644 --- a/src/agents/realtime/openai_realtime.py +++ b/src/agents/realtime/openai_realtime.py @@ -188,15 +188,23 @@ async def connect(self, options: RealtimeModelConfig) -> None: else: self._tracing_config = "auto" - if not api_key: - raise UserError("API key is required but was not provided.") - url = options.get("url", f"wss://api.openai.com/v1/realtime?model={self.model}") - headers = { - "Authorization": f"Bearer {api_key}", - "OpenAI-Beta": "realtime=v1", - } + headers: dict[str, str] = {} + if options.get("headers") is not None: + # For customizing request headers + headers.update(options["headers"]) + else: + # OpenAI's Realtime API + if not api_key: + raise UserError("API key is required but was not provided.") + + headers.update( + { + "Authorization": f"Bearer {api_key}", + "OpenAI-Beta": "realtime=v1", + } + ) self._websocket = await websockets.connect( url, user_agent_header=_USER_AGENT, @@ -490,9 +498,7 @@ async def _handle_ws_event(self, event: dict[str, Any]): try: if "previous_item_id" in event and event["previous_item_id"] is None: event["previous_item_id"] = "" # TODO (rm) remove - parsed: AllRealtimeServerEvents = self._server_event_type_adapter.validate_python( - event - ) + parsed: AllRealtimeServerEvents = self._server_event_type_adapter.validate_python(event) except pydantic.ValidationError as e: logger.error(f"Failed to validate server event: {event}", exc_info=True) await self._emit_event( @@ -583,11 +589,13 @@ async def _handle_ws_event(self, event: dict[str, Any]): ): await self._handle_output_item(parsed.item) elif parsed.type == "input_audio_buffer.timeout_triggered": - await self._emit_event(RealtimeModelInputAudioTimeoutTriggeredEvent( - item_id=parsed.item_id, - audio_start_ms=parsed.audio_start_ms, - audio_end_ms=parsed.audio_end_ms, - )) + await self._emit_event( + RealtimeModelInputAudioTimeoutTriggeredEvent( + item_id=parsed.item_id, + audio_start_ms=parsed.audio_start_ms, + audio_end_ms=parsed.audio_end_ms, + ) + ) def _update_created_session(self, session: OpenAISessionObject) -> None: self._created_session = session diff --git a/src/agents/run.py b/src/agents/run.py index c68e41989..4575edb3f 100644 --- a/src/agents/run.py +++ b/src/agents/run.py @@ -8,7 +8,7 @@ from openai.types.responses import ( ResponseCompletedEvent, - ResponseOutputItemAddedEvent, + ResponseOutputItemDoneEvent, ) from openai.types.responses.response_prompt_param import ( ResponsePromptParam, @@ -1040,7 +1040,7 @@ async def _run_single_turn_streamed( ) context_wrapper.usage.add(usage) - if isinstance(event, ResponseOutputItemAddedEvent): + if isinstance(event, ResponseOutputItemDoneEvent): output_item = event.item if isinstance(output_item, _TOOL_CALL_TYPES): diff --git a/src/agents/tool.py b/src/agents/tool.py index 4624fbb52..04534bd04 100644 --- a/src/agents/tool.py +++ b/src/agents/tool.py @@ -12,8 +12,8 @@ ResponseComputerToolCall, ) from openai.types.responses.response_output_item import LocalShellCall, McpApprovalRequest -from openai.types.responses.tool import WebSearchToolFilters from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp +from openai.types.responses.web_search_tool import Filters as WebSearchToolFilters from openai.types.responses.web_search_tool_param import UserLocation from pydantic import ValidationError from typing_extensions import Concatenate, NotRequired, ParamSpec, TypedDict diff --git a/tests/realtime/test_openai_realtime.py b/tests/realtime/test_openai_realtime.py index 4c410bf6e..08b8d878f 100644 --- a/tests/realtime/test_openai_realtime.py +++ b/tests/realtime/test_openai_realtime.py @@ -84,8 +84,45 @@ def mock_create_task_func(coro): # Verify internal state assert model._websocket == mock_websocket - assert model._websocket_task is not None - assert model.model == "gpt-4o-realtime-preview" + assert model._websocket_task is not None + assert model.model == "gpt-4o-realtime-preview" + + @pytest.mark.asyncio + async def test_connect_with_custom_headers_overrides_defaults(self, model, mock_websocket): + """If custom headers are provided, use them verbatim without adding defaults.""" + # Even when custom headers are provided, the implementation still requires api_key. + config = { + "api_key": "unused-because-headers-override", + "headers": {"api-key": "azure-key", "x-custom": "1"}, + "url": "wss://custom.example.com/realtime?model=custom", + # Use a valid realtime model name for session.update to validate. + "initial_model_settings": {"model_name": "gpt-4o-realtime-preview"}, + } + + async def async_websocket(*args, **kwargs): + return mock_websocket + + with patch("websockets.connect", side_effect=async_websocket) as mock_connect: + with patch("asyncio.create_task") as mock_create_task: + mock_task = AsyncMock() + + def mock_create_task_func(coro): + coro.close() + return mock_task + + mock_create_task.side_effect = mock_create_task_func + + await model.connect(config) + + # Verify WebSocket connection used the provided URL + called_url = mock_connect.call_args[0][0] + assert called_url == "wss://custom.example.com/realtime?model=custom" + + # Verify headers are exactly as provided and no defaults were injected + headers = mock_connect.call_args.kwargs["additional_headers"] + assert headers == {"api-key": "azure-key", "x-custom": "1"} + assert "Authorization" not in headers + assert "OpenAI-Beta" not in headers @pytest.mark.asyncio async def test_connect_with_callable_api_key(self, model, mock_websocket): diff --git a/tests/test_streaming_tool_call_arguments.py b/tests/test_streaming_tool_call_arguments.py new file mode 100644 index 000000000..ce476e59b --- /dev/null +++ b/tests/test_streaming_tool_call_arguments.py @@ -0,0 +1,373 @@ +""" +Tests to ensure that tool call arguments are properly populated in streaming events. + +This test specifically guards against the regression where tool_called events +were emitted with empty arguments during streaming (Issue #1629). +""" + +import json +from collections.abc import AsyncIterator +from typing import Any, Optional, Union, cast + +import pytest +from openai.types.responses import ( + ResponseCompletedEvent, + ResponseFunctionToolCall, + ResponseOutputItemAddedEvent, + ResponseOutputItemDoneEvent, +) + +from agents import Agent, Runner, function_tool +from agents.agent_output import AgentOutputSchemaBase +from agents.handoffs import Handoff +from agents.items import TResponseInputItem, TResponseOutputItem, TResponseStreamEvent +from agents.model_settings import ModelSettings +from agents.models.interface import Model, ModelTracing +from agents.stream_events import RunItemStreamEvent +from agents.tool import Tool +from agents.tracing import generation_span + +from .fake_model import get_response_obj +from .test_responses import get_function_tool_call + + +class StreamingFakeModel(Model): + """A fake model that actually emits streaming events to test our streaming fix.""" + + def __init__(self): + self.turn_outputs: list[list[TResponseOutputItem]] = [] + self.last_turn_args: dict[str, Any] = {} + + def set_next_output(self, output: list[TResponseOutputItem]): + self.turn_outputs.append(output) + + def get_next_output(self) -> list[TResponseOutputItem]: + if not self.turn_outputs: + return [] + return self.turn_outputs.pop(0) + + async def get_response( + self, + system_instructions: Optional[str], + input: Union[str, list[TResponseInputItem]], + model_settings: ModelSettings, + tools: list[Tool], + output_schema: Optional[AgentOutputSchemaBase], + handoffs: list[Handoff], + tracing: ModelTracing, + *, + previous_response_id: Optional[str], + conversation_id: Optional[str], + prompt: Optional[Any], + ): + raise NotImplementedError("Use stream_response instead") + + async def stream_response( + self, + system_instructions: Optional[str], + input: Union[str, list[TResponseInputItem]], + model_settings: ModelSettings, + tools: list[Tool], + output_schema: Optional[AgentOutputSchemaBase], + handoffs: list[Handoff], + tracing: ModelTracing, + *, + previous_response_id: Optional[str] = None, + conversation_id: Optional[str] = None, + prompt: Optional[Any] = None, + ) -> AsyncIterator[TResponseStreamEvent]: + """Stream events that simulate real OpenAI streaming behavior for tool calls.""" + self.last_turn_args = { + "system_instructions": system_instructions, + "input": input, + "model_settings": model_settings, + "tools": tools, + "output_schema": output_schema, + "previous_response_id": previous_response_id, + "conversation_id": conversation_id, + } + + with generation_span(disabled=True) as _: + output = self.get_next_output() + + sequence_number = 0 + + # Emit each output item with proper streaming events + for item in output: + if isinstance(item, ResponseFunctionToolCall): + # First: emit ResponseOutputItemAddedEvent with EMPTY arguments + # (this simulates the real streaming behavior that was causing the bug) + empty_args_item = ResponseFunctionToolCall( + id=item.id, + call_id=item.call_id, + type=item.type, + name=item.name, + arguments="", # EMPTY - this is the bug condition! + ) + + yield ResponseOutputItemAddedEvent( + item=empty_args_item, + output_index=0, + type="response.output_item.added", + sequence_number=sequence_number, + ) + sequence_number += 1 + + # Then: emit ResponseOutputItemDoneEvent with COMPLETE arguments + yield ResponseOutputItemDoneEvent( + item=item, # This has the complete arguments + output_index=0, + type="response.output_item.done", + sequence_number=sequence_number, + ) + sequence_number += 1 + + # Finally: emit completion + yield ResponseCompletedEvent( + type="response.completed", + response=get_response_obj(output), + sequence_number=sequence_number, + ) + + +@function_tool +def calculate_sum(a: int, b: int) -> str: + """Add two numbers together.""" + return str(a + b) + + +@function_tool +def format_message(name: str, message: str, urgent: bool = False) -> str: + """Format a message with name and urgency.""" + prefix = "URGENT: " if urgent else "" + return f"{prefix}Hello {name}, {message}" + + +@pytest.mark.asyncio +async def test_streaming_tool_call_arguments_not_empty(): + """Test that tool_called events contain non-empty arguments during streaming.""" + model = StreamingFakeModel() + agent = Agent( + name="TestAgent", + model=model, + tools=[calculate_sum], + ) + + # Set up a tool call with arguments + expected_arguments = '{"a": 5, "b": 3}' + model.set_next_output( + [ + get_function_tool_call("calculate_sum", expected_arguments, "call_123"), + ] + ) + + result = Runner.run_streamed(agent, input="Add 5 and 3") + + tool_called_events = [] + async for event in result.stream_events(): + if ( + event.type == "run_item_stream_event" + and isinstance(event, RunItemStreamEvent) + and event.name == "tool_called" + ): + tool_called_events.append(event) + + # Verify we got exactly one tool_called event + assert len(tool_called_events) == 1, ( + f"Expected 1 tool_called event, got {len(tool_called_events)}" + ) + + tool_event = tool_called_events[0] + + # Verify the event has the expected structure + assert hasattr(tool_event.item, "raw_item"), "tool_called event should have raw_item" + assert hasattr(tool_event.item.raw_item, "arguments"), "raw_item should have arguments field" + + # The critical test: arguments should NOT be empty + # Cast to ResponseFunctionToolCall since we know that's what it is in our test + raw_item = cast(ResponseFunctionToolCall, tool_event.item.raw_item) + actual_arguments = raw_item.arguments + assert actual_arguments != "", ( + f"Tool call arguments should not be empty, got: '{actual_arguments}'" + ) + assert actual_arguments is not None, "Tool call arguments should not be None" + + # Verify arguments contain the expected data + assert actual_arguments == expected_arguments, ( + f"Expected arguments '{expected_arguments}', got '{actual_arguments}'" + ) + + # Verify arguments are valid JSON that can be parsed + try: + parsed_args = json.loads(actual_arguments) + assert parsed_args == {"a": 5, "b": 3}, ( + f"Parsed arguments should match expected values, got {parsed_args}" + ) + except json.JSONDecodeError as e: + pytest.fail( + f"Tool call arguments should be valid JSON, but got: '{actual_arguments}' with error: {e}" # noqa: E501 + ) + + +@pytest.mark.asyncio +async def test_streaming_tool_call_arguments_complex(): + """Test streaming tool calls with complex arguments including strings and booleans.""" + model = StreamingFakeModel() + agent = Agent( + name="TestAgent", + model=model, + tools=[format_message], + ) + + # Set up a tool call with complex arguments + expected_arguments = ( + '{"name": "Alice", "message": "Your meeting is starting soon", "urgent": true}' + ) + model.set_next_output( + [ + get_function_tool_call("format_message", expected_arguments, "call_456"), + ] + ) + + result = Runner.run_streamed(agent, input="Format a message for Alice") + + tool_called_events = [] + async for event in result.stream_events(): + if ( + event.type == "run_item_stream_event" + and isinstance(event, RunItemStreamEvent) + and event.name == "tool_called" + ): + tool_called_events.append(event) + + assert len(tool_called_events) == 1, ( + f"Expected 1 tool_called event, got {len(tool_called_events)}" + ) + + tool_event = tool_called_events[0] + # Cast to ResponseFunctionToolCall since we know that's what it is in our test + raw_item = cast(ResponseFunctionToolCall, tool_event.item.raw_item) + actual_arguments = raw_item.arguments + + # Critical checks for the regression + assert actual_arguments != "", "Tool call arguments should not be empty" + assert actual_arguments is not None, "Tool call arguments should not be None" + assert actual_arguments == expected_arguments, ( + f"Expected '{expected_arguments}', got '{actual_arguments}'" + ) + + # Verify the complex arguments parse correctly + parsed_args = json.loads(actual_arguments) + expected_parsed = {"name": "Alice", "message": "Your meeting is starting soon", "urgent": True} + assert parsed_args == expected_parsed, f"Parsed arguments should match, got {parsed_args}" + + +@pytest.mark.asyncio +async def test_streaming_multiple_tool_calls_arguments(): + """Test that multiple tool calls in streaming all have proper arguments.""" + model = StreamingFakeModel() + agent = Agent( + name="TestAgent", + model=model, + tools=[calculate_sum, format_message], + ) + + # Set up multiple tool calls + model.set_next_output( + [ + get_function_tool_call("calculate_sum", '{"a": 10, "b": 20}', "call_1"), + get_function_tool_call( + "format_message", '{"name": "Bob", "message": "Test"}', "call_2" + ), + ] + ) + + result = Runner.run_streamed(agent, input="Do some calculations") + + tool_called_events = [] + async for event in result.stream_events(): + if ( + event.type == "run_item_stream_event" + and isinstance(event, RunItemStreamEvent) + and event.name == "tool_called" + ): + tool_called_events.append(event) + + # Should have exactly 2 tool_called events + assert len(tool_called_events) == 2, ( + f"Expected 2 tool_called events, got {len(tool_called_events)}" + ) + + # Check first tool call + event1 = tool_called_events[0] + # Cast to ResponseFunctionToolCall since we know that's what it is in our test + raw_item1 = cast(ResponseFunctionToolCall, event1.item.raw_item) + args1 = raw_item1.arguments + assert args1 != "", "First tool call arguments should not be empty" + expected_args1 = '{"a": 10, "b": 20}' + assert args1 == expected_args1, ( + f"First tool call args: expected '{expected_args1}', got '{args1}'" + ) + + # Check second tool call + event2 = tool_called_events[1] + # Cast to ResponseFunctionToolCall since we know that's what it is in our test + raw_item2 = cast(ResponseFunctionToolCall, event2.item.raw_item) + args2 = raw_item2.arguments + assert args2 != "", "Second tool call arguments should not be empty" + expected_args2 = '{"name": "Bob", "message": "Test"}' + assert args2 == expected_args2, ( + f"Second tool call args: expected '{expected_args2}', got '{args2}'" + ) + + +@pytest.mark.asyncio +async def test_streaming_tool_call_with_empty_arguments(): + """Test that tool calls with legitimately empty arguments still work correctly.""" + model = StreamingFakeModel() + + @function_tool + def get_current_time() -> str: + """Get the current time (no arguments needed).""" + return "2024-01-15 10:30:00" + + agent = Agent( + name="TestAgent", + model=model, + tools=[get_current_time], + ) + + # Tool call with empty arguments (legitimate case) + model.set_next_output( + [ + get_function_tool_call("get_current_time", "{}", "call_time"), + ] + ) + + result = Runner.run_streamed(agent, input="What time is it?") + + tool_called_events = [] + async for event in result.stream_events(): + if ( + event.type == "run_item_stream_event" + and isinstance(event, RunItemStreamEvent) + and event.name == "tool_called" + ): + tool_called_events.append(event) + + assert len(tool_called_events) == 1, ( + f"Expected 1 tool_called event, got {len(tool_called_events)}" + ) + + tool_event = tool_called_events[0] + # Cast to ResponseFunctionToolCall since we know that's what it is in our test + raw_item = cast(ResponseFunctionToolCall, tool_event.item.raw_item) + actual_arguments = raw_item.arguments + + # Even "empty" arguments should be "{}", not literally empty string + assert actual_arguments is not None, "Arguments should not be None" + assert actual_arguments == "{}", f"Expected empty JSON object '{{}}', got '{actual_arguments}'" + + # Should parse as valid empty JSON + parsed_args = json.loads(actual_arguments) + assert parsed_args == {}, f"Should parse to empty dict, got {parsed_args}" diff --git a/uv.lock b/uv.lock index 12a50a794..a936b74db 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 2 +revision = 3 requires-python = ">=3.9" resolution-markers = [ "python_full_version >= '3.11'", @@ -1797,7 +1797,7 @@ wheels = [ [[package]] name = "openai" -version = "1.102.0" +version = "1.104.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -1809,9 +1809,9 @@ dependencies = [ { name = "tqdm" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/07/55/da5598ed5c6bdd9939633854049cddc5cbac0da938dfcfcb3c6b119c16c0/openai-1.102.0.tar.gz", hash = "sha256:2e0153bcd64a6523071e90211cbfca1f2bbc5ceedd0993ba932a5869f93b7fc9", size = 519027, upload-time = "2025-08-26T20:50:29.397Z" } +sdist = { url = "https://files.pythonhosted.org/packages/47/55/7e0242a7db611ad4a091a98ca458834b010639e94e84faca95741ded4050/openai-1.104.1.tar.gz", hash = "sha256:8b234ada6f720fa82859fb7dcecf853f8ddf3892c3038c81a9cc08bcb4cd8d86", size = 557053, upload-time = "2025-09-02T19:59:37.818Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/bd/0d/c9e7016d82c53c5b5e23e2bad36daebb8921ed44f69c0a985c6529a35106/openai-1.102.0-py3-none-any.whl", hash = "sha256:d751a7e95e222b5325306362ad02a7aa96e1fab3ed05b5888ce1c7ca63451345", size = 812015, upload-time = "2025-08-26T20:50:27.219Z" }, + { url = "https://files.pythonhosted.org/packages/64/de/af0eefab4400d2c888cea4f9b929bd5208d98aa7619c38b93554b0699d60/openai-1.104.1-py3-none-any.whl", hash = "sha256:153f2e9c60d4c8bb90f2f3ef03b6433b3c186ee9497c088d323028f777760af4", size = 928094, upload-time = "2025-09-02T19:59:36.155Z" }, ] [[package]] @@ -1882,7 +1882,7 @@ requires-dist = [ { name = "litellm", marker = "extra == 'litellm'", specifier = ">=1.67.4.post1,<2" }, { name = "mcp", marker = "python_full_version >= '3.10'", specifier = ">=1.11.0,<2" }, { name = "numpy", marker = "python_full_version >= '3.10' and extra == 'voice'", specifier = ">=2.2.0,<3" }, - { name = "openai", specifier = ">=1.102.0,<2" }, + { name = "openai", specifier = ">=1.104.1,<2" }, { name = "pydantic", specifier = ">=2.10,<3" }, { name = "requests", specifier = ">=2.0,<3" }, { name = "sqlalchemy", marker = "extra == 'sqlalchemy'", specifier = ">=2.0" },