diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 34e2a30d5..42d295e77 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは、instructions と tools を設定した 大規模言語モデル ( LLM ) です。 +エージェント はアプリのコアとなるビルディングブロックです。エージェント は大規模言語モデル（ LLM ）で、 instructions とツールで構成します。 -## 基本設定 +## 基本構成 -一般的に設定するエージェントの主要プロパティは次のとおりです: +エージェント で最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer message または system prompt とも呼ばれます。 -- `model`: 使用する LLM と、temperature、top_p などのモデル調整用の任意の `model_settings`。 -- `tools`: エージェントがタスクを達成するために使用できるツール。 +- `name`: エージェント を識別する必須の文字列です。 +- `instructions`: developer メッセージ、または system prompt とも呼ばれます。 +- `model`: 使用する LLM と、 temperature、 top_p などのモデル調整パラメーターを設定する任意の `model_settings`。 +- `tools`: エージェント がタスクを達成するために使用できるツール。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型に対してジェネリックです。コンテキストは依存性注入の手段です。`Runner.run()` に渡すために作成するオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態の詰め合わせとして機能します。コンテキストには任意の Python オブジェクトを提供できます。 +エージェント はその `context` 型に対してジェネリックです。コンテキストは依存性注入ツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフ などに渡され、エージェント の実行に必要な依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを提供できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) の出力を生成します。特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトの使用ですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型 (dataclasses、リスト、TypedDict など) をサポートします。 +デフォルトでは、エージェント はプレーンテキスト（すなわち `str`）を出力します。特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使いますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型（dataclasses、lists、TypedDict など）をサポートします。 ```python from pydantic import BaseModel @@ -73,20 +73,20 @@ agent = Agent( !!! note - `output_type` を渡すと、通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようモデルに指示します。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 -## マルチエージェントの設計パターン +## マルチ エージェント システムの設計パターン -マルチエージェント システムを設計する方法は多様ですが、一般的に広く適用できるパターンが 2 つあります: +マルチ エージェント システムの設計方法は多数ありますが、一般的に広く適用できるパターンを 2 つ挙げます。 -1. マネージャー (ツールとしての エージェント): 中央のマネージャー/オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を保持します。 -2. ハンドオフ: ピアのエージェントが、会話を引き継ぐ専門のエージェントに制御をハンドオフします。これは分散型です。 +1. マネージャー（エージェント をツールとして使用）: 中央のマネージャー/オーケストレーターが、専用のサブ エージェント をツールとして呼び出し、会話の制御を保持します。 +2. ハンドオフ: ピア エージェント が制御を、会話を引き継ぐ特化型エージェント にハンドオフします。こちらは分散型です。 -詳細は [実践的なエージェント構築ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) を参照してください。 +詳細は [エージェント 構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) をご覧ください。 -### マネージャー (ツールとしての エージェント) +### マネージャー（エージェント をツールとして使用） -`customer_facing_agent` がすべての ユーザー 対応を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳しくは [tools](tools.md#agents-as-tools) ドキュメントを参照してください。 +`customer_facing_agent` がすべてのユーザー とのやり取りを処理し、ツールとして公開された専用のサブ エージェント を呼び出します。詳しくは [ツール](tools.md#agents-as-tools) ドキュメントをご覧ください。 ```python from agents import Agent @@ -115,7 +115,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフが発生すると、委譲先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに特化して卓越する、モジュール型の専門エージェントが可能になります。詳しくは [handoffs](handoffs.md) ドキュメントを参照してください。 +ハンドオフ は、エージェント が委譲できるサブ エージェント です。ハンドオフ が発生すると、委譲先のエージェント は会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに特化して優れた性能を発揮する、モジュール式のエージェント を実現できます。詳しくは [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェントの作成時に instructions を指定できますが、関数を通じて動的な instructions を提供することもできます。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が利用できます。 +多くの場合、エージェント を作成する際に instructions を指定します。ただし、関数を介して動的な instructions を提供することもできます。関数はエージェント とコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を受け付けます。 ```python def dynamic_instructions( @@ -151,17 +151,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (フック) +## ライフサイクルイベント（フック） -エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりしたい場合です。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +場合によっては、エージェント のライフサイクルを観測したいことがあります。例えば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりする場合です。`hooks` プロパティでエージェント のライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドを override してください。 ## ガードレール -ガードレールを使うと、エージェントの実行と並行して ユーザー 入力に対するチェック/検証を実行でき、エージェントの出力が生成された後にも同様に実施できます。たとえば、 ユーザー の入力とエージェントの出力を関連性でスクリーニングできます。詳しくは [guardrails](guardrails.md) ドキュメントを参照してください。 +ガードレール は、エージェント の実行と並行してユーザー 入力に対するチェック/検証を行い、またエージェント の出力が生成された後にも実行できます。例えば、ユーザー の入力やエージェント の出力の関連性をスクリーニングできます。詳しくは [ガードレール](guardrails.md) ドキュメントをご覧ください。 ## エージェントのクローン/コピー -エージェントの `clone()` メソッドを使うと、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 +エージェント の `clone()` メソッドを使うと、エージェント を複製し、任意で好きなプロパティを変更できます。 ```python pirate_agent = Agent( @@ -178,12 +178,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを提供しても、LLM が必ずツールを使うとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです: +ツールのリストを指定しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、ツール使用を強制できます。有効な値は次のとおりです。 -1. `auto`: ツールを使うかどうかを LLM に委ねます。 -2. `required`: LLM にツールの使用を必須にします (ただし、どのツールかは賢く判断できます)。 -3. `none`: LLM にツールを使用「しない」ことを必須にします。 -4. 特定の文字列 (例: `my_tool`) を設定すると、その特定のツールを LLM に使用させます。 +1. `auto`: LLM にツールを使用するかどうかの判断を任せます。 +2. `required`: LLM にツールの使用を要求します（ただし、どのツールかは賢く判断できます）。 +3. `none`: LLM にツールを _使用しない_ ことを要求します。 +4. 具体的な文字列（例: `my_tool`）を設定すると、LLM にその特定のツールを使用することを要求します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -201,12 +201,12 @@ agent = Agent( ) ``` -## ツール使用の動作 +## ツール使用時の挙動 -`Agent` 構成の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します: +`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 -- `"run_llm_again"`: デフォルト。ツールを実行し、LLM が結果を処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしに最終応答として使用します。 +- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 +- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、その後の LLM による処理は行いません。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -224,7 +224,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool @@ -248,7 +248,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM 継続かを判断するカスタム関数。 +- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを決定するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -286,4 +286,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、その `tool_choice` により LLM がさらに別のツール呼び出しを生成し続けるために発生します。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で構成できます。無限ループは、ツール結果が LLM に送られ、`tool_choice` により LLM がさらに別のツール呼び出しを生成し続けることで起こります。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index cb262739c..0d64ee986 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 は環境変数または上記で設定したデフォルトキーを使って `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 を使用します。 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API を使用するように上書きできます。 +最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使うには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングは既定で有効になっています。既定では上記の OpenAI API キー（つまり環境変数または設定した既定のキー）を使用します。トレーシングに使用する API キーを個別に設定するには、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 +トレーシングはデフォルトで有効です。デフォルトでは、上記セクションの OpenAI API キー（すなわち、環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使うと、トレーシングを完全に無効化できます。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用すると、トレーシングを完全に無効化することもできます。 ```python from agents import set_tracing_disabled @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## デバッグログ -SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。既定では、警告とエラーは `stdout` に送られ、それ以外のログは抑制されます。 +SDK にはハンドラが設定されていない 2 つの Python ロガーがあります。デフォルトでは、警告とエラーは `stdout` に送られ、それ以外のログは抑制されます。 -冗長なログ出力を有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログを有効化するには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -あるいは、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +または、ハンドラ、フィルタ、フォーマッタなどを追加してログをカスタマイズできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html)をご覧ください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機微なデータ +### ログの機微情報 -一部のログには機微なデータ（例：ユーザー データ）が含まれる場合があります。これらのデータを記録しないようにするには、以下の環境変数を設定してください。 +一部のログには機微情報（たとえば ユーザー データ）が含まれる場合があります。これらのデータがログに出力されないようにするには、次の環境変数を設定します。 -LLM の入力と出力のログ記録を無効にするには: +LLM の入力と出力のログ出力を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のログ記録を無効にするには: +ツールの入力と出力のログ出力を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 42d1692f6..97b94eed9 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 オブジェクトを使います。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 2. そのオブジェクトを各種の実行メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 -3. すべてのツール呼び出し、ライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` からアクセスできます。 +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 を使用していますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツール実装はコンテキストから読み取ります。 -3. 型チェッカーでエラーを検出できるよう、エージェントにジェネリック `UserInfo` を付与します（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 -4. コンテキストは `run` 関数に渡されます。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装はコンテキストから読み取ります。 +3. エージェントにジェネリクス `UserInfo` を付け、型チェッカーがエラーを検出できるようにします（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合）。 +4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM のコンテキスト +## エージェント/LLM コンテキスト -LLM が呼び出されるとき、LLM が参照できる **唯一の** データは会話履歴からのものです。したがって、新しいデータを LLM に利用可能にしたい場合、その履歴で参照できる形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されると、参照できるデータは会話履歴のみです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できる形にする必要があります。主な方法は次のとおりです。 -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でもかまいません。これは常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 -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 +1. Agent の `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. リトリーバル (retrieval) または Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）や Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 2c32aa139..ecdfb9876 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,44 +4,44 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples)の examples セクションで、SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +[リポジトリ](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):** - このカテゴリーのコード例は、一般的な エージェント の設計パターンを示します。例: +- **[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 の基礎的な機能を紹介します。例: +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + これらの例は、SDK の基礎的な機能を紹介します。たとえば - - 動的な system prompt + - 動的なシステムプロンプト - ストリーミング出力 - ライフサイクルイベント -- **[ツールのコード例 (tool examples)](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツールの実装方法と、それらを エージェント に統合する方法を学べます。 +- **[ツールのコード例](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + Web 検索やファイル検索などの OpenAI がホストするツールの実装方法を学び、エージェントに統合する方法を確認できます。 -- **[モデルプロバイダー (model providers)](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - SDK で OpenAI 以外のモデルを使用する方法を探ります。 +- **[モデルプロバイダー](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK と併用する方法を学びます。 -- **[ハンドオフ (handoffs)](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェント の ハンドオフ の実用的なコード例をご覧ください。 +- **[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**: シンプルな ディープリサーチ クローン。 + - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 + - **research_bot**: シンプルなディープリサーチ クローン。 -- **[音声 (voice)](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 当社の TTS と STT モデルを用いた音声 エージェント のコード例をご覧ください。 +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + TTS と STT モデルを用いた音声エージェントのコード例。 -- **[リアルタイム (realtime)](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイムな体験を構築するコード例です。 \ No newline at end of file +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使ってリアルタイムな体験を構築するコード例。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index a1435a9f4..564c493d6 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並行_ して動作し、ユーザー入力のチェックやバリデーションを行います。たとえば、顧客からのリクエストに対応するために、非常に賢い（そのため遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を手伝わせるようなことは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意のある使用を検知した場合は、即座にエラーを送出して高価なモデルの実行を止め、時間やコストを節約できます。 +ガードレールは エージェント と _並行して_ 実行され、ユーザー入力のチェックや検証を行います。例えば、顧客からのリクエスト対応に非常に賢い（ゆえに遅く/高価な）モデルを使うエージェントがあるとします。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるような指示を出すことは避けたいはずです。そのため、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意ある使用を検知した場合、即座にエラーを送出して高価なモデルの実行を停止し、時間やコストを節約できます。 ガードレールには 2 種類あります: -1. 入力ガードレールは最初のユーザー入力に対して実行されます +1. 入力ガードレールは初期のユーザー入力に対して実行されます 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] 例外が送出されるため、ユーザーへの適切な応答や例外処理が行えます。 +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] 例外が送出されるため、ユーザーへの適切な応答や例外処理が行えます。 +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 @@ -97,7 +97,7 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 3. ガードレール結果に追加情報を含めることができます。 -4. これがワークフローを定義する実際のエージェントです。 +4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -155,4 +155,4 @@ async def main(): 1. これは実際のエージェントの出力型です。 2. これはガードレールの出力型です。 3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. これがワークフローを定義する実際のエージェントです。 \ No newline at end of file +4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 782994952..50089a85c 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # ハンドオフ -ハンドオフは、あるエージェントが別のエージェントにタスクを委譲できるようにします。これは、異なるエージェントがそれぞれ異なる分野を専門としているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専任で担当するエージェントがいるかもしれません。 +ハンドオフは、あるエージェントが別のエージェントにタスクを委譲するための仕組みです。これは、異なるエージェントがそれぞれ別の分野を専門にしているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に担当するエージェントが存在するかもしれません。 -ハンドオフは LLM に対してツールとして表現されます。たとえば、`Refund Agent` という名前のエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM からはツールとして表現されます。たとえば `Refund Agent` というエージェントにハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは、[`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、`Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、`Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き渡し先のエージェントに加えて、オプションの上書き設定や入力フィルターを指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加えて、任意のオーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -シンプルなハンドオフの作り方は次のとおりです。 +次のようにシンプルなハンドオフを作成できます。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェント（例: `billing_agent`）を直接使うことも、`handoff()` 関数を使うこともできます。 +1. エージェントを直接使用しても（`billing_agent` のように）、`handoff()` 関数を使ってもかまいません。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数で各種のカスタマイズが可能です。 -- `agent`: 引き渡し先のエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使われ、`transfer_to_` に解決されます。これを上書きできます。 +- `agent`: ハンドオフ先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使われ、`transfer_to_` に解決されます。これを上書きできます。 - `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されると分かった時点でのデータ取得の開始などに有用です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフが想定する入力の型（任意）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうか。真偽値、または真偽値を返す関数を指定でき、実行時にハンドオフの有効・無効を動的に切り替えられます。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが実行されると分かった時点でデータ取得を開始するなどに便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで想定される入力の型（任意）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。 +- `is_enabled`: ハンドオフを有効にするかどうか。ブール値またはブール値を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## ハンドオフ入力 -状況によっては、ハンドオフを呼び出す際に LLM にいくつかのデータを提供させたい場合があります。たとえば、「エスカレーション エージェント」へのハンドオフを想像してください。ログのために理由を提供してもらいたいかもしれません。 +状況によっては、ハンドオフ呼び出し時に LLM にデータを提供してほしい場合があります。たとえば、「 Escalation エージェント」へのハンドオフを考えてみてください。理由を提供してもらい、それを記録したいことがあるかもしれません。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を参照できるかのように扱われます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を参照できるかのように扱われます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。 -いくつかの一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +いくつかの一般的なパターン（たとえば履歴からすべてのツール呼び出しを取り除くなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. これにより、`FAQ agent` が呼び出されたときに、履歴からすべてのツールが自動的に削除されます。 +1. これは、`FAQ agent` が呼び出されたときに履歴から自動的にすべてのツールを削除します。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることをおすすめします。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して推奨データをプロンプトに自動追加できます。 +LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることをおすすめします。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨情報を自動的に追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 00c3be2ba..aeb486026 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 と tools を備えた LLM -- **ハンドオフ**: 特定のタスクを他の エージェント に委譲できる機能 -- **ガードレール**: エージェントの入力と出力の検証を可能にします -- **セッション**: エージェントの実行にまたがる会話履歴を自動で保持します +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できる機能 +- **ガードレール**: エージェントの入力と出力の検証を可能にする機能 +- **セッション**: エージェントの実行をまたいで会話履歴を自動的に保持する機能 -Python と組み合わせることで、これらの基本的なコンポーネントはツールと エージェント の複雑な関係を表現でき、学習コストを抑えつつ実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグできるほか、評価やアプリケーション向けのモデルのファインチューニングにも活用できます。 +これらの基本コンポーネントは、 Python と組み合わせることでツールとエージェント間の複雑な関係性を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、 SDK には組み込みの **トレーシング** があり、エージェントフローの可視化とデバッグ、評価や、アプリケーション向けのモデルの微調整まで行えます。 ## Agents SDK を使う理由 -SDK の設計原則は次の 2 つです: +この SDK には 2 つの設計原則があります: -1. 使う価値があるだけの機能は備えつつ、基本的なコンポーネントは少なく、すぐに学べること。 -2. そのままでも十分に使え、必要に応じて挙動をきめ細かくカスタマイズできること。 +1. 使う価値があるだけの機能は備えつつ、学習を素早くするために基本コンポーネントは最小限にする。 +2. すぐに高品質に動作する一方で、挙動を細部までカスタマイズできる。 -SDK の主な機能は次のとおりです: +主な機能は次のとおりです: -- エージェントループ: ツールの呼び出し、結果を LLM に送信、LLM が完了するまでのループを処理する組み込みのエージェントループ。 -- Python ファースト: 新しい抽象を学ぶ必要はなく、言語の組み込み機能で エージェント をオーケストレーションし連携できます。 -- ハンドオフ: 複数の エージェント を協調・委譲させる強力な機能。 -- ガードレール: エージェント と並行して入力の検証やチェックを実行し、失敗時は早期に中断します。 -- セッション: エージェントの実行にまたがる会話履歴を自動管理し、手動での状態管理を不要にします。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic による検証を提供します。 -- トレーシング: ワークフローの可視化、デバッグ、監視を可能にする組み込みのトレーシング。さらに OpenAI の評価、ファインチューニング、蒸留ツール群を活用できます。 +- エージェントループ: ツールの呼び出し、実行結果を LLM に渡す処理、 LLM の完了までのループを扱う組み込みのループ。 +- Python ファースト: 新しい抽象を学ぶ必要はなく、言語の標準機能でエージェントのオーケストレーションや連携が可能。 +- ハンドオフ: 複数のエージェント間で調整と委譲を行う強力な機能。 +- ガードレール: 入力の検証やチェックをエージェントと並行して実行し、失敗した場合は早期に中断。 +- セッション: エージェント実行間で会話履歴を自動管理し、手動での状態管理を不要に。 +- 関数ツール: 任意の Python 関数をツール化し、スキーマを自動生成。 Pydantic による検証も備える。 +- トレーシング: ワークフローの可視化・デバッグ・監視ができ、 OpenAI の評価、微調整、蒸留ツールのスイートも活用可能。 ## インストール @@ -36,7 +36,7 @@ SDK の主な機能は次のとおりです: pip install openai-agents ``` -## Hello World の例 +## Hello World 例 ```python from agents import Agent, Runner diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index c55594de7..ba04d9600 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,34 +4,34 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルへ公開する方法を標準化します。公式ドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: > 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 Python SDK は複数の MCP トランスポートを理解します。これにより既存の MCP サーバーを再利用したり、独自の MCP サーバーを構築して、ファイルシステムや HTTP、コネクタを基盤とするツールを エージェント に公開できます。 +Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、独自に構築して、ファイルシステム、HTTP、またはコネクタ連携のツールを エージェント に提供できます。 -## MCP 統合の選択 +## Choosing an MCP integration -MCP サーバーを エージェント に接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは Python SDK がサポートするオプションをまとめたものです。 +MCP サーバーを エージェント に組み込む前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションの概要です。 -| What you need | Recommended option | +| 必要なこと | 推奨オプション | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| Let OpenAI's Responses API call a publicly reachable MCP server on the model's behalf| **Hosted MCP server tools** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | -| Connect to Streamable HTTP servers that you run locally or remotely | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | -| Talk to servers that implement HTTP with Server-Sent Events | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | -| Launch a local process and communicate over stdin/stdout | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | +| モデルに代わって OpenAI の Responses API がパブリック到達可能な MCP サーバーを呼び出す | **ホスト型 MCP サーバーのツール** を [`HostedMCPTool`][agents.tool.HostedMCPTool] 経由で | +| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | **Streamable HTTP MCP サーバー** を [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 経由で | +| Server-Sent Events を実装した HTTP サーバーと通信する | **HTTP with SSE MCP サーバー** を [`MCPServerSse`][agents.mcp.server.MCPServerSse] 経由で | +| ローカル プロセスを起動し stdin/stdout で通信する | **stdio MCP サーバー** を [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 経由で | -以下のセクションでは、それぞれのオプション、設定方法、およびどのトランスポートを選ぶべきかを説明します。 +以下のセクションでは、それぞれのオプションについて、設定方法と、どのトランスポートを選ぶべきかを説明します。 ## 1. Hosted MCP server tools -Hosted ツールは、ツールのラウンドトリップ全体を OpenAI のインフラストラクチャ内で実行します。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバー ラベル（および任意のコネクタ メタデータ）を Responses API に転送します。モデルはリモート サーバー のツールを列挙し、あなたの Python プロセスへの追加のコールバックなしでそれらを呼び出します。Hosted ツールは現在、Responses API の hosted MCP 統合をサポートする OpenAI モデルで動作します。 +ホスト型ツールでは、ツールの往復処理全体を OpenAI のインフラに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバー ラベル（および任意のコネクタ メタデータ）を Responses API に転送します。モデルはリモート サーバーのツールを列挙し、あなたの Python プロセスへの追加のコールバックなしにそれらを呼び出します。ホスト型ツールは現在、Responses API の hosted MCP 連携をサポートする OpenAI モデルで動作します。 -### 基本の hosted MCP ツール +### Basic hosted MCP tool -エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` dict は、REST API に送信する JSON を反映します: +エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` の dict は、REST API に送る JSON をそのまま反映します: ```python import asyncio @@ -59,11 +59,11 @@ async def main() -> None: asyncio.run(main()) ``` -Hosted サーバー はツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 +ホストされたサーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 -### ストリーミング対応の hosted MCP 結果 +### Streaming hosted MCP results -Hosted ツールは 関数ツール と全く同じ方法で ストリーミング に対応します。`Runner.run_streamed` に `stream=True` を渡すことで、モデルがまだ実行中でも増分の MCP 出力を消費できます: +ホスト型ツールは、関数ツールとまったく同じ方法で結果の ストリーミング をサポートします。`Runner.run_streamed` に `stream=True` を渡すと、モデルがまだ動作中でも増分の MCP 出力を消費できます: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -73,9 +73,9 @@ async for event in result.stream_events(): print(result.final_output) ``` -### 任意の承認フロー +### Optional approval flows -サーバー が機密性の高い操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を要求できます。`tool_config` の `require_approval` を、単一のポリシー（`"always"`、`"never"`）またはツール名をポリシーにマッピングする dict で設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 +サーバーが機微な操作を行える場合、各ツール実行の前に人間またはプログラムによる承認を要求できます。`tool_config` の `require_approval` を、単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict で設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -103,11 +103,11 @@ agent = Agent( ) ``` -コールバックは同期・非同期のどちらでもよく、モデルが実行を継続するために承認データを必要とするたびに呼び出されます。 +コールバックは同期・非同期いずれでもよく、モデルが継続実行に必要な承認データを要するたびに呼び出されます。 -### コネクタを基盤とする hosted サーバー +### Connector-backed hosted servers -Hosted MCP は OpenAI コネクタにも対応します。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、hosted サーバー はコネクタのツールを公開します。 +ホスト型 MCP は OpenAI コネクタにも対応しています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホストされたサーバーがコネクタのツールを公開します。 ```python import os @@ -123,12 +123,12 @@ HostedMCPTool( ) ``` -ストリーミング、承認、コネクタを含む、完全に動作する hosted ツールのサンプルは +ストリーミング、承認、コネクタを含む完全なホスト型ツールのサンプルは [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 ## 2. Streamable HTTP MCP servers -ネットワーク接続を自分で管理したい場合は、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバー は、トランスポートを自分で制御したい場合や、低レイテンシを維持しつつ自分のインフラ内で サーバー を実行したい場合に最適です。 +ネットワーク接続を自分で管理したい場合は、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、レイテンシーを低く保ちつつ自分のインフラ内でサーバーを実行したい場合に最適です。 ```python import asyncio @@ -163,18 +163,23 @@ async def main() -> None: asyncio.run(main()) ``` -コンストラクターは追加オプションを受け付けます: +コンストラクタは追加オプションを受け付けます: - `client_session_timeout_seconds` は HTTP の読み取りタイムアウトを制御します。 - `use_structured_content` は、テキスト出力よりも `tool_result.structured_content` を優先するかどうかを切り替えます。 - `max_retry_attempts` と `retry_backoff_seconds_base` は、`list_tools()` と `call_tool()` に自動リトライを追加します。 -- `tool_filter` は一部のツールのみを公開できます（[ツールのフィルタリング](#tool-filtering) を参照）。 +- `tool_filter` により、公開するツールをサブセットに絞り込めます（[ツールのフィルタリング](#tool-filtering) を参照）。 ## 3. HTTP with SSE MCP servers -MCP サーバー が HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバー と同一です。 +MCP サーバーが HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 ```python + +from agents import Agent, Runner +from agents.model_settings import ModelSettings +from mcp import MCPServerSse + workspace_id = "demo-workspace" async with MCPServerSse( @@ -196,10 +201,12 @@ async with MCPServerSse( ## 4. stdio MCP servers -ローカルのサブプロセスとして実行される MCP サーバー には、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキストマネージャの終了時に自動的に閉じます。これは、迅速なプロトタイプや、サーバー がコマンドラインのエントリポイントのみを公開する場合に便利です。 +ローカルのサブプロセスとして動作する MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキスト マネージャの終了時に自動でクローズします。このオプションは、迅速なプロトタイプ作成や、サーバーがコマンドライン エントリ ポイントのみを公開している場合に便利です。 ```python from pathlib import Path +from agents import Agent, Runner +from agents.mcp import MCPServerStdio current_dir = Path(__file__).parent samples_dir = current_dir / "sample_files" @@ -220,11 +227,11 @@ async with MCPServerStdio( print(result.final_output) ``` -## ツールのフィルタリング +## Tool filtering -各 MCP サーバー はツール フィルターをサポートしており、エージェント が必要とする関数のみを公開できます。フィルタリングは、構築時または実行ごとに動的に行えます。 +各 MCP サーバーはツール フィルターをサポートしており、エージェント に必要な機能だけを公開できます。フィルタリングは、構築時にも、実行ごとに動的にも行えます。 -### 静的なツールのフィルタリング +### Static tool filtering [`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、簡単な許可/ブロック リストを設定します: @@ -244,11 +251,11 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後、残った集合からブロック対象のツールを削除します。 +`allowed_tool_names` と `blocked_tool_names` が両方指定された場合、SDK は最初に許可リストを適用し、その後、残りの集合からブロック対象のツールを除去します。 -### 動的なツールのフィルタリング +### Dynamic tool filtering -より込み入ったロジックが必要な場合は、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。呼び出し可能オブジェクトは同期または非同期でよく、ツールを公開すべきときに `True` を返します。 +より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。これは同期・非同期いずれでもよく、ツールを公開すべき場合に `True` を返します。 ```python from pathlib import Path @@ -272,16 +279,18 @@ async with MCPServerStdio( ... ``` -フィルターのコンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。 +フィルター コンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。 -## プロンプト +## Prompts -MCP サーバー は、エージェントの instructions を動的に生成する プロンプト も提供できます。プロンプトをサポートする サーバー は 2 つのメソッドを公開します: +MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 つのメソッドを公開します: - `list_prompts()` は利用可能なプロンプト テンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じて パラメーター を伴う具体的なプロンプトを取得します. +- `get_prompt(name, arguments)` は、必要に応じて パラメーター 付きで具体的なプロンプトを取得します。 ```python +from agents import Agent + prompt_result = await server.get_prompt( "generate_code_review_instructions", {"focus": "security vulnerabilities", "language": "python"}, @@ -295,21 +304,21 @@ agent = Agent( ) ``` -## キャッシュ +## Caching -各 エージェント 実行は、各 MCP サーバー に対して `list_tools()` を呼び出します。リモート サーバー は顕著なレイテンシをもたらす可能性があるため、すべての MCP サーバー クラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変化しないと確信できる場合にのみ `True` に設定してください。後で新しいリストを強制するには、サーバー インスタンスで `invalidate_tools_cache()` を呼び出します。 +各 エージェント 実行時に、すべての MCP サーバーに対して `list_tools()` が呼び出されます。リモート サーバーは顕著なレイテンシーをもたらす可能性があるため、すべての MCP サーバー クラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変わらないと確信できる場合にのみ、これを `True` に設定してください。後で新しいリストを強制するには、サーバー インスタンスで `invalidate_tools_cache()` を呼び出します。 -## トレーシング +## Tracing -[Tracing](./tracing.md) は MCP のアクティビティを自動的に取得します。内容は次のとおりです: +[Tracing](./tracing.md) は MCP のアクティビティを自動的に捕捉します。含まれるもの: -1. ツールを列挙するための MCP サーバー への呼び出し。 +1. ツールを列挙するための MCP サーバーへの呼び出し。 2. ツール呼び出しに関する MCP 関連情報。 -![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) +![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) -## 参考資料 +## Further reading -- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様および設計ガイド。 +- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様と設計ガイド。 - [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP のサンプル。 -- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む、完全な hosted MCP デモ。 \ No newline at end of file +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む完全なホスト型 MCP のデモ。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index b26d91d10..681c6b7b6 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 つの形でそのまま使えるサポートが付属しています。 -- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **推奨**: [`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 を呼び出します。 ## OpenAI モデル -`Agent` を初期化する際にモデルを指定しない場合、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント的なワークフローにおける予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化する際にモデルを指定しない場合は、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント型ワークフローにおける予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など別のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 -### デフォルトの OpenAI モデル +### 既定の OpenAI モデル -カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使いたい場合は、エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 +カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使用したい場合は、エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -GPT-5 の推論モデル（[`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 effort を調整するには、独自の `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 effort をサポートしていないため、この 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` を設定できるケースに該当します。設定可能なサンプルは [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` のレベルにあります。これにより、「この実行でのすべての エージェント に対してカスタムのモデルプロバイダーを使う」と指定できます。設定可能なサンプルは [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] は、特定の Agent インスタンスでモデルを指定できるようにします。これにより、エージェント ごとに異なるプロバイダーを組み合わせて使えます。簡単に多くのモデルを使うには、[LiteLLM との連携](./litellm.md)が便利です。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能なサンプルは [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより「この実行に含まれるすべての エージェント に対してカスタムのモデルプロバイダーを使う」と指定できます。設定可能なサンプルは [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] は特定の Agent インスタンス上でモデルを指定できます。これにより、エージェント ごとに異なるプロバイダーを組み合わせて使えます。簡単に多くのモデルを利用するには [LiteLLM 連携](./litellm.md)が便利です。 -`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` で トレーシング を無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することをおすすめします。 +`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` で トレーシング を無効化するか、[別の トレーシング プロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの code examples では、Responses API/モデルを LLM プロバイダーの多くがまだサポートしていないため、Chat Completions を使用しています。お使いの LLM プロバイダーがサポートしている場合は、Responses の使用をおすすめします。 + これらの例では、Responses API をサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。もしお使いの LLM プロバイダーが Responses をサポートしている場合は、Responses の使用をおすすめします。 ## モデルの組み合わせ -1 つのワークフローの中で、エージェント ごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使う、といった使い分けです。[`Agent`][agents.Agent] を構成する際は、次のいずれかの方法で特定のモデルを選べます: +1 つのワークフロー内で、エージェント ごとに異なるモデルを使用したい場合があります。例えば、振り分けには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使うといった形です。[`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] の両方の形に対応していますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは 1 つのモデル形に統一することをおすすめします。もしワークフロー上でモデル形を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしていますが、それぞれ対応する機能やツールの集合が異なるため、ワークフローごとに 1 つのモデル形に統一することをおすすめします。ワークフロー上でモデル形を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -125,7 +125,7 @@ async def main(): 1. OpenAI のモデル名を直接設定します。 2. [`Model`][agents.models.interface.Model] 実装を提供します。 -特定の エージェント で使用するモデルをさらに細かく設定したい場合は、`temperature` などの任意のモデル構成 パラメーター を提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェント で使用するモデルをさらに構成したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡すことで、temperature などの任意のモデル構成パラメーターを指定できます。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意 パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡せます。 +また、OpenAI の Responses API を使用する際には、[いくつかの追加の任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡すことができます。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー利用時の一般的な問題 +## 他社 LLM プロバイダー利用時の一般的な問題 ### トレーシング クライアントのエラー 401 -トレーシング に関連するエラーが発生する場合、これはトレースが OpenAI の サーバー にアップロードされる一方で、OpenAI の API キーをお持ちでないためです。解決策は次の 3 つです: +トレーシング に関連するエラーが発生する場合、トレースは OpenAI の サーバー にアップロードされ、OpenAI の API キーを持っていないことが原因です。解決するには次の 3 つの選択肢があります。 -1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング 用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -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 以外の trace プロセッサーを使用する。[tracing のドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだサポートしていません。その結果、404 などの問題が発生する場合があります。解決するには、次の 2 つの方法があります: +SDK は既定で Responses API を使用しますが、他の多くの LLM プロバイダーはまだ対応していません。その結果、404 などの問題が発生することがあります。解決するには次の 2 つの方法があります。 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 のサポート -一部のモデルプロバイダーは [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` を理解しないプロバイダーに送らない -- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングする -- structured な JSON 出力をサポートしていないプロバイダーは、無効な JSON を生成することがある点に注意する \ No newline at end of file +- 非対応のプロバイダーに対して、理解できない `tools` を送らないでください +- テキストのみ対応のモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください +- structured JSON 出力をサポートしていないプロバイダーでは、無効な JSON が生成されることがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index f556b8e36..cb8e3ee60 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,13 +2,13 @@ search: exclude: true --- -# LiteLLM 経由の任意モデル利用 +# LiteLLM を使用した任意モデルの利用 !!! note - LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub の issues](https://github.com/openai/openai-agents-python/issues) に報告してください。迅速に修正します。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) でご報告ください。迅速に対応します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 連携を追加しており、任意の AI モデルを利用できます。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、任意の AI モデルを使用できるようにしました。 ## セットアップ @@ -18,17 +18,17 @@ search: 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` をモデル名にし、OpenAI の API キー -- `anthropic/claude-3-5-sonnet-20240620` をモデル名にし、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 94b43ddbe..4fa9e63d4 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントをどの順番で実行し、次に何をするかをどのように決めるかということです。エージェントをオーケストレーションする主な方法は次の 2 つです。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを、どの順序で実行し、次に何を行うかをどう決めるか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定を任せる: LLM の知能を活用して計画・推論し、それに基づいて実行手順を決めます。 +1. LLM に意思決定させる: LLM の知性を用いて計画・推論し、それに基づいて実行手順を決定します。 2. コードでオーケストレーションする: コードでエージェントの流れを決定します。 -これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使えます。各方法には以下のようなトレードオフがあります。 ## LLM によるオーケストレーション -エージェントは、instructions、tools、ハンドオフ を備えた LLM です。つまり、オープンエンドなタスクが与えられた場合に、LLM はツールを使って行動しデータを取得し、ハンドオフでサブエージェントに委譲することで、タスクへの取り組み方を自律的に計画できます。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 +エージェントは、instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM は自律的にタスクへの取り組み方を計画し、ツールを用いて行動やデータ取得を行い、handoffs によってサブエージェントへタスクを委譲できます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 -- Web 検索でオンラインの情報を見つける -- ファイル検索 とリトリーバルで独自データや接続を横断的に検索する -- コンピュータ操作 でコンピュータ上のアクションを実行する -- コード実行 でデータ分析を行う -- 計画作成、レポート執筆などに長けた専門エージェントへの ハンドオフ +- Web 検索でオンライン情報を見つける +- ファイル検索と取得で社内データや接続を横断的に検索する +- コンピュータ操作 でコンピュータ上の行動を実行する +- コード実行でデータ分析を行う +- 計画やレポート作成などが得意な専門エージェントへの handoffs -このパターンは、タスクがオープンエンドで、LLM の知能に依拠したい場合に有効です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知性に依拠したい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーター を明確にします。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、そして動作すべきパラメーターを明確にします。 2. アプリを監視し、反復改善する。問題が起きる箇所を把握し、プロンプトを改善します。 3. エージェントに内省と改善を許可する。たとえばループで実行し、自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもできる汎用エージェントではなく、1 つのタスクに秀でた専門エージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスクの熟達度を高められます。 +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` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで繰り返す。 +- 複数のエージェントを並列実行する。例: `asyncio.gather` のような Python の基本コンポーネント を用いる。相互に依存しない複数のタスクがある場合、速度向上に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数の code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の例があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 65077b86c..aee9fa457 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ行えば大丈夫です。 +これは 1 回だけ実施すれば十分です。 ```bash mkdir my_project @@ -22,15 +22,15 @@ python -m venv .venv source .venv/bin/activate ``` -### Agents SDK のインストール +### Agents SDK のインストール ```bash 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)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[次の手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してエクスポートしてください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions、名前、任意のコンフィグ（例: `model_config`）で定義します。 +エージェントは instructions、名前、任意の設定（例: `model_config`）で定義します。 ```python from agents import Agent @@ -49,7 +49,7 @@ agent = Agent( ) ``` -## いくつかのエージェントの追加 +## エージェントの追加 追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 @@ -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 @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードのトレース ビューア](https://platform.openai.com/traces)でエージェント実行のトレースを確認してください。 +エージェント実行で何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェント フローの作り方を学びましょう: +より複雑なエージェント フローの構築方法を学びましょう: -- Learn about how to configure [エージェント](agents.md)。 -- Learn about [エージェントの実行](running_agents.md)。 -- Learn about [tools](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 3314755b3..e60f60622 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 "Beta feature" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装改善に伴い、互換性に影響する変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、会話フローを実現し、音声とテキストの入力をリアルタイムに処理し、リアルタイム音声で応答します。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話や、割り込みへの円滑な対応が可能です。 +Realtime エージェントは、会話のフローを可能にし、音声およびテキスト入力をリアルタイムに処理して、リアルタイム音声で応答します。OpenAI の Realtime API への永続接続を維持し、低遅延で自然な音声対話と、割り込みへの適切な対応を実現します。 ## アーキテクチャ ### コアコンポーネント -realtime システムは、いくつかの重要なコンポーネントで構成されています。 +realtime システムは、いくつかの主要なコンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。通常は ユーザー が会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出すとセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（一般的には OpenAI の WebSocket 実装） ### セッションフロー -一般的な realtime セッションは次のフローに従います。 +一般的な realtime セッションの流れは次のとおりです。 -1. instructions、tools、handoffs を指定して **RealtimeAgent を作成** します。 -2. エージェントと設定オプションを用いて **RealtimeRunner をセットアップ** します。 -3. `await runner.run()` を使って **セッションを開始** し、RealtimeSession を受け取ります。 -4. `send_audio()` または `send_message()` を使って **音声またはテキストメッセージを送信** します。 +1. instructions、tools、ハンドオフを指定して **RealtimeAgent を作成** します。 +2. エージェントと設定オプションを使って **RealtimeRunner を設定** します。 +3. `await runner.run()` を使って **セッションを開始** します。これにより RealtimeSession が返されます。 +4. `send_audio()` または `send_message()` を使用して **音声またはテキストメッセージを送信** します。 5. セッションを反復処理して **イベントを監視** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. ユーザー がエージェントに被せて話した際の **割り込み処理** に対応します。これにより現在の音声生成は自動的に停止します。 +6. ユーザーがエージェントの発話にかぶせて話した場合の **割り込みを処理** します。現在の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、realtime モデルとの永続的な接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は、通常の Agent クラスと類似して動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご確認ください。 +RealtimeAgent は、通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスを参照してください。 -通常のエージェントとの差分: +通常のエージェントとの主な違い: -- モデルの選択はエージェントレベルではなく、セッションレベルで設定します。 +- モデル選択はエージェントではなくセッションレベルで設定します。 - structured output はサポートされません（`outputType` は非対応）。 -- ボイスはエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- ツール、ハンドオフ、instructions などの他の機能は同様に動作します。 +- 声質はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- それ以外の機能（tools、ハンドオフ、instructions）は同様に動作します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-realtime`）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび/または音声）を構成できます。音声フォーマットは入力と出力の両方で設定でき、既定は PCM16 です。 +セッション設定では、基盤となる realtime モデルの挙動を制御できます。モデル名（`gpt-realtime` など）、声質の選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび／または音声）を設定できます。音声フォーマットは入力・出力の両方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定では、セッションが音声入出力をどのように扱うかを制御します。Whisper のようなモデルを用いた入力音声の文字起こし、言語設定、ドメイン特有の用語の精度を高めるための文字起こしプロンプトを構成できます。ターン検出設定では、エージェントがいつ応答を開始・停止するかを制御でき、音声活動検出のしきい値、無音時間、検出された発話の前後のパディングなどを設定できます。 +音声設定は、セッションが音声入力と出力をどのように処理するかを制御します。Whisper のようなモデルを用いた入力音声の文字起こし、言語設定、ドメイン固有用語の精度を高めるための文字起こしプロンプトを指定できます。発話区間検出（turn detection）の設定により、エージェントがいつ応答を開始・停止するかを制御でき、音声アクティビティ検出のしきい値、無音時間、検出された発話の前後パディングなどのオプションがあります。 ## ツールと関数 @@ -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_interrupted**: ユーザーがエージェントを割り込み - **tool_start/tool_end**: ツール実行のライフサイクル - **handoff**: エージェントのハンドオフが発生 - **error**: 処理中にエラーが発生 -イベントの詳細は、[`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +イベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -realtime エージェントでサポートされるのは出力 ガードレール のみです。これらの ガードレール はデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために（毎語ではなく）定期的に実行されます。既定のデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでサポートされるのは出力ガードレールのみです。性能問題を避けるため、これらのガードレールはデバウンスされ、リアルタイム生成中に毎語ではなく定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` 経由で提供できます。両方の経路から提供された ガードレール は合わせて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースからのガードレールは併用されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレール がトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキストエージェントと異なり、realtime エージェントは ガードレール が発火しても 例外 をスローしません。 +ガードレールが発動すると、`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 session.model.add_listener(my_custom_listener) ``` -これにより、接続を低レベルに制御する必要がある高度なユースケースに向けて、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、接続を低レベルで制御する必要がある高度なユースケースに向けて、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## 例 +## コード例 -完全に動作するサンプルは、UI コンポーネントの有無両方のデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご確認ください。 \ No newline at end of file +完全な動作サンプルは、UI コンポーネントあり・なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index fce5c94ab..dd3777dea 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,10 +4,10 @@ search: --- # クイックスタート -Realtime エージェントは OpenAI の Realtime API を使って、AI エージェントとの音声会話を可能にします。このガイドでは、最初の Realtime 音声エージェントの作成手順を説明します。 +リアルタイム エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声会話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、互換性のない変更が発生する可能性があります。 +リアルタイム エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 前提条件 @@ -23,7 +23,7 @@ Realtime エージェントはベータ版です。実装の改善に伴い、 pip install openai-agents ``` -## 最初の Realtime エージェントの作成 +## 最初のリアルタイム エージェントの作成 ### 1. 必要なコンポーネントのインポート @@ -32,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. Realtime エージェントの作成 +### 2. リアルタイム エージェントの作成 ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. runner のセットアップ +### 3. ランナーのセットアップ ```python runner = RealtimeRunner( @@ -109,9 +109,9 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 完全なコード例 +## 完全なサンプル -動作する完全なコード例は次のとおりです: +以下は完全に動作する例です: ```python import asyncio @@ -192,9 +192,9 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルを選択します (例: `gpt-realtime`) -- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストまたは音声を有効化します (`["text"]` または `["audio"]`) +- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-realtime`) +- `voice`: 音声を選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`) ### 音声設定 @@ -204,28 +204,28 @@ if __name__ == "__main__": ### ターン検出 -- `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`: 発話前の音声パディング -## 次の手順 +## 次のステップ -- [Realtime エージェントの詳細を学ぶ](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) フォルダの動作する例を確認 +- エージェントにツールを追加 +- エージェント間のハンドオフを実装 +- 安全のためのガードレールを設定 ## 認証 -環境に OpenAI API キーが設定されていることを確認します: +環境に OpenAI API キーが設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -また、セッション作成時に直接渡すこともできます: +またはセッション作成時に直接渡します: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 150c8dee0..e7c6b3cbc 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリース プロセス/変更履歴 +# リリースプロセス／変更履歴 -このプロジェクトは、`0.Y.Z` の形式を用いた、やや修正されたセマンティック バージョニングに従います。先頭の `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` を受け取っていた箇所の一部が、代わりに `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 484f83f17..cfd776cbf 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -この SDK は、ターミナル上でエージェントの挙動をすばやく対話的にテストするための `run_demo_loop` を提供します。 +この SDK は、`run_demo_loop` を提供しており、ターミナル上でエージェントの挙動を素早く対話的にテストできます。 ```python import asyncio @@ -18,6 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間の会話履歴を保持します。デフォルトでは、生成され次第モデルの出力をストリーミングします。上の例を実行すると、 run_demo_loop は対話的なチャットセッションを開始します。入力を継続的に促し、ターン間で会話全体の履歴を記憶します（そのため、エージェントは何が話されたかを把握できます）。さらに、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 +`run_demo_loop` は、ループで ユーザー 入力を促し、ターン間で会話履歴を保持します。既定で、生成と同時にモデル出力を ストリーミング します。上の例を実行すると、run_demo_loop は対話型のチャットセッションを開始します。継続的に入力を求め、ターン間で会話履歴全体を保持します（そのため、エージェントは何が議論されたかを把握できます）、そして生成され次第、エージェントの応答をリアルタイムに自動で ストリーミング します。 -このチャットセッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボードショートカットを使用してください。 \ No newline at end of file +このチャットセッションを終了するには、`quit` または `exit` と入力（Enter を押下）するか、`Ctrl-D` のキーボードショートカットを使用してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index c5eadce31..d764b4a83 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -6,51 +6,51 @@ search: `Runner.run` メソッドを呼び出すと、次のいずれかが返ります: -- `run` または `run_sync` を呼んだ場合は [`RunResult`][agents.result.RunResult] -- `run_streamed` を呼んだ場合は [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、主な有用情報はそこに含まれます。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報の多くはここに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が入ります。次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: - 最後のエージェントに `output_type` が定義されていない場合は `str` - エージェントに出力タイプが定義されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。これは ハンドオフ のため、静的型付けができません。ハンドオフ が発生すると、どのエージェントでも最後のエージェントになり得るため、可能な出力型の集合を静的には特定できません。 + `final_output` は型 Any です。ハンドオフの可能性があるため、静的な型付けはできません。ハンドオフが発生する場合、最後のエージェントになり得るのは任意のエージェントであり、取り得る出力タイプの集合を静的には特定できないためです。 -## 次ターンへの入力 +## 次のターンへの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、提供した元の入力に、エージェントの実行中に生成されたアイテムを連結した入力リストに実行結果を変換できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を末尾に追加したりするのが容易になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、実行時に生成された項目を、元の入力に連結した入力リストへ変換できます。これにより、あるエージェント実行の出力を別の実行へ渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが容易になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、これは次回 ユーザー が何かを入力する際に役立つことがよくあります。たとえば、一次トリアージのエージェントから特定言語に特化したエージェントへ ハンドオフ する構成の場合、最後のエージェントを保存しておき、次に ユーザー がそのエージェントにメッセージを送る際に再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が入力する際に役立つことが多いです。例えば、一次振り分けのエージェントが言語別のエージェントへハンドオフする場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送るときに再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`][agents.items.RunItem] です。Run item は、LLM が生成した生のアイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。RunItem は、LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem]: LLM からのメッセージを表します。生のアイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem]: LLM が ハンドオフ ツールを呼び出したことを示します。生のアイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフ が行われたことを示します。生のアイテムは ハンドオフ ツール呼び出しへのツール応答です。アイテムから送信元/送信先のエージェントにもアクセスできます。 +- [`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]: ツールが呼び出されたことを示します。生のアイテムはツールの応答です。アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem]: 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_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 34af40d13..e88f07cc6 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] を返します。 -2. [ `Runner.run_sync()` ][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 -3. [ `Runner.run_streamed()` ][agents.run.Runner.run_streamed]: 非同期で実行し、[ `RunResultStreaming` ][agents.result.RunResultStreaming] を返します。LLM を ストリーミング モードで呼び出し、受信したイベントをそのまま ストリーミング します。 +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 をストリーミング モードで呼び出し、受信したイベントを逐次ストリーミングします。 ```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 がツール呼び出しを生成した場合、それらを実行し、結果を追加して、ループを再実行します。 -3. 渡された `max_turns` を超えた場合、[ `MaxTurnsExceeded` ][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行して結果を追加し、ループを再実行します。 +3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、ツール呼び出しが無いことです。 ## ストリーミング -ストリーミング を使うと、LLM の実行中に ストリーミング イベントも受け取れます。ストリームが完了すると、[ `RunResultStreaming` ][agents.result.RunResultStreaming] に実行に関する完全な情報（新たに生成されたすべての出力を含む）が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して受け取れます。詳しくは [ストリーミング ガイド](streaming.md) をご覧ください。 +ストリーミングを使うと、LLM の実行中にストリーミング イベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新規出力を含む実行の完全な情報が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 ## 実行設定 -`run_config` パラメーターでは、エージェント 実行のグローバル設定を構成できます: +`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] のドキュメントをご覧ください。 -- [ `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]: すべてのトレースに含めるメタデータです。 +- [`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]: すべてのトレースに含めるメタデータ。 ## 会話/チャットスレッド -いずれの run メソッドを呼び出しても、1 つ以上のエージェント が実行され（つまり 1 回以上の LLM 呼び出しが発生し）ますが、チャット会話の 1 つの論理的なターンを表します。例: +いずれかの run メソッドを呼び出すと 1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される可能性がありますが、チャット会話の 1 つの論理ターンを表します。例: -1. ユーザー のターン: ユーザー がテキストを入力 -2. Runner の実行: 最初のエージェント が LLM を呼び出し、ツールを実行し、2 つ目のエージェント に ハンドオフ、2 つ目のエージェント がさらにツールを実行し、その後に出力を生成。 +1. ユーザーのターン: ユーザーがテキストを入力 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ、2 番目のエージェントがさらにツールを実行し、最終的に出力を生成。 -エージェント の実行終了時に、ユーザー に何を見せるかを選べます。例えば、エージェント が生成したすべての新しいアイテムを見せるか、最終出力だけを見せるかです。いずれにせよ、その後に ユーザー がフォローアップの質問をするかもしれません。その場合は、再び run メソッドを呼び出せます。 +エージェント実行の最後に、ユーザーに何を見せるかを選べます。例えば、エージェントが生成したすべての新規アイテムを見せることも、最終出力だけを見せることもできます。いずれにせよ、ユーザーが追質問をするかもしれないので、その場合は再度 run メソッドを呼び出します。 ### 手動の会話管理 -次のターンの入力を取得するために、[ `RunResultBase.to_input_list()` ][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます: +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドで次のターンの入力を取得し、会話履歴を手動で管理できます: ```python async def main(): @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使うと、手動で `.to_input_list()` を呼び出さずに会話履歴を自動処理できます: +より簡単な方法として、[Sessions](sessions.md) を使えば、`.to_input_list()` を手動で呼び出さずに会話履歴を自動処理できます: ```python from agents import Agent, Runner, SQLiteSession @@ -117,26 +117,26 @@ async def main(): # California ``` -Sessions は自動的に以下を行います: +Sessions は自動で次を行います: -- 各実行の前に会話履歴を取得 -- 各実行の後に新しいメッセージを保存 -- 異なるセッション ID ごとに別々の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なるセッション ID ごとに個別の会話を維持 -詳細は [Sessions ドキュメント](sessions.md) をご覧ください。 +詳細は [Sessions のドキュメント](sessions.md) を参照してください。 -## 長時間実行エージェントと Human-in-the-Loop +## 長時間実行のエージェントと human-in-the-loop -Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop タスクを含む耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了させるデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) で、ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) をご覧ください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、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 の 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 6653ae3ba..832709c67 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は複数回のエージェント実行にまたがって会話履歴を自動的に保持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 +Agents SDK は、複数回のエージェント実行にわたって会話履歴を自動的に保持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 -セッションは特定のセッションに対する会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 +Sessions は特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを保持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築するのに特に有用です。 ## クイックスタート @@ -51,17 +51,17 @@ print(result.final_output) # "Approximately 39 million" セッションメモリを有効にすると: -1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの先頭に付与します。 -2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）は自動的にセッションに保存されます。 -3. **コンテキストの維持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーがセッションの会話履歴を自動で取得し、入力アイテムの前に付加します。 +2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が自動的にセッションへ保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 -これにより、実行間で手動で `.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 @@ -128,8 +128,8 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API メモリ -[OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api) を使用して、独自のデータベースを管理せずに -会話状態を永続化します。これは、会話履歴の保存に OpenAI がホストするインフラストラクチャにすでに依存している場合に役立ちます。 +[OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api) を使用して、 +独自のデータベースを管理せずに会話状態を永続化します。これは、会話履歴の保存に OpenAI がホストするインフラストラクチャにすでに依存している場合に役立ちます。 ```python from agents import OpenAIConversationsSession @@ -188,13 +188,13 @@ result2 = await Runner.run( ) ``` -### SQLAlchemy 対応セッション +### SQLAlchemy ベースのセッション -より高度なユースケースでは、SQLAlchemy 駆動のセッションバックエンドを使用できます。これにより、セッションストレージに SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 +より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、セッションの保存に SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 -**例 1: `from_url` とインメモリ SQLite の使用** + **例 1: `from_url` を用いたインメモリ SQLite** -これは最も簡単な開始方法で、開発やテストに最適です。 +これは最も簡単な入門方法で、開発やテストに最適です。 ```python import asyncio @@ -215,9 +215,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy エンジンの使用** + **例 2: 既存の SQLAlchemy エンジンを使用する** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性があります。それをセッションに直接渡せます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っていることが多いでしょう。これをセッションに直接渡せます。 ```python import asyncio @@ -297,17 +297,17 @@ result = await Runner.run( 会話を整理しやすい意味のあるセッション 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)`）を使用 -- OpenAI がホストするストレージ（`OpenAIConversationsSession()`）は、履歴を OpenAI Conversations API に保存したい場合に使用 -- より高度なユースケースでは、他の本番システム（Redis、Django など）向けにカスタムセッションバックエンドの実装を検討 +- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用 +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用 +- 既存のデータベースを SQLAlchemy がサポートする本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 +- OpenAI Conversations API に履歴を保存したい場合は OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用 +- より高度なユースケースでは、他の本番システム（Redis、Django など）向けにカスタムセッションバックエンドの実装を検討 ### セッション管理 @@ -333,9 +333,9 @@ result2 = await Runner.run( ) ``` -## 完全なコード例 +## 完全な例 -以下は、セッションメモリの実際の動作を示す完全なコード例です: +セッションメモリの動作を示す完全な例です: ```python import asyncio @@ -399,9 +399,9 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは以下をご覧ください: +詳細な API ドキュメントは次を参照してください: -- [`Session`][agents.memory.Session] - プロトコルインターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 -- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 対応実装 \ No newline at end of file +- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 +- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 実装 +- [`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 efb6fb4ce..fb92229b9 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 レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。生成され次第、ユーザーに応答メッセージをストリーミングしたい場合に便利です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式であり、各イベントには種類（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、生成され次第すぐにレスポンスメッセージをユーザーへストリーミングしたい場合に有用です。 -例えば、これは LLM が生成するテキストをトークンごとに出力します。 +例えば、これは LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 実行アイテムイベントとエージェントイベント +## Run アイテムイベントと エージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] はより高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークンではなく「メッセージ生成」「ツール実行」などのレベルで進捗更新を配信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」といったレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果として）の更新を提供します。 -例えば、これは raw イベントを無視し、ユーザーに更新をストリーミングします。 +例えば、これは raw イベントを無視して、更新をユーザーにストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 250e89501..b76059a7f 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行できるようにします。データ取得、コード実行、外部 API 呼び出し、さらにはコンピュータの使用などです。Agent SDK にはツールが 3 つのクラスがあります: +ツールは エージェント がアクションを実行できるようにします。データ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作 まで行えます。Agents SDK には 3 つのツールクラスがあります: -- Hosted tools: これらは AI モデルと並行して LLM サーバー 上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供します。 +- Hosted tools: これらは AI モデルと同じ LLM サーバー上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を hosted tools として提供しています。 - Function calling: 任意の Python 関数をツールとして使用できます。 -- Agents as tools: エージェント をツールとして使うことで、ハンドオフ せずに エージェント から別の エージェント を呼び出せます。 +- ツールとしての エージェント: エージェント をツールとして使用でき、ハンドオフ せずに他の エージェント を呼び出せます。 -## ホスト型ツール +## Hosted tools -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]: コンピュータ操作 タスクを自動化できます。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]: LLM がサンドボックス環境でコードを実行できます。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool]: リモートの MCP サーバー のツールをモデルに公開します。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]: プロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool]: ローカルマシンでシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web を検索させます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を検索できます。 +- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 タスクを自動化します。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は サンドボックス環境でコードを実行します。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバーのツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -45,12 +45,12 @@ async def main(): 任意の 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,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数として任意の Python 型を使用でき、関数は同期・非同期いずれでも構いません。 -2. docstring があれば、説明文と引数の説明を取得します。 -3. 関数はオプションで `context`（先頭引数である必要があります）を受け取れます。ツール名や説明、docstring スタイルなどの上書きも設定できます。 -4. デコレートした関数を tools のリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、同期/非同期のいずれでも構いません。 +2. docstring があれば、説明や引数の説明に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring スタイルなどの上書き設定も可能です。 +4. デコレートした関数をツールの一覧に渡せます。 -??? note "出力を展開して表示" +??? note "出力を表示" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。代わりに、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: +Python 関数をツールとして使いたくない場合もあります。必要であれば直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。以下を指定する必要があります: - `name` - `description` -- `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列の引数を受け取り、ツールの出力文字列を返す async 関数） +- 引数の JSON スキーマである `params_json_schema` +- [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツール出力を文字列で返す非同期関数 `on_invoke_tool` ```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` です。形式は自動検出を試みますがベストエフォートです。`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 +1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を理解し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示指定できます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 ## ツールとしてのエージェント -一部のワークフローでは、ハンドオフ するのではなく、中央の エージェント が専門 エージェント のネットワークをオーケストレーションしたい場合があります。エージェント をツールとしてモデリングすることで実現できます。 +一部のワークフローでは、ハンドオフ する代わりに、中央の エージェント が専門 エージェント 群のオーケストレーションを行いたい場合があります。これは エージェント をツールとしてモデル化することで実現できます。 ```python from agents import Agent, Runner @@ -269,7 +269,7 @@ async def main(): ### ツール化エージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント を簡単にツール化するためのユーティリティです。ただし、すべての設定をサポートしているわけではありません（例: `max_turns` は設定できません）。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: +`agent.as_tool` は エージェント をツールに変換するための簡便メソッドです。ただし、すべての設定をサポートするわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。例えば次のような場合に有用です: +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。例えば以下の用途に有用です: -- サブエージェントのチャット履歴から特定情報（例: JSON ペイロード）を抽出する。 -- エージェント の最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 -- 出力を検証したり、エージェント の応答が欠落・不正な場合のフォールバック値を提供する。 +- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 +- エージェントの最終回答を変換または再整形する（例: 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` パラメーター は次を受け付けます: -- **Boolean values**: `True`（常に有効）または `False`（常に無効） -- **Callable functions**: `(context, agent)` を受け取り boolean を返す関数 -- **Async functions**: 複雑な条件ロジック向けの非同期関数 +`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` などになり得ます。 +- 既定では（何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 +- 独自のエラー関数を渡した場合は、それが実行され、その応答が LLM に送信されます。 +- 明示的に `None` を渡すと、ツール呼び出しのエラーは再スローされ、呼び出し元で処理できます。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -412,4 +412,4 @@ def get_user_profile(user_id: str) -> str: ``` -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラー処理を行う必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index ddbacd7f6..a876a5c1c 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベント）を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録（ LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタム イベント）を収集します。[Traces ダッシュボード](https://platform.openai.com/traces)を使って、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効にする方法は 2 つあります: + トレーシングはデフォルトで有効です。無効化する方法は 2 つあります: 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 単一の実行でのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します + 2. 単一の実行でトレーシングを無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーの下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンドの操作を表します。複数のスパンで構成されます。トレースには次のプロパティがあります: - - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 同じ会話からの複数のトレースをリンクするための任意のグループ ID。たとえばチャットスレッド ID など。 - - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースの任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: - - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを表す `trace_id` - - 親スパン（ある場合）を指す `parent_id` - - スパンに関する情報である `span_data`。たとえば `AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報など。 +- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 同じ会話からの複数のトレースを関連付けるための任意のグループ ID。たとえばチャット スレッド ID など。 + - `disabled`: True の場合、このトレースは記録されません。 + - `metadata`: トレースの任意のメタデータ。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次の情報があります: + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを表す `trace_id` + - このスパンの親スパン（ある場合）を指す `parent_id` + - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます。 -## 既定のトレーシング +## デフォルトのトレーシング デフォルトでは、 SDK は次をトレースします: -- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` によってラップされます -- エージェントが実行されるたびに `agent_span()` でラップされます -- LLM 生成は `generation_span()` でラップされます -- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます -- ガードレールは `guardrail_span()` でラップされます -- ハンドオフは `handoff_span()` でラップされます -- 音声入力（音声認識）は `transcription_span()` でラップされます -- 音声出力（音声合成）は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の下に親子付けされる場合があります +- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます。 +- エージェントが実行されるたびに、`agent_span()` でラップされます +- LLM の生成は `generation_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます +- ガードレールは `guardrail_span()` でラップされます +- ハンドオフは `handoff_span()` でラップされます +- 音声入力（音声認識）は `transcription_span()` でラップされます +- 音声出力（音声合成）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親子付けされる場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使う場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 -加えて、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の送信先へプッシュできます（置き換えやセカンダリ送信先として）。 +加えて、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先に送る（置き換え、または副次的な送信先として）ことができます。 -## 上位レベルのトレース +## より高レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。コード全体を `trace()` でラップすることで実現できます。 +複数回の `run()` 呼び出しを単一のトレースの一部にしたい場合があります。その場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,46 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. `Runner.run` の 2 回の呼び出しが `with 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` に、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を構成します。`BackendSpanExporter` は OpenAI のバックエンドへスパンとトレースをバッチでエクスポートします。 -このデフォルト設定をカスタマイズし、別のバックエンドへの送信や追加のバックエンドへの送信、あるいはエクスポーターの動作を変更するには、次の 2 つの方法があります: +このデフォルト構成をカスタマイズして、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポーターの動作変更を行うには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが用意できたときに受け取る「追加の」トレースプロセッサーを追加できます。これにより、 OpenAI のバックエンドへの送信に加えて独自の処理を実行できます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに「置き換え」できます。これは、 OpenAI のバックエンドへトレースが送信されなくなることを意味します（その役割を果たす `TracingProcessor` を含めない限り）。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第受け取る「追加の」トレース プロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレース プロセッサーに「置き換える」ことができます。OpenAI のバックエンドにトレースが送信されるのは、その役割を担う `TracingProcessor` を含めた場合に限られます。 -## Non-OpenAI モデルでのトレーシング +## OpenAI 以外のモデルでのトレーシング -トレーシングを無効化することなく、 Non-OpenAI モデルで OpenAI API キーを使用して、 OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 +OpenAI の API キーを、OpenAI 以外のモデルと一緒に使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。 ```python import os @@ -125,27 +125,27 @@ agent = Agent( ``` ## 注意 -- 無料のトレースは OpenAI Traces ダッシュボードで確認できます。 - -## 外部トレーシングプロセッサー一覧 - -- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) -- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) -- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) -- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) -- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file +- 無料のトレースは Openai Traces ダッシュボードで表示できます。 + +## 外部トレーシング プロセッサー一覧 + +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) +- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 70c48dfb3..67fce12e8 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**: input + output +- **requests**: 実行した LLM API コール数 +- **input_tokens**: 送信した入力トークン合計 +- **output_tokens**: 受信した出力トークン合計 +- **total_tokens**: 入力 + 出力 - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` ## 実行からの使用量の取得 -`Runner.run(...)` の後、`result.context_wrapper.usage` から取得します。 +`Runner.run(...)` 実行後、`result.context_wrapper.usage` から使用量にアクセスできます。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）で集計されます。 +使用量は実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 ## セッションでの使用量の取得 -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用量を返します。セッションはコンテキストのために会話履歴を保持しますが、各実行の使用量は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その特定の実行の使用量を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用量は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -46,11 +46,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -なお、セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しが返す使用量メトリクスは、その実行だけを表します。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用量メトリクスは、その実行の結果のみを表します。セッションでは、以前のメッセージが各実行の入力として再投入される場合があり、その後のターンの入力トークン数に影響します。 ## フックでの使用量の活用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、主要なライフサイクルのタイミングで使用量を記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクル時点で使用量を記録できます。 ```python class MyHooks(RunHooks): @@ -63,6 +63,6 @@ class MyHooks(RunHooks): 詳細な API ドキュメントは次を参照してください: -- [`Usage`][agents.usage.Usage] - 使用量の追跡データ構造 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用量にアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフック \ No newline at end of file +- [`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 25548d8bb..2ada782a3 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,11 +4,11 @@ search: --- # エージェントの可視化 -エージェントの可視化では、 **Graphviz** を使用して、エージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように連携するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を使用して、エージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存グループをインストールします: +オプションの `viz` 依存関係グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -18,9 +18,9 @@ pip install "openai-agents[viz]" `draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックスで表されます。 -- **MCP サーバー** は灰色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 +- **エージェント** は黄色のボックスとして表されます。 +- **MCP サーバー** は灰色のボックスとして表されます。 +- **ツール** は緑色の楕円として表されます。 - **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -67,9 +67,9 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェントのグラフ](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -これにより、 **トリアージ エージェント** と、そのサブエージェントやツールへの接続の構造を視覚的に表すグラフが生成されます。 +これは、 **トリアージ エージェント** と、そのサブエージェントやツールへの接続の構造を視覚的に表すグラフを生成します。 ## 可視化の理解 @@ -84,22 +84,21 @@ draw_graph(triage_agent) - エージェント間のハンドオフには **実線の矢印**。 - ツール呼び出しには **点線の矢印**。 - MCP サーバー呼び出しには **破線の矢印**。 -- 実行の終了地点を示す **終了ノード** (`__end__`)。 +- 実行が終了する場所を示す **終了ノード** (`__end__`)。 -**注意:** MCP サーバーは最近のバージョンの -`agents` パッケージでレンダリングされます（ **v0.2.8** で確認済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**注:** MCP サーバーは、最近の `agents` パッケージのバージョンで描画されます（ **v0.2.8** で確認済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: +既定では、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: +既定では、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index ba00a7a6b..44c91d018 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 など） - - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） +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 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の文字起こしが既にあり、その結果に対する出力だけが必要な場合に使います。話者が話し終えたタイミングの検出が不要なケース、例えば事前録音の音声や、ユーザーが話し終わるタイミングが明確なプッシュトゥトーク型アプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングの検出が必要な場合に使います。検出された音声チャンクを逐次プッシュでき、パイプラインは「アクティビティ検出」と呼ばれる処理を通じて、適切なタイミングで自動的にエージェントのワークフローを実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput]: 音声の全文字起こしがあり、その結果だけを生成したい場合に使用します。発話終了の検出が不要なケース（例: 事前録音の音声、話者の終了が明確なプッシュ・トゥ・トーク (push-to-talk) アプリ）に役立ちます。 +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 f178e2d22..0d24e90e2 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,10 +14,10 @@ pip install 'openai-agents[voice]' ## 概念 -主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです。 +知っておくべき主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスです。 1. 音声をテキストに変換するために音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行して結果を生成します。 +2. 結果を生成するために、通常はエージェントのワークフローであるあなたのコードを実行します。 3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 ```mermaid @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定しましょう。これは、この SDK でエージェントを作成したことがあれば馴染みがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。この SDK でエージェントを作成したことがあれば、見覚えがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 ```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 989f60b1b..4f0053177 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレースされます。 +[エージェントがトレーシングされる方法](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報は上記ドキュメントをご参照ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] によってパイプラインのトレーシングを構成できます。 +基本的なトレーシング情報については上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを構成できます。 -トレーシングに関する主なフィールドは次のとおりです。 +主要なトレーシング関連フィールドは次のとおりです: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。既定ではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機微情報となり得るデータをトレースに含めるかどうかを制御します。これは音声パイプラインに特有で、ワークフロー内部で起こる処理には適用されません。 -- [`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 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。既定ではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしのような機微情報をトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、あなたの Workflow 内で起こる処理には適用されません。 +- [`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