diff --git a/docs/agents.md b/docs/agents.md index 15ced6255..d401f53da 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -22,7 +22,7 @@ def get_weather(city: str) -> str: agent = Agent( name="Haiku agent", instructions="Always respond in haiku form", - model="o3-mini", + model="gpt-5-nano", tools=[get_weather], ) ``` @@ -163,7 +163,7 @@ By using the `clone()` method on an agent, you can duplicate an Agent, and optio pirate_agent = Agent( name="Pirate", instructions="Write like a pirate", - model="o3-mini", + model="gpt-4.1", ) robot_agent = pirate_agent.clone( diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 64999d312..b6b04e482 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは、instructions とツールで構成された大規模言語モデル ( LLM ) です。 +エージェントはアプリにおける中核の構成要素です。エージェントは、instructions と tools で構成された大規模言語モデル（ LLM ）です。 -## 基本設定 +## 基本構成 -最も一般的に設定するエージェントのプロパティは次のとおりです。 +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージまたは 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 @@ -26,14 +26,14 @@ def get_weather(city: str) -> str: agent = Agent( name="Haiku agent", instructions="Always respond in haiku form", - model="o3-mini", + model="gpt-5-nano", tools=[get_weather], ) ``` ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行における依存関係と状態の詰め合わせとして機能します。任意の Python オブジェクトをコンテキストとして提供できます。 +エージェントはその `context` 型に対してジェネリックです。Context は依存性注入のためのツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行に必要な依存関係と状態の寄せ集めとして機能します。任意の Python オブジェクトを context として提供できます。 ```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、list、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) を参照してください。 -### マネージャー（ツールとしてのエージェント） +### マネージャー（エージェントをツールとして） -`customer_facing_agent` はすべてのユーザー対応を行い、ツールとして公開された特化型サブエージェントを呼び出します。詳しくは [ツール](tools.md#agents-as-tools) のドキュメントを参照してください。 +`customer_facing_agent` はすべてのユーザー対応を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントをご覧ください。 ```python from agents import Agent @@ -115,7 +115,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに秀でたモジュール型・特化型エージェントが可能になります。詳しくは [ハンドオフ](handoffs.md) のドキュメントを参照してください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフが発生すると、委譲先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに特化したモジュール式のエージェントが可能になります。詳細は [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を指定できますが、関数を介して動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも使用できます。 +多くの場合、エージェントを作成するときに instructions を指定できますが、関数を通じて動的な instructions を提供することもできます。この関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を受け付けます。 ```python def dynamic_instructions( @@ -153,11 +153,11 @@ agent = Agent[UserContext]( ## ライフサイクルイベント（フック） -場合によっては、エージェントのライフサイクルを観察したいことがあります。たとえば、イベントのログ記録や、特定のイベント発生時にデータを事前取得したい場合です。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりします。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック/検証を行い、エージェントの出力が生成された後にもチェックを実行できます。たとえば、ユーザー入力とエージェント出力の関連性をスクリーニングできます。詳しくは [ガードレール](guardrails.md) のドキュメントを参照してください。 +ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック/バリデーションを実行し、エージェントの出力が生成された後にも同様のチェックを行えます。たとえば、ユーザーの入力とエージェントの出力の妥当性をスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントをご覧ください。 ## エージェントのクローン/コピー @@ -167,7 +167,7 @@ agent = Agent[UserContext]( pirate_agent = Agent( name="Pirate", instructions="Write like a pirate", - model="o3-mini", + model="gpt-4.1", ) robot_agent = pirate_agent.clone( @@ -178,12 +178,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、LLM が必ずツールを使うとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです。 +ツールのリストを渡しても、LLM が必ずしもツールを使うとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、ツール使用を強制できます。有効な値は次のとおりです。 -1. `auto`: LLM にツールを使うかどうかを判断させます。 -2. `required`: LLM にツールの使用を要求します（どのツールを使うかは賢く判断できます）。 -3. `none`: LLM にツールを使用しないことを要求します。 -4. 特定の文字列（例: `my_tool`）を設定すると、その特定のツールを LLM に使用させます。 +1. `auto`: LLM にツールを使うかどうかの判断を任せます。 +2. `required`: LLM にツールの使用を要求します（ただし、どのツールを使うかは賢く判断できます）。 +3. `none`: LLM にツールを使わないよう要求します。 +4. 特定の文字列（例: `my_tool`）を設定し、その特定のツールの使用を要求します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -201,12 +201,12 @@ agent = Agent( ) ``` -## ツール使用の挙動 +## ツール使用の動作 `Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱いを制御します。 - `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の 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 2dfb3acfe..7f8d4e875 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポートされた直後から LLM リクエストと トレーシング のために `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[デフォルトの OpenAI キーを設定する (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` インスタンスを作成します。これを変更するには、[デフォルトの OpenAI クライアントを設定する (set_default_openai_client)][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは、OpenAI Responses API を使用します。これを上書きして Chat Completions API を使用するには、[デフォルトの OpenAI API を設定する (set_default_openai_api)][agents.set_default_openai_api] 関数を使用します。 +さらに、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使用するには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシング はデフォルトで有効です。デフォルトでは、上記のセクションの OpenAI API キー（つまり、環境変数または設定したデフォルトキー）を使用します。トレーシング に使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 +トレーシングはデフォルトで有効です。デフォルトでは上記の OpenAI API キー（すなわち、環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシング を完全に無効化することもできます。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシングを完全に無効化することもできます。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグロギング +## デバッグログ -SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、その他のログは抑制されることを意味します。 +SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。 -詳細なログ出力を有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログを有効にするには、[`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 ガイド](https://docs.python.org/3/howto/logging.html)をご覧ください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -83,15 +83,15 @@ 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 4f19f9e9c..e5ce0c193 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという用語には複数の意味があります。ここでは主に次の 2 つの種類のコンテキストを扱います。 +コンテキストは多義的な用語です。重要なのは次の 2 つのクラスです。 -1. コードからローカルに参照できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。 -2. LLM に提供されるコンテキスト: これは、応答を生成する際に LLM が参照できるデータです。 +1. コードからローカルで利用可能なコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に提供されるコンテキスト: 応答を生成する際に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティによって表現されます。動作の流れは次のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 -2. そのオブジェクトを各種の実行メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 -3. すべてのツール呼び出しやライフサイクルフックなどには、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` を通じてアクセスできます。 +2. そのオブジェクトを各種 run メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 +3. すべてのツール呼び出しやライフサイクルフックには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -最も **重要** な点: 特定のエージェント実行に関わるすべてのエージェント、ツール関数、ライフサイクルなどは、同じ型のコンテキストを使用しなければなりません。 +**最も重要** な注意点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じコンテキストの型を使用する必要があります。 コンテキストは次のような用途に使えます: -- 実行時の状況データ（例: ユーザー名/ UID やユーザーに関するその他の情報） +- 実行時のコンテキストデータ（例: ユーザー名/uid やその他のユーザーに関する情報） - 依存関係（例: ロガーオブジェクト、データフェッチャーなど） - ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは LLM に送信されません。これは純粋にローカルなオブジェクトで、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に送信されません。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装はコンテキストから読み取ります。 -3. 型チェッカーでエラーを検出できるように、エージェントにジェネリック `UserInfo` を付与しています（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っているのが分かります。ツールの実装はコンテキストから読み取ります。 +3. 型チェッカーでエラーを検出できるように（例えば、異なるコンテキスト型を受け取るツールを渡した場合など）、エージェントにジェネリクス `UserInfo` を付けています。 4. コンテキストは `run` 関数に渡されます。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント/ LLM のコンテキスト +## エージェント/LLM のコンテキスト -LLM が呼び出されるとき、参照できるのは会話履歴に含まれるデータのみです。つまり、LLM に新しいデータを利用させたい場合は、その履歴に含められる形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できるのは会話履歴からのデータのみです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できる形で提供しなければなりません。方法はいくつかあります: -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でも構いません。常に有用な情報（例: ユーザーの名前や現在の日付）に適した手法です。 -2. `Runner.run` を呼び出す際の `input` に追加します。これは `instructions` の手法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)の下位にメッセージを配置できます。 -3. 関数ツール経由で公開します。これはオンデマンドのコンテキストに有用で、LLM が必要になったタイミングでツールを呼び出してデータを取得できます。 -4. リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）、あるいは Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答に根拠付けを行うのに有用です。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「system prompt」や「developer message」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 +2. `Runner.run` 関数を呼ぶときの `input` に追加します。これは `instructions` を使う方法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)でより下位のメッセージを持たせられます。 +3. 関数ツール経由で公開します。これは _オンデマンド_ のコンテキストに有用です。LLM は必要なときにデータが必要だと判断し、ツールを呼び出してそのデータを取得できます。 +4. リトリーバルまたは Web 検索を使います。これらは、ファイルやデータベース（リトリーバル）、あるいは Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに応答を「グラウンディング」するのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index ae06375a8..3b52cbcc3 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -2,47 +2,47 @@ search: exclude: true --- -# コード例 - -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の コード例 セクションで、SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示す複数の カテゴリー に整理されています。 +# サンプル +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK の多様なサンプル実装を確認できます。これらの code examples は、さまざまなパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例では、次のような一般的な エージェント の設計パターンを示します。 + このカテゴリーの code examples は、次のような一般的なエージェント設計パターンを示します - 決定的なワークフロー - - ツールとしての エージェント - - エージェント の並列実行 + - ツールとしてのエージェント + - 並列エージェント実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - このカテゴリーの例では、SDK の基礎的な機能を紹介します。 + これらの code examples は、SDK の基礎的な機能を示します - 動的な システムプロンプト - - ストリーミング 出力 + - ストリーミング出力 - ライフサイクルイベント -- **[ツールのコード例](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 といった OpenAI がホストするツール の実装方法と、それらを エージェント に統合する方法を学べます。 +- **[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/model_providers):** - SDK で 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/handoffs):** - エージェント の ハンドオフ の実践的な例をご覧ください。 +- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + エージェントのハンドオフ の実践的な code examples を確認できます。 - **[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 つ紹介します。 + 実世界のアプリケーションを示す、より作り込まれた code examples が 2 つあります - - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 - - **research_bot**: シンプルな ディープリサーチ のクローン。 + - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 + - **research_bot**: シンプルな ディープリサーチ クローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを用いた音声 エージェント の例。 + 当社の TTS と STT モデルを用いた音声エージェントの code examples を確認できます。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使って リアルタイム 体験を構築する方法の例。 \ No newline at end of file + SDK を使用してリアルタイム体験を構築する方法を示す code examples。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index cd32f77d8..dc0d68cbb 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並列_ に実行され、ユーザー入力のチェックと検証を行います。たとえば、顧客対応に非常に賢い（そのため遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を手伝わせるよう依頼するのは避けたいはずです。そこで、速く/安価なモデルでガードレールを走らせます。ガードレールが不正利用を検出した場合、即座にエラーを発生させ、高価なモデルの実行を止め、時間やコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力の検査と検証を行います。たとえば、顧客からのリクエスト対応に非常に賢い（＝遅くて高価な）モデルを使うエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせるような依頼をすることは避けたいはずです。そこで、速くて安価なモデルでガードレールを実行できます。ガードレールが不正利用を検知したら、即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。 -ガードレールには 2 種類あります: +ガードレールには 2 種類あります。 1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェントの出力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 ステップで実行されます: +入力ガードレールは次の 3 ステップで実行されます。 -1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。 +1. まず、ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップします。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が行えます。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントのガードレールはそのエージェントが「最初の」エージェントの場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡されないのかと疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールが走るのは、そのエージェントが「最初の」エージェントである場合のみです。`guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのはなぜかと疑問に思うかもしれません。ガードレールは実際のエージェントに密接に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。 ## 出力ガードレール -出力ガードレールは 3 ステップで実行されます: +出力ガードレールは次の 3 ステップで実行されます。 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。 +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 @@ -96,7 +96,7 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果に追加情報を含められます。 +3. ガードレールの結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 180740cc7..5585b7fdf 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# Handoffs +# ハンドオフ -Handoffs は、ある エージェント が別の エージェント にタスクを委譲できるようにする仕組みです。これは、異なる エージェント がそれぞれ別の分野を専門にしている状況で特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専任で担当する エージェント がいるかもしれません。 +ハンドオフは、あるエージェントが別のエージェントにタスクを委任することを可能にします。これは、異なるエージェントがそれぞれ特定の分野を専門としているシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱うエージェントがいるかもしれません。 -Handoffs は LLM に対してツールとして表現されます。したがって、`Refund Agent` という名前の エージェント への handoff がある場合、そのツール名は `transfer_to_refund_agent` になります。 +ハンドオフは、LLM に対してツールとして表現されます。例えば `Refund Agent` というエージェントへのハンドオフがある場合、そのツール名は `transfer_to_refund_agent` になります。 -## Handoff の作成 +## ハンドオフの作成 -すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは `Agent` を直接渡すか、Handoff をカスタマイズする `Handoff` オブジェクトを受け取ります。 +すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持っており、これは `Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用して handoff を作成できます。この関数では、ハンドオフ先の エージェント の指定に加えて、任意の上書きや入力フィルターを指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き渡し先のエージェントに加えて、任意の上書き設定や入力フィルターを指定できます。 ### 基本的な使い方 -シンプルな handoff を作成する方法は次のとおりです。 +以下は、シンプルなハンドオフの作り方です。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のように エージェント を直接使用することも、`handoff()` 関数を使用することもできます。 +1. エージェントを直接使う（`billing_agent` のように）ことも、`handoff()` 関数を使うこともできます。 -### `handoff()` 関数による handoff のカスタマイズ +### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフ先の エージェント です。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使用され、`transfer_to_` が割り当てられます。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: handoff が呼び出されたときに実行されるコールバック関数です。handoff が呼ばれたことが分かった時点でのデータ取得開始などに役立ちます。この関数は エージェント コンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: handoff が想定する入力の型（任意）。 -- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: handoff を有効にするかどうか。ブール値、またはブール値を返す関数を指定でき、実行時に動的に handoff を有効化・無効化できます。 +- `agent`: 引き渡し先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使われ、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されることがわかった時点でデータ取得を開始するなどに便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフが想定する入力の型（任意）です。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 +- `is_enabled`: ハンドオフを有効にするかどうかです。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## Handoff の入力 +## ハンドオフの入力 -状況によっては、handoff を呼び出す際に LLM に何らかのデータを提供してほしいことがあります。例えば、「エスカレーション エージェント」への handoff を想定してみてください。ログに残すために理由を提供してほしい、ということがあるかもしれません。 +状況によっては、ハンドオフを呼び出す際に LLM にいくつかのデータを提供してほしい場合があります。例えば「エスカレーションエージェント」へのハンドオフを想像してください。ログのために理由を提供してほしい、というようなケースです。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -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 が handoff を正しく理解するようにするため、エージェント に handoff に関する情報を含めることを推奨します。[`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 63ff336c2..b62760ec3 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 -- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できる機能 -- **ガードレール**: エージェントの入力と出力を検証できる機能 -- **セッション**: エージェントの実行間で会話履歴を自動的に保持 +- **ハンドオフ**: 特定のタスクでエージェントが他のエージェントに委譲できる機能 +- **ガードレール**: エージェントの入力と出力の検証を可能にする機能 +- **セッション**: エージェントの実行間で会話履歴を自動的に維持する機能 -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、この SDK には **トレーシング** が組み込まれており、エージェントのフローを可視化・デバッグできるほか、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェント フローの可視化とデバッグ、評価、さらにはアプリケーション向けのモデルのファインチューニングまで行えます。 -## Agents SDK を使う理由 +## Why use the Agents SDK -この SDK は次の 2 つの設計原則に基づいています。 +この SDK の設計原則は 2 つあります。 -1. 使う価値のある十分な機能を備えつつ、学習を素早くできるよう基本コンポーネントは少数に保つこと。 -2. すぐに使えて高品質に動作しつつ、挙動を細部までカスタマイズできること。 +1. 十分に使う価値がある機能を備えつつ、基本コンポーネントは少なく、短時間で学べること。 +2. そのままでも優れた動作をする一方で、何が起きるかを正確にカスタマイズできること。 SDK の主な機能は次のとおりです。 -- エージェントループ: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを処理する組み込みのループ。 -- Python ファースト: 新しい抽象を学ぶのではなく、言語の標準機能でエージェントのオーケストレーションや連携を記述。 -- ハンドオフ: 複数のエージェント間での調整と委譲を可能にする強力な機能。 +- エージェント ループ: ツールの呼び出し、結果を LLM へ送信、LLM の完了までのループを処理する組み込みのループ。 +- Python ファースト: 新しい抽象化を学ぶのではなく、言語の組み込み機能でエージェントのオーケストレーションや連鎖を実現。 +- ハンドオフ: 複数のエージェント間での調整や委譲を可能にする強力な機能。 - ガードレール: エージェントと並行して入力の検証やチェックを実行し、失敗時には早期に中断。 -- セッション: エージェントの実行間での会話履歴を自動管理し、手動での状態管理を不要化。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースのバリデーションを提供。 -- トレーシング: ワークフローの可視化・デバッグ・モニタリングに加え、OpenAI の評価、ファインチューニング、蒸留ツール群を活用可能な組み込みトレーシング。 +- セッション: エージェントの実行間での会話履歴を自動管理し、手動の状態管理を不要に。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 +- トレーシング: ワークフローの可視化、デバッグ、モニタリングを可能にし、OpenAI の評価、ファインチューニング、蒸留ツール群も利用可能。 ## インストール diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 829251aa1..2ce0acb49 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -6,32 +6,30 @@ search: [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. +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションのための USB-C ポートのようなものです。USB-C がデバイスをさまざまな周辺機器やアクセサリに標準化された方法で接続できるのと同様に、MCP は AI モデルをさまざまなデータソースやツールに標準化された方法で接続します。 -Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、独自に構築してファイルシステム、HTTP、あるいはコネクタ バックエンドのツールをエージェントに公開できます。 +Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、ファイルシステム、HTTP、またはコネクタで支えられたツールをエージェントに公開するために独自のサーバーを構築したりできます。 -## MCP 統合の選択 +## Choosing an MCP integration -MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下の表は Python SDK がサポートするオプションの概要です。 +エージェントに MCP サーバーを接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは Python SDK がサポートするオプションの概要です。 -| 要件 | 推奨オプション | -| ------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| OpenAI の Responses API がモデルの代理でインターネット経由で到達可能な MCP サーバーを呼び出す | **Hosted MCP server tools** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | -| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | -| Server-Sent Events を備えた HTTP を実装するサーバーと通信する | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | -| ローカル プロセスを起動し、stdin/stdout 経由で通信する | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | +| 必要なこと | 推奨オプション | +| --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| モデルの代わりに OpenAI の Responses API からパブリックに到達可能な MCP サーバーを呼び出す | [`HostedMCPTool`][agents.tool.HostedMCPTool] による **Hosted MCP server tools** | +| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] による **Streamable HTTP MCP servers** | +| Server-Sent Events を用いた HTTP を実装するサーバーと通信する | [`MCPServerSse`][agents.mcp.server.MCPServerSse] による **HTTP with SSE MCP servers** | +| ローカルプロセスを起動して stdin/stdout 経由で通信する | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] による **stdio MCP servers** | -以下のセクションではそれぞれのオプションについて、設定方法やどのトランスポートを選ぶべきかを解説します。 +以下のセクションでは、それぞれのオプションの設定方法と、どのトランスポートを選ぶべきかを説明します。 -## 1. Hosted MCP サーバーのツール +## 1. Hosted MCP server tools -ホスト型ツールは、ツールの往復処理全体を OpenAI のインフラに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] がサーバーのラベル（および任意のコネクタ メタデータ）を Responses API に転送します。モデルはリモート サーバーのツールを列挙し、あなたの Python プロセスへの追加のコールバックなしにそれらを呼び出します。ホスト型ツールは現在、Responses API の ホスト型 MCP 統合をサポートする OpenAI のモデルで動作します。 +ホスト型ツールは、ツールの往復処理全体を OpenAI のインフラストラクチャに移します。コードでツールの列挙や呼び出しを行う代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] はサーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、Python プロセスへの追加のコールバックなしでそれらを呼び出します。ホスト型ツールは現在、Responses API の hosted MCP 連携をサポートする OpenAI モデルで動作します。 -### 基本的なホスト型 MCP ツール +### Basic hosted MCP tool -エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` の dict は、REST API に送信する JSON を反映します: +エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` 辞書は REST API に送る JSON と同じ構造です: ```python import asyncio @@ -59,11 +57,11 @@ async def main() -> None: asyncio.run(main()) ``` -ホスト型サーバーは自動的にツールを公開します。`mcp_servers` に追加する必要はありません。 +ホストされたサーバーは自動的にそのツールを公開します。`mcp_servers` に追加する必要はありません。 -### ホスト型 MCP 結果のストリーミング +### Streaming hosted MCP results -ホスト型ツールは、関数ツールとまったく同じ方法で結果のストリーミングをサポートします。`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 +71,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"`）またはツール名からポリシーへの辞書で設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -103,11 +101,11 @@ agent = Agent( ) ``` -コールバックは同期または非同期のいずれでもよく、モデルが継続実行に必要な承認データを求めるたびに呼び出されます。 +コールバックは同期・非同期のどちらでもよく、モデルが継続実行に必要な承認データを求めるたびに呼び出されます。 -### コネクタ バックエンドのホスト型サーバー +### Connector-backed hosted servers -ホスト型 MCP は OpenAI コネクタもサポートします。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホスト型サーバーはコネクタのツールを公開します。 +Hosted MCP は OpenAI コネクタにも対応しています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホストされたサーバーがコネクタのツールを公開します。 ```python import os @@ -126,10 +124,10 @@ HostedMCPTool( ストリーミング、承認、コネクタを含む完全なホスト型ツールのサンプルは [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 -## 2. Streamable HTTP MCP サーバー +## 2. Streamable HTTP MCP servers -ネットワーク接続を自分で管理したい場合は -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを制御したい場合や、レイテンシを抑えつつ自社インフラ内でサーバーを稼働させたい場合に最適です。 +ネットワーク接続を自分で管理したい場合は、 +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、レイテンシを低く保ちながら自社インフラ内でサーバーを実行したい場合に最適です。 ```python import asyncio @@ -167,20 +165,20 @@ 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-filtering) を参照）。 +- `use_structured_content` は、テキスト出力よりも `tool_result.structured_content` を優先するかどうかを切り替えます。 +- `max_retry_attempts` と `retry_backoff_seconds_base` は `list_tools()` と `call_tool()` に自動リトライを追加します。 +- `tool_filter` は公開するツールのサブセットを制限できます（[Tool filtering](#tool-filtering) を参照）。 -## 3. HTTP with SSE MCP サーバー +## 3. HTTP with SSE MCP servers MCP サーバーが HTTP with SSE トランスポートを実装している場合は、 -[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外の API は Streamable HTTP サーバーと同一です。 ```python from agents import Agent, Runner from agents.model_settings import ModelSettings -from mcp import MCPServerSse +from agents.mcp import MCPServerSse workspace_id = "demo-workspace" @@ -201,9 +199,9 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP サーバー +## 4. stdio MCP servers -ローカル サブプロセスとして実行する MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたまま維持し、コンテキスト マネージャの終了時に自動的にクローズします。これは、迅速なプロトタイプや、サーバーがコマンドライン エントリ ポイントのみを公開する場合に有用です。 +ローカルのサブプロセスとして動作する MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキストマネージャの終了時に自動的にクローズします。これは、迅速なプロトタイプや、サーバーがコマンドラインのエントリポイントのみを公開している場合に役立ちます。 ```python from pathlib import Path @@ -229,13 +227,13 @@ async with MCPServerStdio( print(result.final_output) ``` -## ツールのフィルタリング +## Tool filtering -各 MCP サーバーはツール フィルタをサポートしており、エージェントに必要な機能だけを公開できます。フィルタリングは構築時にも、実行ごとに動的にも行えます。 +各 MCP サーバーはツールフィルターをサポートしており、エージェントに必要な関数だけを公開できます。フィルタリングは構築時にも、実行ごとに動的にも行えます。 -### 静的なツール フィルタリング +### Static tool filtering -[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、単純な許可/拒否リストを設定します: +[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、単純な許可/ブロックリストを構成します: ```python from pathlib import Path @@ -253,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 @@ -281,14 +279,14 @@ async with MCPServerStdio( ... ``` -フィルタ コンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。 +フィルターコンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。 -## プロンプト +## Prompts -MCP サーバーは、エージェントの指示を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 つのメソッドを公開します: +MCP サーバーは、エージェントの instructions を動的に生成する Prompts も提供できます。Prompts をサポートするサーバーは次の 2 つのメソッドを公開します: -- `list_prompts()` は利用可能なプロンプト テンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具象プロンプトを取得します。 +- `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 +- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。 ```python from agents import Agent @@ -306,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.md) は MCP のアクティビティを自動的に記録します。含まれる内容: +[Tracing](./tracing.md) は、次を含む MCP アクティビティを自動的に捕捉します: -1. MCP サーバーへのツール一覧取得呼び出し。 +1. ツール一覧のための MCP サーバーへの呼び出し。 2. ツール呼び出しに関する MCP 関連情報。 -![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) +![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) -## 参考情報 +## Further reading -- [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) – 承認やコネクタを含む完全なホスト型 MCP デモ。 \ No newline at end of file +- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様と設計ガイド。 +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP のサンプル。 +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む完全な hosted MCP デモ。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 4f369e5da..59c8270a3 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに使える形で 2 通りサポートしています。 +Agents SDK には、OpenAI モデルをすぐに使える形で次の 2 種類でサポートしています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい Responses API を使用して OpenAI API を呼び出します。(https://platform.openai.com/docs/api-reference/responses) +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。Chat Completions API を使用して OpenAI API を呼び出します。(https://platform.openai.com/docs/api-reference/chat) ## OpenAI モデル -`Agent` の初期化時にモデルを指定しない場合は、デフォルトのモデルが使われます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェントワークフローにおける予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化するときにモデルを指定しない場合、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント型ワークフローにおける予測可能性と低レイテンシの強力なバランスを提供します。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など別のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 ### デフォルトの OpenAI モデル -カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使いたい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 +カスタムモデルを設定していないすべてのエージェントに対して特定のモデルを一貫して使用したい場合は、エージェントを実行する前に環境変数 `OPENAI_DEFAULT_MODEL` を設定してください。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -この方法で GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使う場合、SDK は妥当な `ModelSettings` をデフォルトで適用します。具体的には、`reasoning.effort` と `verbosity` をどちらも `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 +この方法で GPT-5 の 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")` を呼び出してください。 -レイテンシをさらに下げたい、または特定の要件がある場合は、別のモデルと設定を選べます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。 +より低レイテンシや特定の要件がある場合は、別のモデルと設定を選択できます。デフォルトモデルの reasoning の強度を調整するには、独自の `ModelSettings` を渡してください。 ```python from openai.types.shared import Reasoning @@ -44,52 +44,52 @@ my_agent = Agent( ) ``` -特にレイテンシを下げる目的では、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、デフォルト設定より高速に応答が返ることが多いです。ただし Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしていないため、この 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 通りの方法で統合できます（examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダを統合する方法はさらに 3 つあります（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは、LLM プロバイダが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に使用します。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行のすべてのエージェントでカスタムのモデルプロバイダを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] では、特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダを組み合わせて使えます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能な多くのモデルを簡単に使う方法として、[LiteLLM 連携](./litellm.md) があります。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に有用です。これは LLM プロバイダが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能なサンプルは [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行のすべてのエージェントにカスタムのモデルプロバイダを使う」と指定できます。設定可能なサンプルは [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] は特定の Agent インスタンスでモデルを指定できます。これにより、エージェントごとに異なるプロバイダを組み合わせて使うことができます。設定可能なサンプルは [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの利用可能なモデルを簡単に使う方法としては、[LiteLLM 連携](../litellm.md) があります。 -`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの examples では、Responses API をまだサポートしていない LLM プロバイダが多いため、Chat Completions API/モデルを使用しています。もし利用中の LLM プロバイダが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの code examples では、Responses API/モデルではなく Chat Completions API/モデルを使用しています。これは、多くの LLM プロバイダがまだ Responses API をサポートしていないためです。もし使用する LLM プロバイダが Responses をサポートしている場合は、Responses の使用をおすすめします。 ## モデルの組み合わせ -1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小さく高速なモデルを、複雑なタスクにはより大きく高性能なモデルを使うといった具合です。[`Agent`][agents.Agent] の設定時には、次のいずれかの方法で特定のモデルを選べます。 +1 つのワークフローの中で、エージェントごとに異なるモデルを使いたい場合があります。例えば、トリアージには小型で高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使うといった使い分けです。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法で特定のモデルを選択できます。 -1. モデル名を渡す。 -2. 任意のモデル名と、その名前を Model インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 -3. [`Model`][agents.models.interface.Model] の実装を直接渡す。 +1. モデル名を直接渡す。 +2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは単一のモデル形状を使うことを推奨します。ワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしていますが、ワークフローごとに 1 つのモデル形に統一することをおすすめします。両者はサポートする機能やツールのセットが異なるためです。ワークフローでモデル形を混在させる場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -122,10 +122,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデルの名前を直接設定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +1. OpenAI のモデル名を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに細かく設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡してください。これは、temperature などのオプションのモデル設定パラメーターを提供します。 +エージェントで使用するモデルをさらに設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡すことで、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 @@ -156,24 +156,24 @@ english_agent = Agent( ## 他の LLM プロバイダ使用時の一般的な問題 -### トレーシングクライアントの 401 エラー +### トレーシングクライアントのエラー 401 -トレーシング関連のエラーが発生する場合、トレースは OpenAI のサーバーにアップロードされ、あなたが OpenAI の API キーを持っていないことが原因です。解決策は次の 3 つです。 +トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI のサーバーにアップロードされる一方で、OpenAI の API キーを持っていないためです。解決策は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. OpenAI 以外のトレースプロセッサーを使用する。[tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +2. トレーシング用に OpenAI のキーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. OpenAI 以外のトレースプロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、多くの他の LLM プロバイダはまだサポートしていません。その結果、404 などの問題が発生する場合があります。解決策は次の 2 つです。 +SDK はデフォルトで Responses API を使用しますが、ほとんどの他の LLM プロバイダはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決するには、次の 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] を使用します。examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 -### structured outputs のサポート +### Structured outputs のサポート -一部のモデルプロバイダは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーが発生することがあります。 +一部のモデルプロバイダは、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。このため、次のようなエラーが発生することがあります。 ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダ側の制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないという問題です。現在、この点については修正に取り組んでいますが、JSON schema 出力をサポートしているプロバイダに依存することを推奨します。そうでない場合、不正な JSON が原因でアプリが頻繁に壊れる可能性があります。 +これは一部のモデルプロバイダ側の不足によるものです。JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないことがあります。現在これに対する修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダに依存することをおすすめします。そうでないと、JSON の不正形式が原因でアプリが頻繁に壊れてしまいます。 -## プロバイダ間でモデルを混在させる +## プロバイダをまたいだモデルの混在 -モデルプロバイダ間の機能差を理解していないと、エラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしていますが、多くの他プロバイダはこれらの機能をサポートしていません。以下の制約に注意してください。 +モデルプロバイダ間の機能差異に注意しないと、エラーに遭遇する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索および Web 検索をサポートしていますが、多くの他プロバイダはこれらの機能をサポートしていません。次の制限に注意してください。 -- サポートしていない `tools` を理解しないプロバイダに送らない -- テキスト専用モデルを呼び出す前にマルチモーダル入力を除去する -- structured JSON 出力をサポートしないプロバイダでは、無効な JSON が出力される場合がある点に注意する \ No newline at end of file +- サポートされていない `tools` を理解しないプロバイダに送らない +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングする +- 構造化された JSON 出力をサポートしないプロバイダは、無効な JSON を生成することがある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index df23aa8fd..0e53e75bc 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,31 +2,31 @@ 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 モデルを利用できるようにしました。 ## セットアップ -`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 +`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください: ```bash pip install "openai-agents[litellm]" ``` -完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +完了したら、任意の エージェント で [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 ## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます。 +これは完全に動作するサンプルです。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます: -- `openai/gpt-4.1` をモデルにし、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 providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 @@ -76,9 +76,9 @@ if __name__ == "__main__": asyncio.run(main(model, api_key)) ``` -## 使用状況データの追跡 +## 利用データのトラッキング -LiteLLM のレスポンスで Agents SDK の使用状況メトリクスを埋めたい場合は、エージェント作成時に `ModelSettings(include_usage=True)` を渡してください。 +LiteLLM のレスポンスを Agents SDK の利用状況メトリクスに反映させるには、エージェント作成時に `ModelSettings(include_usage=True)` を渡してください。 ```python from agents import Agent, ModelSettings @@ -91,4 +91,4 @@ agent = Agent( ) ``` -`include_usage=True` の場合、LiteLLM のリクエストは、組み込みの OpenAI モデルと同様に `result.context_wrapper.usage` を通じてトークン数とリクエスト数を報告します。 \ No newline at end of file +`include_usage=True` を指定すると、LiteLLM のリクエストは組み込みの OpenAI モデルと同様に、`result.context_wrapper.usage` を通じてトークン数とリクエスト数を報告します。 \ No newline at end of file diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 7fd5df30f..aec3a7ad8 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、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたときに、LLM は自律的にタスクへの取り組み方を計画し、ツールを使って行動・データ取得を行い、ハンドオフを使ってサブエージェントにタスクを委譲できます。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 -- Web 検索でオンラインの情報を見つける -- ファイル検索と取得でプロプライエタリなデータや接続先を検索する +- Web 検索でオンライン情報を探す +- ファイル検索と取得でプロプライエタリなデータや接続を検索する - コンピュータ操作でコンピュータ上のアクションを実行する - コード実行でデータ分析を行う -- 計画立案・レポート作成などに優れた特化型エージェントへのハンドオフ +- 計画立案、レポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで LLM の知性に頼りたい場合に有効です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで LLM の知能に頼りたい場合に最適です。ここで重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、運用すべきパラメーターの範囲を明確にします。 -2. アプリを監視し、反復改善する。どこで問題が起きるかを把握し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもこなす汎用エージェントではなく、単一のタスクに特化して卓越したエージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。エージェントを訓練し、タスクの上達に役立ちます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、および準拠すべきパラメーターを明確にします。 +2. アプリを監視し、反復改善する。問題が起きる箇所を見極め、プロンプトを改善します。 +3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、またはエラーメッセージを与えて改善させます。 +4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越したエージェントを用意する。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練して、タスクの上達と改善を図れます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の面でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選びます。 -- 複数のエージェントを、あるエージェントの出力を次のエージェントの入力に変換することで連鎖させる。ブログ記事執筆のようなタスクを、リサーチ → アウトライン作成 → 本文執筆 → 批評 → 改善、という一連のステップに分解できます。 -- タスクを実行するエージェントと、それを評価・フィードバックするエージェントを `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで繰り返す。 -- 複数のエージェントを並列に実行する（例: Python の基本コンポーネントである `asyncio.gather` を利用）。互いに依存しない複数タスクがある場合、速度向上に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次のエージェントを選ぶといった使い方です。 +- 複数のエージェントを、あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事の作成のようなタスクを、リサーチ、アウトライン作成、本文作成、批評、改善という一連のステップに分解できます。 +- 実行役のエージェントと、その出力を評価してフィードバックを与えるエージェントを組み合わせ、評価者が基準を満たしたと判断するまで `while` ループで回す。 +- 複数のエージェントを並行実行する。例えば Python の基本コンポーネントである `asyncio.gather` を使う。互いに依存しない複数タスクがある場合、速度向上に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数のコーデ例があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) にいくつかの code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index b35a2a529..32faeda88 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -この作業は 1 回だけで済みます。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナルセッションを開始するたびに実行します。 +新しいターミナル セッションを開始するたびに実行します。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[これらの手順](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、名前、任意の config（例: `model_config`）で定義します。 +エージェントは instructions、名前、およびオプションの config（たとえば `model_config`）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## エージェントの追加 +## さらにいくつかのエージェントを追加 -追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加のコンテキストを提供します。 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各エージェントで、タスクを進める方法を決める際に選択できる、送出側ハンドオフのオプションの一覧を定義できます。 +各エージェントごとに、そのエージェントがタスクを進める方法を判断する際に選択できる、送信側ハンドオフ オプションの一覧を定義できます。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## エージェントオーケストレーションの実行 -ワークフローが実行され、振り分け用エージェントが 2 つの専門エージェント間で正しくルーティングすることを確認しましょう。 +ワークフローが実行され、トリアージ エージェントが 2 つの専門エージェント間を正しくルーティングすることを確認しましょう。 ```python from agents import 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 ダッシュボードの [Trace viewer](https://platform.openai.com/traces) に移動し、実行のトレースを表示します。 +エージェント実行中に起きたことを確認するには、OpenAI ダッシュボードの Trace viewer に移動して、エージェントの実行のトレースを表示します。 ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう: +より複雑なエージェント フローの構築方法を学びましょう。 -- [エージェント](agents.md) の設定方法を学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [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 dd90bd685..49baa2381 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の realtime 機能を使って音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK のリアルタイム機能を用いて、音声対応の AI エージェントを構築する方法を詳しく説明します。 -!!! warning "Beta feature" -Realtime エージェントはベータ版です。実装の改善に伴い、非互換の変更が入る可能性があります。 +!!! warning "ベータ機能" +リアルタイムエージェントはベータ版です。実装の改善に伴い、互換性に影響する変更が入る可能性があります。 ## 概要 -Realtime エージェントは、音声とテキストの入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを可能にします。OpenAI の Realtime API との永続的な接続を維持し、低遅延で自然な音声対話と、割り込みへの優雅な対応を実現します。 +リアルタイムエージェントは、音声とテキスト入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを可能にします。OpenAI の Realtime API と持続的に接続し、低レイテンシで自然な音声対話や割り込みへの優雅な対応を実現します。 ## アーキテクチャ ### コアコンポーネント -realtime システムは、次の主要コンポーネントで構成されます。 +リアルタイムシステムは、いくつかの主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェントです。 -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに 1 つ作成し、会話が終了するまで存続させます。 -- **RealtimeModel**: 基盤となるモデルインターフェイスです（通常は OpenAI の WebSocket 実装）。 +- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデルインターフェイス（通常は OpenAI の WebSocket 実装） ### セッションフロー -一般的な realtime セッションは次の流れに従います。 +一般的なリアルタイムセッションは次のフローに従います。 -1. **RealtimeAgent を作成** し、instructions、tools、handoffs を設定します。 +1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 2. **RealtimeRunner をセットアップ** し、エージェントと設定オプションを指定します。 -3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返ります。 +3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返されます。 4. **音声またはテキストメッセージを送信** します。`send_audio()` または `send_message()` を使用します。 -5. **イベントをリッスン** します。セッションを反復処理して、音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーなどのイベントを受け取ります。 -6. **割り込みに対応** します。ユーザーがエージェントの発話に重ねて話した場合、現在の音声生成は自動的に停止します。 +5. **イベントをリッスン** します。セッションを反復処理してイベントを受け取ります。イベントには、音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. **割り込みに対応** します。ユーザーがエージェントの発話中に話し始めると、現在の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、realtime モデルとの永続的な接続を管理します。 +セッションは会話履歴を保持し、リアルタイムモデルとの持続的な接続を管理します。 ## エージェントの設定 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつかの重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] のリファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェントではなくセッション単位で設定します。 -- structured output はサポートされません（`outputType` は非対応）。 -- 音声はエージェント単位で設定できますが、最初のエージェントが話し始めた後は変更できません。 -- その他の機能（tools、handoffs、instructions）は同様に動作します。 +- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 +- structured outputs はサポートされません（`outputType` はサポート対象外）。 +- ボイスはエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 +- それ以外の機能（tools、ハンドオフ、instructions）は同様に機能します。 ## セッションの設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-realtime` など）、音声選択（ alloy、echo、fable、onyx、nova、shimmer ）、対応モダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の両方で設定可能で、既定は PCM16 です。 +セッション設定により、基盤となるリアルタイムモデルの動作を制御できます。モデル名（例: `gpt-realtime`）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力と出力の両方に設定可能で、既定は PCM16 です。 ### 音声設定 -音声設定では、セッションの音声入力・出力の扱いを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、特定領域の用語に対する精度向上のための文字起こしプロンプトを設定できます。ターン検出の設定では、音声活動検出のしきい値、無音時間、検出した発話の前後のパディングなどにより、エージェントがいつ応答を開始・終了するかを制御します。 +音声設定は、セッションが音声入力と出力をどのように扱うかを制御します。Whisper のようなモデルを用いた入力音声の文字起こし、言語設定、およびドメイン固有用語の精度向上のための文字起こしプロンプトを指定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出された発話周辺のパディングなど、エージェントが応答を開始・停止するタイミングを調整できます。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします。 +通常のエージェントと同様に、リアルタイムエージェントは会話中に実行される 関数ツール をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、専門特化したエージェント間で会話を引き継げます。 +ハンドオフにより、会話を専門特化したエージェント間で引き継ぐことができます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーミングし、セッションオブジェクトを反復処理してリッスンできます。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始・終了、エージェントのハンドオフ、エラーが含まれます。主に対応すべきイベントは以下です。 +セッションは、セッションオブジェクトを反復処理することでリッスンできるイベントをストリーミングします。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に扱うべき主なイベントは以下です。 -- **audio**: エージェントの応答からの raw な音声データ -- **audio_end**: エージェントの発話が終了しました -- **audio_interrupted**: ユーザーがエージェントを割り込みました -- **tool_start/tool_end**: ツール実行のライフサイクル -- **handoff**: エージェントのハンドオフが発生しました -- **error**: 処理中にエラーが発生しました +- **audio**: エージェントの応答からの raw 音声データ +- **audio_end**: エージェントの発話が終了 +- **audio_interrupted**: ユーザーがエージェントを割り込み +- **tool_start/tool_end**: ツール実行のライフサイクル +- **handoff**: エージェントのハンドオフが発生 +- **error**: 処理中にエラーが発生 -イベントの詳細は、[`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +イベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -realtime エージェントでサポートされるのは出力ガードレールのみです。パフォーマンス低下を避けるため、これらのガードレールはデバウンスされ、リアルタイム生成中に（毎語ではなく）定期的に実行されます。既定のデバウンス長は 100 文字ですが、変更可能です。 +リアルタイムエージェントでサポートされるのは出力ガードレールのみです。パフォーマンス問題を避けるため、これらのガードレールはデバウンスされ、（毎語ではなく）定期的に実行されます。既定のデバウンス長は 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` イベントが生成され、エージェントの現在の応答を中断することがあります。デバウンス動作は、安全性とリアルタイム性能要件のバランスに役立ちます。テキストエージェントと異なり、リアルタイムエージェントはガードレールが作動しても例外を発生させません。 ## 音声処理 -[`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] インターフェイスへ直接アクセスできます。 ## コード例 -動作する完全なコード例は、[examples/realtime directory](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI コンポーネントあり/なしのデモが含まれます。 \ 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 5ab822653..41e7c5841 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,20 +4,20 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントと音声で会話できるようにします。本ガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声会話を可能にします。このガイドでは、最初の Realtime 音声エージェントの作成手順を説明します。 -!!! warning "Beta feature" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的な変更が発生する可能性があります。 +!!! warning "ベータ機能" +Realtime エージェントはベータ版です。実装の改良に伴い、互換性のない変更が発生する可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK に関する基本的な理解 ## インストール -まだの場合は、OpenAI Agents SDK をインストールします: +まだの場合は、OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents @@ -109,9 +109,9 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 完全なコード例 +## 完全なサンプルコード -以下は動作する完全な例です: +動作する完全なサンプルコードは次のとおりです: ```python import asyncio @@ -192,34 +192,34 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択（例: `gpt-realtime`） -- `voice`: 音声の選択（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） -- `modalities`: テキストまたは音声を有効化（`["text"]` または `["audio"]`） +- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-realtime`) +- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`) ### 音声設定 -- `input_audio_format`: 入力音声のフォーマット（`pcm16`、`g711_ulaw`、`g711_alaw`） -- `output_audio_format`: 出力音声のフォーマット -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力音声の形式 +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法（`server_vad`、`semantic_vad`） -- `threshold`: 音声活動のしきい値（0.0–1.0） -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前の音声パディング +- `type`: 検出方式 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動のしきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [realtime エージェントの詳細](guide.md) -- 動作するサンプルは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダを参照してください -- エージェントにツールを追加する -- エージェント間のハンドオフを実装する -- 安全性のためのガードレールを設定する +- [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" diff --git a/docs/ja/release.md b/docs/ja/release.md index 420ce52a2..2906d3001 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,17 +4,17 @@ search: --- # リリースプロセス/変更履歴 -本プロジェクトは、`0.Y.Z` という形式の、やや修正したセマンティック バージョニングに従います。先頭の 0 は、 SDK が依然として急速に進化していることを示します。各コンポーネントは以下のように増分します。 +このプロジェクトは、`0.Y.Z` という形式のやや変更されたセマンティック バージョニングに従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増加させます。 ## マイナー (`Y`) バージョン -ベータとしてマークされていない公開インターフェースに対する **破壊的変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には、破壊的変更が含まれる可能性があります。 +ベータではない公開インターフェースに対する**破壊的変更**がある場合、マイナー バージョン `Y` を上げます。例えば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで 0.0.x バージョンに固定することをお勧めします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 ## パッチ (`Z`) バージョン -非破壊的な変更については `Z` を増分します。 +非破壊的変更には `Z` を増やします。 - バグ修正 - 新機能 @@ -25,8 +25,8 @@ search: ### 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] に `run_context` と `agent` という 2 つの新しい params が追加されました。`MCPServer` を継承するすべてのクラスに、これらの params を追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 4d21fc95c..e84d776a2 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 d01c71936..20a19d081 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 実行結果 +# 結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: +`Runner.run` メソッドを呼び出すと、以下のいずれかが返ります: -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- [`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] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は `last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `output_type` が定義されていない場合は `str` +- エージェントに出力タイプが定義されている場合は、`last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフがあるため、静的に型付けできません。ハンドオフが発生すると、任意のエージェントが最後のエージェントになり得るため、可能な出力タイプの集合を静的には把握できません。 + `final_output` は `Any` 型です。ハンドオフ のため、静的型付けはできません。ハンドオフ が発生すると、どのエージェントでも最後になり得るため、可能な出力タイプの集合を静的には特定できません。 ## 次ターンの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、もともと渡した入力に、エージェントの実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、あるエージェントの出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが簡単になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、元の入力とエージェント実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが簡単になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次に ユーザー が入力する際に役立つことがよくあります。例えば、フロントラインの振り分けエージェントが言語別のエージェントにハンドオフする場合、最後のエージェントを保存しておき、次回 ユーザー がエージェントにメッセージを送るときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が入力する際にこれが役立つことが多いです。例えば、一次対応のトリアージ エージェントが言語特化の エージェントにハンドオフ する場合、最後のエージェントを保存しておき、次に ユーザー がエージェントにメッセージを送るときに再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。Run item は LLM が生成した raw アイテムを包むラッパーです。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツールの応答です。アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM のツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフ が発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース／ターゲットのエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツールの応答です。アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 ### ガードレールの実行結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの実行結果（存在する場合）が含まれます。ガードレールの実行結果には、記録や保存に有用な情報が含まれることがあるため、参照できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレール の実行結果（存在する場合）が含まれます。ガードレール の結果には、ログや保存に有用な情報が含まれることがあるため、これらを利用できるようにしています。 -### raw レスポンス +### Raw 応答 [`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`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 f58f293c3..c67ca0c4e 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 を ストリーミング モードで呼び出し、受信したイベントを順次 ストリーミング します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリーミングします。 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳細は[結果ガイド](results.md)をご覧ください。 +詳しくは [実行結果ガイド](results.md) をご覧ください。 -## エージェントループ +## エージェントのループ -`Runner` の run メソッドを使用する際は、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）または入力アイテムのリスト（OpenAI Responses API のアイテム）です。 +`Runner` の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージとみなされます）か、OpenAI Responses API のアイテムのリストのいずれかです。 Runner は次のループを実行します。 -1. 現在のエージェントと現在の入力で LLM を呼び出します。 +1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し、結果を返します。 - 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新して、ループを再実行します。 - 3. LLM が ツール呼び出し を生成した場合、それらを実行し、結果を追記して、ループを再実行します。 + 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追加してループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、所望の型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、ツール呼び出しがない場合です。 ## ストリーミング -ストリーミング を使うと、LLM 実行中のイベントを逐次受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] に、その実行で生成されたすべての新規出力を含む、完全な情報が格納されます。ストリーミング イベントは `.stream_events()` を呼び出して受け取れます。詳細は[ストリーミング ガイド](streaming.md)をご覧ください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行の完全な情報が格納されます。ストリーミングイベントは `.stream_events()` を呼び出してください。詳しくは [ストリーミング ガイド](streaming.md) をご覧ください。 ## 実行設定 `run_config` パラメーターで、エージェント実行のグローバル設定を構成できます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関わらず、使用するグローバルな LLM モデルを設定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーで、既定は OpenAI です。 -- [`model_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]: 実行のトレーシング用 Workflow 名、Trace ID、Trace Group ID を設定します。少なくとも `workflow_name` の設定を推奨します。Group ID は任意で、複数実行にまたがるトレースを関連付けできます。 +- [`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(): @@ -91,9 +91,9 @@ async def main(): # California ``` -### Sessions による自動会話管理 +### Sessions による会話の自動管理 -より簡単な方法として、[Sessions](sessions.md) を使えば、`.to_input_list()` を手動で呼び出さずに会話履歴を自動処理できます。 +より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出さずに会話履歴を自動で扱えます。 ```python from agents import Agent, Runner, SQLiteSession @@ -120,23 +120,23 @@ async def main(): 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/) 連携を使うと、耐障害性があり長時間実行されるワークフロー（人間参加型のタスクを含む）を実行できます。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 c18b7dc7b..1897ea74f 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()` を扱う必要がなくなります。 -セッションは特定のセッションに対して会話履歴を保存し、明示的な手動メモリ管理なしで エージェント がコンテキストを維持できるようにします。これは、チャットアプリケーションや、過去のやり取りを エージェント に覚えておいてほしいマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッション用に会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -51,17 +51,17 @@ print(result.final_output) # "Approximately 39 million" セッションメモリを有効にすると: -1. **各実行の前**: ランナーがセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行の後**: 実行中に生成されたすべての新規アイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が自動的にセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、 エージェント がコンテキストを維持できます。 +1. **各実行の前**: ランナーはセッションの会話履歴を自動で取得し、入力アイテムの先頭に付加します。 +2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）はすべて自動的にセッションへ保存されます。 +3. **コンテキストの維持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出して会話状態を管理する必要がなくなります。 ## メモリ操作 ### 基本操作 -セッションは会話履歴を管理するためのいくつかの操作をサポートします: +セッションは会話履歴を管理するための複数の操作をサポートします: ```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 @@ -117,7 +117,7 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリオプション +## メモリのオプション ### メモリなし（デフォルト） @@ -129,7 +129,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 がホストするインフラに +すでに依存している場合に役立ちます。 ```python from agents import OpenAIConversationsSession @@ -188,13 +189,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 +216,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy エンジンの使用** +**例 2: 既存の SQLAlchemy エンジンを使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性があります。セッションに直接渡すことができます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っていることが多いでしょう。これをセッションに直接渡せます。 ```python import asyncio @@ -246,7 +247,7 @@ if __name__ == "__main__": ``` -## カスタムメモリ実装 +## 独自メモリ実装 [`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: @@ -295,19 +296,19 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすくする意味のあるセッション ID を使用します: +会話を整理するのに役立つ意味のあるセッション ID を使用します: - ユーザー基準: `"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)`）は、SQLAlchemy がサポートする既存データベースを用いる本番システム向け -- OpenAI ホスト型ストレージ（`OpenAIConversationsSession()`）は、履歴を OpenAI Conversations API に保存したい場合に使用 -- より高度なユースケースでは、他の本番システム（Redis、Django など）向けのカスタムセッションバックエンドの実装を検討 +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用 +- 既存のデータベースを持つ本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 +- 履歴を OpenAI Conversations API に保存したい場合は OpenAI ホスト型ストレージ（`OpenAIConversationsSession()`）を使用 +- さらに高度なユースケース向けに（Redis、Django など）他の本番システム向けのカスタムセッションバックエンドの実装を検討 ### セッション管理 @@ -335,7 +336,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリの動作を示す完全な例です: +セッションメモリが実際にどのように動作するかを示す完全な例です: ```python import asyncio @@ -399,9 +400,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 +- [`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 84f4c395c..73761f170 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 803ae3d86..0a6d7b012 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールはエージェントに行動を取らせます。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 つのツールのクラスがあります: +ツールは エージェント がアクションを実行するための手段です。たとえばデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータの使用まで可能です。 Agent SDK には 3 種類のツールがあります: -- Hosted tools: これは LLM サーバー上で AI モデルと並行して動作します。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 - Function Calling: 任意の Python 関数をツールとして使えます。 -- エージェントをツールとして: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せます。 +- ツールとしての エージェント: エージェント をツールとして使えます。これにより、ハンドオフなしで エージェント から他の エージェント を呼び出せます。 ## ホスト型ツール 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]: サンドボックス環境で LLM がコードを実行できます。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool]: リモートの MCP サーバーのツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]: プロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool]: あなたのマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして使えます。Agents SDK がツールを自動的にセットアップします: +任意の Python 関数をツールとして使用できます。 Agents SDK がツールを自動的にセットアップします: -- ツール名は Python 関数名になります（任意で名前を指定可能） -- ツールの説明は関数の docstring から取得します（任意で説明を指定可能） +- ツール名は Python 関数名になります（任意の名前を指定することも可能） +- ツールの説明は関数の docstring から取得されます（説明を指定することも可能） - 関数入力のスキーマは関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り関数の docstring から取得します +- 各入力の説明は、無効化しない限り、関数の docstring から取得されます -Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成します。 +関数シグネチャの抽出には Python の `inspect` モジュールを、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ生成には `pydantic` を使用しています。 ```python import json @@ -102,10 +102,10 @@ for tool in agent.tools: ``` -1. 任意の Python 型を関数の引数に使え、関数は同期・非同期どちらでも構いません。 -2. docstring がある場合は、説明や引数の説明の取得に使用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名や説明、docstring スタイルなどの上書き設定も可能です。 -4. デコレートした関数をツールのリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期のどちらでも構いません。 +2. docstring が存在する場合、説明文および引数の説明の取得に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。また、ツール名や説明、使用する docstring スタイルなどのオーバーライドも設定できます。 +4. デコレートした関数をツール一覧に渡せます。 ??? note "出力を表示" @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。代わりに直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。その場合、以下を指定する必要があります: +Python 関数をツールとして使いたくない場合もあります。必要に応じて直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: - `name` - `description` -- 引数の JSON スキーマである `params_json_schema` -- [`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力の文字列を返す非同期関数 `on_invoke_tool` +- `params_json_schema`（引数の JSON スキーマ） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と、JSON 文字列の引数を受け取り、ツールの出力を文字列で返す非同期関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。注意点: +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足: -1. シグネチャ解析は `inspect` モジュールで行います。引数型は型アノテーションから理解し、全体のスキーマを表現する Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 +1. シグネチャ解析は `inspect` モジュール経由で行います。型アノテーションを用いて引数の型を理解し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など大半の型をサポートします。 +2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。形式の自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することも可能です。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## エージェントをツールとして +## ツールとしてのエージェント -一部のワークフローでは、ハンドオフせずに中央のエージェントが専門エージェント群の連携をオーケストレーションしたい場合があります。エージェントをツールとしてモデル化することで実現できます。 +一部のワークフローでは、ハンドオフせずに中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。これは エージェント をツールとしてモデル化することで実現できます。 ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツール化したエージェントのカスタマイズ +### ツール化エージェントのカスタマイズ -`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための便宜メソッドです。ただし、すべての設定をサポートしているわけではありません。例えば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 Runner.run を使用してください: +`agent.as_tool` 関数は、エージェント をツールに変換しやすくするための簡便メソッドです。ただし、すべての設定に対応しているわけではありません。例えば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### カスタム出力抽出 -場合によっては、中央のエージェントに返す前に、ツール化したエージェントの出力を変更したいことがあります。例えば次のような場合に有用です: +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に有用です: -- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 -- エージェントの最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 -- 出力を検証し、応答が欠落している、または不正な場合にフォールバック値を提供する。 +- サブ エージェント のチャット履歴から特定情報（例: JSON ペイロード）を抽出する。 +- エージェント の最終回答を変換または再整形する（例: Markdown をプレーンテキストや CSV に変換）。 +- 出力を検証し、応答が欠落または不正な場合にフォールバック値を提供する。 -これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで行えます: +これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 条件付きツール有効化 -実行時に `is_enabled` パラメーターを使用して、エージェントのツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザーの嗜好、実行時の条件に基づいて、LLM に提供するツールを動的に絞り込めます。 +実行時に `is_enabled` パラメーターを使って、エージェント ツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザーの嗜好、実行時条件に基づいて、LLM に提供するツールを動的に絞り込めます。 ```python import asyncio @@ -373,23 +373,23 @@ asyncio.run(main()) ``` `is_enabled` パラメーターは次を受け付けます: -- **ブーリアン値**: `True`（常に有効）または `False`（常に無効） -- **呼び出し可能関数**: `(context, agent)` を受け取りブール値を返す関数 -- **非同期関数**: 複雑な条件ロジックのための非同期関数 +- **ブール値**: `True`（常に有効）または `False`（常に無効） +- **呼び出し可能関数**: `(context, agent)` を受け取り、真偽値を返す関数 +- **非同期関数**: 複雑な条件ロジック用の async 関数 無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: -- ユーザー権限に基づく機能のゲーティング -- 環境別のツール可用性（開発 vs 本番） -- 異なるツール構成の A/B テスト +- ユーザー権限に基づく機能ゲーティング +- 環境別のツール提供（開発 vs 本番） +- ツール構成の 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 8dfd383f4..8262797d3 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` に設定して無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます + 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシーの下で利用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース (Traces)** は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されます。トレースには次のプロパティがあります: - - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - - `trace_id`: トレースの一意の ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースを関連付けます。例えば、チャットスレッド ID を使用できます。 - - `disabled`: True の場合、このトレースは記録されません。 - - `metadata`: トレースの任意のメタデータ。 -- **スパン (Spans)** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: +- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。複数のスパンで構成されます。トレースには次のプロパティがあります: + - `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 の生成に関する情報などを含みます。 + - スパンに関する情報である `span_data`。例えば、`AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報などが含まれます。 -## 既定のトレーシング +## デフォルトのトレーシング デフォルトでは、SDK は次をトレースします: -- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます。 +- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます - エージェントが実行されるたびに、`agent_span()` でラップされます -- LLM の生成は `generation_span()` でラップされます -- 関数ツールの呼び出しは、それぞれ `function_span()` でラップされます +- LLM 生成は `generation_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます - ガードレールは `guardrail_span()` でラップされます - ハンドオフは `handoff_span()` でラップされます -- 音声入力（音声認識）は `transcription_span()` でラップされます -- 音声出力（音声合成）は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の子になる場合があります +- 音声入力（音声→テキスト）は `transcription_span()` でラップされます +- 音声出力（テキスト→音声）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合にこの名前を設定できます。または、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 +デフォルトのトレース名は "Agent workflow" です。`trace` を使う場合にこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 -さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、他の宛先にトレースを送信できます（置き換えとして、またはセカンダリ宛先として）。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、他の送信先へトレースを送ることができます（置き換え、またはセカンダリ送信先として）。 ## 上位レベルのトレース -複数の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、全体のコードを `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,47 +64,47 @@ 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 つあります: +[`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` には、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。`BackendSpanExporter` はスパンとトレースを OpenAI のバックエンドにバッチでエクスポートします。 +- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、これがトレースの作成を担当します。 +- `TraceProvider` には [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、これはトレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。エクスポーターはスパンとトレースを OpenAI バックエンドにバッチでエクスポートします。 -このデフォルト設定をカスタマイズして、別のバックエンドや追加のバックエンドにトレースを送信したり、エクスポーターの挙動を変更したりするには、次の 2 つの方法があります: +このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第受け取る、**追加の** トレース プロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を実行できます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレース プロセッサーに**置き換え**られます。つまり、OpenAI のバックエンドにトレースが送られるのは、そうする `TracingProcessor` を含めた場合に限られます。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備できた時点で受け取る「追加の」トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに「置き換え」られます。これは、OpenAI バックエンドに送信する `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送られないことを意味します。 -## 非 OpenAI モデルでのトレーシング +## OpenAI 以外のモデルでのトレーシング -OpenAI の API キーを非 OpenAI モデルと併用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 +OpenAI の API キーを非 OpenAI モデルで使用すると、トレーシングを無効化せずに OpenAI の Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -125,11 +125,10 @@ agent = Agent( ) ``` -## 注記 -- Openai Traces ダッシュボードで無料トレースを表示します。 +## 備考 +- 無料のトレースは OpenAI Traces ダッシュボードで確認できます。 - -## 外部トレーシング プロセッサー一覧 +## 外部トレーシングプロセッサー一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) diff --git a/docs/ja/usage.md b/docs/ja/usage.md index aa43c3731..f74472055 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -2,23 +2,23 @@ search: exclude: true --- -# 使用状況 +# 利用状況 -Agents SDK は各 run のトークン使用状況を自動で追跡します。run のコンテキストから参照でき、コストの監視、上限の適用、分析の記録に利用できます。 +Agents SDK は各ランのトークン利用状況を自動で追跡します。ランのコンテキストから参照でき、コストの監視、上限の適用、分析記録に活用できます。 ## 追跡対象 -- **requests**: 実行された LLM API 呼び出しの回数 +- **requests**: 行われた LLM API 呼び出し回数 - **input_tokens**: 送信された入力トークンの合計 - **output_tokens**: 受信した出力トークンの合計 -- **total_tokens**: input + output +- **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) ``` -使用状況は run 中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）を集計します。 +利用状況は、ラン中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 -### LiteLLM モデルでの使用状況の有効化 +### LiteLLM モデルでの usage 有効化 -LiteLLM プロバイダーはデフォルトでは使用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡すと、LiteLLM のレスポンスが `result.context_wrapper.usage` に反映されます。 +LiteLLM プロバイダーは既定では利用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡して、LiteLLM のレスポンスが `result.context_wrapper.usage` を埋めるようにします。 ```python from agents import Agent, ModelSettings, Runner @@ -50,9 +50,9 @@ result = await Runner.run(agent, "What's the weather in Tokyo?") print(result.context_wrapper.usage.total_tokens) ``` -## セッションでの使用状況の取得 +## セッションでの利用状況へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しはその特定の run の使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各 run の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その特定のランの利用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各ランの利用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -64,11 +64,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -セッションは run 間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、その実行のみを表します。セッションでは、前のメッセージが各 run の入力として再投入されることがあり、その結果、後続ターンの入力トークン数に影響します。 +セッションはラン間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される利用状況メトリクスは、その実行のみを表します。セッションでは前のメッセージが各ランに入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 -## フックでの使用状況の利用 +## フックでの利用状況の利用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクルのタイミングで使用状況を記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なポイントで利用状況を記録できます。 ```python class MyHooks(RunHooks): @@ -79,8 +79,8 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは以下を参照してください。 +詳細な API ドキュメントは次をご覧ください: -- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - run コンテキストから使用状況へアクセス -- [`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 902127289..9f3cfd7dd 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]" @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は有向グラフを作成し、次を表します: +`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックス。 -- **MCP サーバー** は灰色のボックス。 -- **ツール** は緑色の楕円。 -- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジ。 +- **エージェント** は黄色のボックスとして表されます。 +- **MCP サーバー** は灰色のボックスとして表されます。 +- **ツール** は緑色の楕円として表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへの有向辺として表されます。 ### 使用例 @@ -69,37 +69,36 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これは、 **トリアージ エージェント** と、そのサブエージェントやツールへの接続の構造を視覚的に表すグラフを生成します。 +これにより、**トリアージ エージェント** の構造と、そのサブエージェントやツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されたグラフには次が含まれます: +生成されるグラフには次が含まれます: -- エントリーポイントを示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた **長方形** で表されるエージェント。 -- 緑で塗りつぶされた **楕円** で表されるツール。 -- 灰色で塗りつぶされた **長方形** で表される MCP サーバー。 -- 相互作用を示す有向エッジ: +- 入口を示す **開始ノード**（`__start__`）。 +- 黄色で塗りつぶされた **長方形** としてのエージェント。 +- 緑色で塗りつぶされた **楕円** としてのツール。 +- 灰色で塗りつぶされた **長方形** としての MCP サーバー。 +- 相互作用を示す有向辺: - エージェント間のハンドオフには **実線の矢印**。 - ツール呼び出しには **点線の矢印**。 - MCP サーバー呼び出しには **破線の矢印**。 -- 実行終了箇所を示す **終了ノード** (`__end__`)。 +- 実行の終了箇所を示す **終了ノード**（`__end__`）。 -**注:** MCP サーバーは、最近の -`agents` パッケージのバージョン（ **v0.2.8** で確認済み）でレンダリングされます。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**Note:** 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 ae0062863..8ce4a09f1 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント主導のワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声化までを処理します。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント的なワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声に戻す処理まで担当します。 ```mermaid graph LR @@ -34,28 +34,28 @@ graph LR ## パイプラインの設定 -パイプライン作成時に、以下を設定できます: +パイプラインを作成する際には、次の項目を設定できます。 -1. 各音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +1. 新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] 2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル -3. 次のような項目を設定できる [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - - モデル名をモデルにマッピングできるモデルプロバイダー - - トレーシング（トレーシングの無効化可否、音声ファイルのアップロード可否、ワークフロー名、トレース ID など） - - プロンプト、言語、使用するデータ型など、TTS と STT モデルの設定 +3. 次のような設定を可能にする [`config`][agents.voice.pipeline_config.VoicePipelineConfig] + - モデル名をモデルへマッピングできるモデルプロバイダー + - トレーシング（トレーシングの無効化可否、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） + - プロンプト、言語、使用するデータ型などの TTS と STT のモデル設定 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます: +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の文字起こしがある場合に、その結果だけを生成したいときに使用します。話者が話し終えたタイミングの検出が不要なケース、たとえば事前録音の音声や、ユーザーが話し終えるタイミングが明確なプッシュ・トゥ・トークのアプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングを検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、音声パイプラインは「activity detection（音声アクティビティ検出）」と呼ばれるプロセスを通じて、適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声を書き起こしたテキストがあり、その結果だけを生成したい場合に使用します。これは、発話の終了検出が不要なケース、たとえば事前録音の音声や、ユーザーの発話終了が明確なプッシュ・トゥ・トークのアプリで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、ボイスパイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて適切なタイミングでエージェントのワークフローを自動実行します。 ## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントを順次ストリーミングできるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] にはいくつかの種類があり、たとえば次のものがあります: +ボイスパイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 1. 音声チャンクを含む [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] -2. ターンの開始・終了などライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] +2. ターンの開始や終了などのライフサイクルイベントを知らせる [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 3. エラーイベントである [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み機能をサポートしていません。代わりに、検出された各ターンごとにワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みに対応したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンのすべての音声が送出された後にトリガーされます。これらのイベントを利用して、モデルがターンを開始したときに話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュし終えた後にミュートを解除する、といった制御が可能です。 \ No newline at end of file +Agents SDK は現時点で、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みに対応したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] のイベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンの音声がすべてディスパッチされた後にトリガーされます。これらのイベントを用いて、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にアンミュートする、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 39b112f27..4231f68e5 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK のベースの[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしていることを確認します。次に、SDK から音声向けのオプション依存関係をインストールします。 +Agents SDK の[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声向けの任意依存関係をインストールします: ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです。 +ここで知っておくべき主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスです: -1. 音声をテキストに変換するために音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行して結果を生成します。 -3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 +1. 音声をテキストに変換する音声認識モデルを実行します。 +2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。 +3. 結果のテキストを音声に戻す音声合成モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントをセットアップします。これは、この SDK でエージェントを作成したことがあれば見覚えがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 +まずエージェントをいくつか設定します。既にこの SDK でエージェントを作成したことがあれば、馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -76,7 +76,7 @@ spanish_agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. Speak in Spanish.", ), - model="gpt-4o-mini", + model="gpt-4.1", ) agent = Agent( @@ -84,7 +84,7 @@ agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", ), - model="gpt-4o-mini", + model="gpt-4.1", handoffs=[spanish_agent], tools=[get_weather], ) @@ -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 @@ -160,7 +160,7 @@ spanish_agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. Speak in Spanish.", ), - model="gpt-4o-mini", + model="gpt-4.1", ) agent = Agent( @@ -168,7 +168,7 @@ agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", ), - model="gpt-4o-mini", + model="gpt-4.1", handoffs=[spanish_agent], tools=[get_weather], ) @@ -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 b2d154d68..753580a1e 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -6,13 +6,13 @@ search: [エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレーシングされます。 -基本的なトレーシング情報は上記ドキュメントをご参照ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを設定できます。 +基本的なトレーシング情報は上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを構成できます。 -トレーシングに関する主なフィールドは次のとおりです。 +主なトレーシング関連フィールドは次のとおりです。 -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかを制御します。既定では有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機微なデータをトレースに含めるかを制御します。これは音声パイプライン専用で、ワークフロー内部で起こることには適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 音声データをトレースに含めるかを制御します。 +- [`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 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file diff --git a/docs/mcp.md b/docs/mcp.md index e06bbf873..4ee7b5781 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -188,7 +188,7 @@ If the MCP server implements the HTTP with SSE transport, instantiate from agents import Agent, Runner from agents.model_settings import ModelSettings -from mcp import MCPServerSse +from agents.mcp import MCPServerSse workspace_id = "demo-workspace" diff --git a/docs/voice/quickstart.md b/docs/voice/quickstart.md index 896ffe839..bb3a02be7 100644 --- a/docs/voice/quickstart.md +++ b/docs/voice/quickstart.md @@ -72,7 +72,7 @@ spanish_agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. Speak in Spanish.", ), - model="gpt-4o-mini", + model="gpt-4.1", ) agent = Agent( @@ -80,7 +80,7 @@ agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", ), - model="gpt-4o-mini", + model="gpt-4.1", handoffs=[spanish_agent], tools=[get_weather], ) @@ -156,7 +156,7 @@ spanish_agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. Speak in Spanish.", ), - model="gpt-4o-mini", + model="gpt-4.1", ) agent = Agent( @@ -164,7 +164,7 @@ agent = Agent( instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", ), - model="gpt-4o-mini", + model="gpt-4.1", handoffs=[spanish_agent], tools=[get_weather], ) diff --git a/examples/basic/lifecycle_example.py b/examples/basic/lifecycle_example.py index 1429872b8..874ff629b 100644 --- a/examples/basic/lifecycle_example.py +++ b/examples/basic/lifecycle_example.py @@ -4,10 +4,36 @@ from pydantic import BaseModel -from agents import Agent, RunContextWrapper, RunHooks, Runner, Tool, Usage, function_tool +from agents import ( + Agent, + AgentHooks, + RunContextWrapper, + RunHooks, + Runner, + Tool, + Usage, + function_tool, +) from agents.items import ModelResponse, TResponseInputItem +class LoggingHooks(AgentHooks[Any]): + async def on_start( + self, + context: RunContextWrapper[Any], + agent: Agent[Any], + ) -> None: + print(f"#### {agent.name} is starting.") + + async def on_end( + self, + context: RunContextWrapper[Any], + agent: Agent[Any], + output: Any, + ) -> None: + print(f"#### {agent.name} produced output: {output}.") + + class ExampleHooks(RunHooks): def __init__(self): self.event_counter = 0 @@ -92,6 +118,7 @@ class FinalResult(BaseModel): instructions="Multiply the number by 2 and then return the final result.", tools=[multiply_by_two], output_type=FinalResult, + hooks=LoggingHooks(), ) start_agent = Agent( @@ -100,6 +127,7 @@ class FinalResult(BaseModel): tools=[random_number], output_type=FinalResult, handoffs=[multiply_agent], + hooks=LoggingHooks(), ) diff --git a/examples/voice/streamed/my_workflow.py b/examples/voice/streamed/my_workflow.py index 3cb804b0c..076abd2a3 100644 --- a/examples/voice/streamed/my_workflow.py +++ b/examples/voice/streamed/my_workflow.py @@ -21,7 +21,7 @@ def get_weather(city: str) -> str: instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. Speak in Spanish.", ), - model="gpt-4o-mini", + model="gpt-4.1", ) agent = Agent( @@ -29,7 +29,7 @@ def get_weather(city: str) -> str: instructions=prompt_with_handoff_instructions( "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", ), - model="gpt-4o-mini", + model="gpt-4.1", handoffs=[spanish_agent], tools=[get_weather], )