diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 8b504d6d9..a9bdaff0c 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェント は、アプリの中心的なビルディングブロックです。エージェント は、指示 (`instructions`) とツール (`tools`) で構成された LLM です。 +エージェントはアプリの中核を成す構成要素です。エージェントとは、 instructions と tools で構成された大規模言語モデル ( LLM ) です。 ## 基本設定 -エージェント で最もよく設定するプロパティは次のとおりです。 +もっとも一般的に設定するエージェントのプロパティは次のとおりです。 -- `name`: エージェント を識別する必須の文字列です。 -- `instructions`: 開発者メッセージ、または システムプロンプト とも呼ばれます。 -- `model`: 使用する LLM を指定します。`model_settings` を使って temperature、top_p などのモデル チューニング パラメーターを設定できます。 -- `tools`: エージェント がタスクを達成するために使用できるツールです。 +- `name` : エージェントを識別する必須の文字列です。 +- `instructions` : developer message または system prompt とも呼ばれます。 +- `model` : 使用する LLM を指定します。また、 `model_settings` を用いて temperature や top_p などのチューニングパラメーターを任意で設定できます。 +- `tools` : エージェントがタスクを遂行するために使用できる tools です。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェント はその `context` 型についてジェネリックです。コンテキストは dependency-injection 用のオブジェクトで、あなたが作成して `Runner.run()` に渡し、実行中のエージェント・ツール・ハンドオフ などすべてに共有されます。実行に必要な依存関係や状態をまとめて保持する入れ物として機能します。コンテキストには任意の Python オブジェクトを渡せます。 +エージェントは `context` 型についてジェネリックになっています。コンテキストは依存性注入のための仕組みで、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、 tool 、 handoff などへ引き渡され、実行時の依存関係や状態を保持する入れ物として機能します。任意の Python オブジェクトをコンテキストとして渡せます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェント はプレーンテキスト (つまり `str`) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用します。一般的には [ Pydantic ](https://docs.pydantic.dev/) オブジェクトを使いますが、Pydantic の [ TypeAdapter ](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型 (dataclass、list、TypedDict など) なら何でもサポートされています。 +デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型で出力させたい場合は、 `output_type` パラメーターを使用します。よく使われるのは Pydantic オブジェクトですが、Pydantic の TypeAdapter にラップできる型であれば何でもサポートしています。たとえば dataclass 、 list 、 TypedDict などです。 ```python from pydantic import BaseModel @@ -73,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキストではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 + `output_type` を渡すと、モデルは通常のプレーンテキストの代わりに structured outputs を使用するよう指示されます。 ## ハンドオフ -ハンドオフ は、エージェント が委譲できるサブエージェントです。ハンドオフ のリストを渡すことで、関連性がある場合にエージェント がそれらへ委譲できます。これは、単一タスクに特化したモジュール化 エージェント をオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) ドキュメントを参照してください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは状況に応じてそれらへ委譲できます。これは、単一のタスクに特化したモジュラーなエージェントを編成できる強力なパターンです。詳細は handoffs のドキュメントをご覧ください。 ```python from agents import Agent @@ -98,7 +98,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント 作成時に instructions を指定しますが、関数を使って動的に instructions を生成することもできます。この関数はエージェント と コンテキスト を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を使用できます。 +ほとんどの場合、エージェント作成時に instructions を渡しますが、関数を通じて動的に instructions を生成することもできます。その関数は agent と context を受け取り、プロンプトを返す必要があります。同期関数と async 関数の両方を指定できます。 ```python def dynamic_instructions( @@ -115,15 +115,15 @@ agent = Agent[UserContext]( ## ライフサイクルイベント (hooks) -エージェント のライフサイクルを観察したい場合があります。たとえば、イベントをログに残したり、特定のイベント発生時にデータを事前取得したりするケースです。`hooks` プロパティを使って エージェント のライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] を継承し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを監視したい場合があります。たとえば、イベントを記録したり、特定のイベントが起きた際にデータを事前取得したりするケースです。 `hooks` プロパティを使ってエージェントのライフサイクルにフックできます。 `AgentHooks` クラスを継承し、必要なメソッドをオーバーライドしてください。 ## ガードレール -ガードレール を使うと、エージェント 実行と並行してユーザー入力に対するチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をフィルタリングできます。詳細は [guardrails](guardrails.md) ドキュメントを参照してください。 +ガードレールを使うと、エージェントの実行と並行してユーザー入力のチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は guardrails のドキュメントを参照してください。 -## エージェントの複製とコピー +## エージェントのクローン／コピー -`clone()` メソッドを使用すると、エージェント を複製し、必要に応じて任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使うと、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、必ずしも LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。指定できる値は次のとおりです。 +tools のリストを渡しても、 LLM が必ずしもツールを使用するとは限りません。 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです: -1. `auto` : LLM がツールを使うかどうかを判断します。 -2. `required` : LLM にツール使用を必須とします (どのツールを使うかは自動判断)。 -3. `none` : LLM にツールを使用しないよう必須とします。 -4. 文字列を指定 (例: `my_tool`) : 指定したツールを必ず使用させます。 +1. `auto` : LLM がツールを使うかどうかを判断します。 +2. `required` : LLM にツール使用を必須とします ( どのツールを使うかは賢く選択されます )。 +3. `none` : LLM にツールを使用させません。 +4. 特定の文字列 ( 例 `my_tool` ) を設定すると、そのツールの使用を強制します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -165,10 +165,10 @@ agent = Agent( ## ツール使用の挙動 -`Agent` の `tool_use_behavior` パラメーターは、ツールの出力をどのように扱うかを制御します。 +`Agent` の `tool_use_behavior` パラメーターは、ツールの出力をどのように扱うかを制御します: -- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、追加の LLM 処理は行いません。 +- `"run_llm_again"` : デフォルト。ツールを実行し、その結果を LLM が処理して最終レスポンスを生成します。 +- `"stop_on_first_tool"` : 最初のツール呼び出しの出力をそのまま最終レスポンスとして使用し、以降 LLM は処理を行いません。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -186,7 +186,8 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールが呼び出された時点で停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])` : 指定したツールが呼び出された時点で停止し、その出力を最終レスポンスとして使用します。 + ```python from agents import Agent, Runner, function_tool from agents.agent import StopAtTools @@ -208,7 +209,8 @@ agent = Agent( tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを判断するカスタム関数です。 + +- `ToolsToFinalOutputFunction` : ツール結果を処理し、停止するか LLM を続行するかを判断するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -246,4 +248,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` により再びツール呼び出しが生成されることを繰り返すために発生します。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 773819404..119ad8792 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、 SDK はインポートされた直後に LLM へのリクエストとトレーシングのための `OPENAI_API_KEY` 環境変数を検索します。アプリ起動前にこの環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 +デフォルトでは、SDK はインポートされた直後に LLM リクエストとトレーシング用の `OPENAI_API_KEY` 環境変数を参照します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使ってキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -代わりに、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを使って `AsyncOpenAI` インスタンスを生成します。この動作は [set_default_openai_client()][agents.set_default_openai_client] 関数で変更できます。 +別の方法として、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数もしくは上記で設定したデフォルトキーを使って `AsyncOpenAI` インスタンスを生成します。[set_default_openai_client()][agents.set_default_openai_client] 関数を使用するとこれを変更できます。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を使用していますが、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API に変更できます。 +最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を利用しますが、[set_default_openai_api()][agents.set_default_openai_api] 関数を用いれば Chat Completions API に変更できます。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効です。デフォルトでは、上記セクションで説明した OpenAI API キー（環境変数または設定したデフォルトキー）が使用されます。トレーシングで使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。 +トレーシングはデフォルトで有効になっています。上記セクションで設定した OpenAI API キー（環境変数またはデフォルトキー）がそのまま使用されます。トレーシング専用の API キーを指定したい場合は、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化するには、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使います。 +トレーシングを完全に無効化したい場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用できます。 ```python from agents import set_tracing_disabled @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## デバッグロギング -SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーが `stdout` に送られ、その他のログは抑制されます。 +SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーが `stdout` に出力され、それ以外のログは抑制されます。 -詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 +詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) をご覧ください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python logging guide](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 8fda89181..5faa30abc 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,29 +4,30 @@ search: --- # コンテキスト管理 -コンテキスト (context) という言葉には複数の意味があります。ここでは、主に気に掛けるべきコンテキストには 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. そのオブジェクトを各種 run メソッドに渡します (例: `Runner.run(..., **context=whatever**)`)。 -3. すべてのツール呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、 `wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使うパターンが多いです。 +2. そのオブジェクトを各種 `run` メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 +3. すべてのツール呼び出しやライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -**最も重要なポイント**: 1 回のエージェント実行において、エージェント・ツール関数・ライフサイクルフックなどは、必ず同じ型のコンテキストを共有する必要があります。 +最も重要な点: ひとつのエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルフックは、同じ _型_ のコンテキストを使用しなければなりません。 -コンテキストは次のような用途に利用できます。 +コンテキストでできることの例: -- 実行に関するデータ (例: ユーザー名 / UID などの ユーザー 情報) -- 依存関係 (例: logger オブジェクトやデータフェッチャーなど) -- ヘルパー関数 +- 実行時の状況データ（ユーザー名 / UID などユーザーに関する情報） +- 依存関係（ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは **LLM に送信されません**。あくまでもローカルなオブジェクトであり、読み書きやメソッド呼び出しにのみ使用します。 + + コンテキストオブジェクトは **LLM に送信されません**。これはあくまでローカルオブジェクトであり、読み書きやメソッド呼び出しのみが可能です。 ```python import asyncio @@ -65,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型で構いません。 -2. これはツールです。 `RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. エージェントにジェネリック型 `UserInfo` を指定しているため、型チェッカーで (異なるコンテキスト型を受け取るツールを渡そうとした場合など) エラーを検出できます。 -4. `run` 関数にコンテキストを渡しています。 -5. エージェントはツールを正しく呼び出し、 age を取得します。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型で構いません。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照します。 +3. エージェントをジェネリック型 `UserInfo` でマークし、型チェッカーが誤りを検出できるようにします（例えば、異なるコンテキスト型を取るツールを渡した場合など）。 +4. `run` 関数にコンテキストを渡します。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM のコンテキスト +## エージェント／LLM コンテキスト -LLM が呼び出される際、 LLM が参照できるデータは会話履歴だけです。そのため、新しいデータを LLM に渡したい場合は、そのデータを会話履歴に組み込む必要があります。主な方法は次のとおりです。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴のみです。したがって、新しいデータを LLM に渡したい場合は、そのデータを会話履歴に含める必要があります。方法はいくつかあります。 -1. Agent の `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。 system prompt は固定の文字列でも、コンテキストを受け取って文字列を返す動的関数でもかまいません。ユーザー名や現在の日付など、常に有用な情報に適した方法です。 -2. `Runner.run` を呼び出す際に `input` に追加する。この方法は `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位レベルにメッセージを配置できます。 -3. function tools を通じて公開する。これはオンデマンドのコンテキストに適しており、 LLM が必要になったタイミングでツールを呼び出してデータを取得できます。 -4. retrieval や web search を使用する。これらはファイルやデータベースから関連データを取得する (retrieval) 、あるいは Web から取得する (web search) 特別なツールです。関連するコンテキストデータでレスポンスを「グラウンディング」するのに適しています。 \ No newline at end of file +1. エージェントの `instructions` に追加する。この部分は「システムプロンプト」または「developer message」とも呼ばれます。システムプロンプトは静的文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。ユーザー名や現在の日付など、常に有用な情報に一般的な手法です。 +2. `Runner.run` を呼び出す際の `input` に追加する。この方法は `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 上でより下位のメッセージとして扱えます。 +3. 関数ツールを通じて公開する。これはオンデマンドのコンテキストに便利です。LLM が必要と判断したときにツールを呼び出してデータを取得できます。 +4. リトリーバルや Web 検索を使用する。これらはファイルやデータベース（リトリーバル）あるいは Web（Web 検索）から関連データを取得できる特殊なツールです。関連コンテキストデータで応答を「グラウンディング」する際に有効です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 7aaf8b700..97acb93d9 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,45 +4,44 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションには、SDK のさまざまなサンプル実装が用意されています。これらのコード例は、異なるパターンや機能を示すいくつかのカテゴリーに整理されています。 - +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでは、さまざまな SDK のサンプル実装をご覧いただけます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例では、一般的なエージェント設計パターンを示しています。 + このカテゴリーのコード例では、一般的なエージェント設計パターンを示しています。例えば、 - - 決定的ワークフロー - - エージェントをツールとして利用 + - 決定論的ワークフロー + - ツールとしてのエージェント - エージェントの並列実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - このカテゴリーでは、SDK の基礎的な機能を紹介しています。 + 基本的な機能を示すコード例です。例えば、 - - 動的システムプロンプト - - ストリーミング出力 + - 動的な system prompt + - ストリーミング出力 - ライフサイクルイベント - **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索やファイル検索などの OpenAI がホストするツールを実装し、エージェントに統合する方法を学べます。 + OAI hosted tools である web search や file search を実装し、エージェントに統合する方法を学べます。 - **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを SDK で利用する方法を探求できます。 + OpenAI 以外のモデルを SDK と併用する方法を紹介しています。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフの実践例を確認できます。 + エージェントのハンドオフを実践的に示すコード例です。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP を使用したエージェントの構築方法を学べます。 + MCP を使ったエージェントの構築方法を学べます。 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 実際のユースケースを示す、さらに充実した 2 つの例です。 + 実際のユースケースを想定した、より発展的なコード例が含まれています。 - - **customer_service**: 航空会社向けのカスタマーサービス システムの例 - - **research_bot**: シンプルなディープリサーチ クローン + - **customer_service**: 航空会社向けのカスタマーサービスシステムの例 + - **research_bot**: シンプルなディープリサーチのクローン - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを使用した音声エージェントの例を確認できます。 + TTS および STT モデルを用いた音声エージェントのコード例です。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を用いてリアルタイム体験を構築する方法を示す例です。 \ No newline at end of file + SDK を使ってリアルタイム体験を構築する方法を示すコード例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index a218c8c11..0de7d5983 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,47 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並列_ で実行され、ユーザー入力のチェックとバリデーションを行うことができます。 -たとえば、非常に賢い（そのぶん遅く／高価な）モデルを使って顧客リクエストを処理するエージェントがあると想像してください。悪意のあるユーザーがこのモデルに数学の宿題を解かせようとするのは避けたいはずです。そこで、高速かつ低コストのモデルでガードレールを走らせます。ガードレールが悪用を検知した場合、即座にエラーを発生させることで高価なモデルの実行を止め、時間とコストを節約できます。 +Guardrails はエージェントと並行して実行され、ユーザー入力のチェックと検証を行えます。たとえば、非常に賢い（そのぶん遅く／高価な）モデルを使って顧客対応を行うエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を解かせようとするのは避けたいでしょう。そのために、より高速かつ低コストなモデルで動くガードレールを実行できます。ガードレールが悪意ある使用を検知した場合、即座にエラーを発生させることで高価なモデルの実行を止め、時間とコストを節約できます。 ガードレールには 2 種類あります。 -1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェント出力に対して実行されます +1. Input guardrails は初期ユーザー入力に対して実行されます +2. Output guardrails は最終的なエージェント出力に対して実行されます -## 入力ガードレール +## Input guardrails -入力ガードレールは 3 段階で実行されます。 +Input guardrails は次の 3 ステップで実行されます。 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの応答や例外処理を適切に行えます。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップします。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの応答や例外処理を適切に行えます。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントが *最初* のエージェントである場合にのみそのガードレールが実行されます。 - 「なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか？」と疑問に思うかもしれません。それは、ガードレールが実際の Agent に密接に関連しているからです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + Input guardrails はユーザー入力に対して実行されることを想定しているため、エージェントが *最初* のエージェントである場合のみ実行されます。「`guardrails` プロパティがエージェント側にあり、`Runner.run` で渡さないのはなぜか」と疑問に思うかもしれません。これはガードレールが実際のエージェントに密接に関連する傾向があるからです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くほうが読みやすくなります。 -## 出力ガードレール +## Output guardrails -出力ガードレールも 3 段階で実行されます。 +Output guardrails も 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 - 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントが *最後* のエージェントである場合にのみそのガードレールが実行されます。 - 入力ガードレールと同様に、ガードレールは実際の Agent に密接に関連しているため、コードを同じ場所に置くことで可読性が向上します。 + Output guardrails は最終的なエージェント出力に対して実行されることを想定しているため、エージェントが *最後* のエージェントである場合のみ実行されます。Input guardrails と同様に、ガードレールは実際のエージェントに関連する傾向があるため、コードを同じ場所に置くほうが読みやすくなります。 -## トリップワイヤー +## Tripwires -入力または出力がガードレールを通過できない場合、ガードレールはトリップワイヤーでその事実を通知できます。トリップワイヤーが発動したガードレールを検知した瞬間に `{Input,Output}GuardrailTripwireTriggered` 例外を直ちに送出し、エージェントの実行を停止します。 +入力または出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤーでそれを示します。トリップワイヤーが発動したガードレールを検知した時点で、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。以下の例では、この処理を内部でエージェントを実行する形で行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、その内部でエージェントを実行してガードレールを実装します。 ```python from pydantic import BaseModel @@ -99,10 +96,10 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力／コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果には追加情報を含めることができます。 -4. こちらがワークフローを定義する実際のエージェントです。 +3. ガードレール結果に追加情報を含めることができます。 +4. これがワークフローを定義する実際のエージェントです。 -出力ガードレールも同様です。 +Output guardrails も同様です。 ```python from pydantic import BaseModel @@ -155,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. こちらは実際のエージェントの出力型です。 -2. こちらはガードレールの出力型です。 +1. これは実際のエージェントの出力型です。 +2. これはガードレールの出力型です。 3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. こちらがワークフローを定義する実際のエージェントです。 \ No newline at end of file +4. これがワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index ee95a97f1..a00cbb9bd 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # ハンドオフ -ハンドオフを使用すると、あるエージェントが別のエージェントにタスクを委任できます。これは、エージェントごとに異なる分野を専門とさせたいシナリオで特に役立ちます。たとえば、カスタマーサポートアプリでは、注文状況、返金、 FAQ などのタスクをそれぞれ担当するエージェントを用意できます。 +ハンドオフを使用すると、エージェントはタスクを別のエージェントに委譲できます。これは、異なるエージェントがそれぞれ異なる分野を専門としているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に処理するエージェントがいる場合があります。 -ハンドオフは LLM に対してはツールとして表現されます。そのため、`Refund Agent` という名前のエージェントへのハンドオフであれば、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM からはツールとして認識されます。たとえば、`Refund Agent` というエージェントにハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、直接 `Agent` を渡すことも、ハンドオフをカスタマイズした `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持っており、ここには直接 `Agent` を渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、さらに任意でオーバーライドや入力フィルターを設定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、オーバーライドや入力フィルターをオプションで指定できます。 ### 基本的な使い方 -シンプルなハンドオフの例は次のとおりです: +以下のように、シンプルなハンドオフを作成できます。 ```python from agents import Agent, handoff @@ -28,17 +28,17 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のようにエージェントをそのまま渡すことも、`handoff()` 関数を使うこともできます。 +1. `billing_agent` のようにエージェントを直接指定することも、`handoff()` 関数を使用することもできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数では、次のようなカスタマイズが可能です。 -- `agent`: ハンドオフ先のエージェントを指定します。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使用され、`transfer_to_` という形式になります。ここで上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` で設定されるデフォルトのツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが実行されたと同時にデータ取得を開始するなどの用途に便利です。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御されます。 -- `input_type`: ハンドオフが受け取る入力の型 (任意)。 +- `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`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。 ```python @@ -59,7 +59,7 @@ handoff_obj = handoff( ## ハンドオフ入力 -場合によっては、ハンドオフを呼び出す際に LLM に何らかのデータを渡してほしいことがあります。たとえば「Escalation agent」へのハンドオフでは、ログ用に理由を記録したいかもしれません。 +状況によっては、ハンドオフを呼び出す際に LLM に何らかのデータを渡してほしい場合があります。たとえば、「エスカレーションエージェント」へのハンドオフでは、記録用に理由を受け取りたいことがあります。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を閲覧できるようになります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定してください。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、それまでの会話履歴をすべて閲覧できます。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定します。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] を受け取り、新しい `HandoffInputData` を返す関数です。 -よく使われるパターン (たとえば履歴からすべてのツール呼び出しを削除するなど) は、[`agents.extensions.handoff_filters`][] に実装されています。 +履歴からすべてのツール呼び出しを削除するなど、一般的なパターンはいくつかあり、[`agents.extensions.handoff_filters`][] に実装されています。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. これは `FAQ agent` が呼び出されたときに、履歴からすべてのツールを自動的に削除します。 +1. これにより、`FAQ agent` が呼び出された際に履歴からすべてのツールが自動的に削除されます。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるように、エージェントにハンドオフに関する情報を組み込むことをお勧めします。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨されるプレフィックスが用意されているほか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出すことで、プロンプトに推奨事項を自動で追加できます。 +LLM がハンドオフを正しく理解できるように、エージェントのプロンプトにハンドオフに関する情報を含めることを推奨します。推奨されるプレフィックスは [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に用意されており、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出すことで、自動で推奨データをプロンプトに追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 916ac10dd..9e97e61c7 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、非常に少ない抽象化でエージェント型 AI アプリを構築できる軽量で使いやすいパッケージです。これは、以前にエージェント向けに実験していた [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントが含まれています。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) を使用すると、抽象化を最小限に抑えた軽量で扱いやすいパッケージで、エージェント指向の AI アプリを構築できます。これは、以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番利用できるレベルへとアップグレードしたものです。Agents SDK には、基本コンポーネントがごくわずかしかありません。 -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委任する仕組み -- **ガードレール**: エージェントへの入力を検証する機構 -- **セッション**: エージェントの実行をまたいで会話履歴を自動管理 +- **エージェント**: instructions と tools を備えた LLM です +- **ハンドオフ**: エージェントが特定のタスクを他のエージェントへ委任できるしくみ +- **ガードレール**: エージェントへの入力を検証する機能 +- **セッション**: エージェントの実行をまたいで会話履歴を自動的に保持します -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなく実用的なアプリケーションを構築できます。さらに、SDK には **トレーシング** が組み込まれており、エージェントフローの可視化・デバッグ・評価や、アプリ向けモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントは tools とエージェント間の複雑な関係を表現できるだけの十分な力を持ち、急な学習コストなしに実用アプリを構築できます。さらに、SDK には組み込みの トレーシング があり、エージェントのフローを可視化・デバッグできるほか、評価やアプリ向けモデルのファインチューニングにも活用できます。 ## Agents SDK を使う理由 -SDK には次の 2 つの設計原則があります。 +SDK には、次の 2 つの設計原則があります: -1. 使う価値があるだけの機能を備えつつ、学習しやすいようにコンポーネント数を絞る。 -2. すぐに使い始められる一方で、挙動を細かくカスタマイズできる。 +1. 利用価値のある十分な機能を持ちながら、基本コンポーネントを絞り込むことで学習がすばやく済むこと。 +2. すぐに使えて高い性能を発揮しつつ、挙動を細部までカスタマイズできること。 -主な機能は以下のとおりです。 +SDK の主な機能は次のとおりです: -- エージェントループ: ツールの呼び出し、結果を LLM へ送信、LLM が完了するまでのループを自動で処理。 -- Python ファースト: 新しい抽象を学ばずに Python の言語機能でエージェントを編成・連鎖。 -- ハンドオフ: 複数エージェント間の協調や委任を実現する強力な機能。 -- ガードレール: エージェントと並列で入力の検証を実行し、失敗時には早期終了。 -- セッション: エージェント実行をまたいで会話履歴を自動管理し、状態管理の手間を排除。 -- 関数ツール: 任意の Python 関数を自動スキーマ生成と Pydantic 検証付きのツールに変換。 -- トレーシング: フローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツールを活用可能。 +- Agent ループ: tools の呼び出し、結果を LLM へ渡す処理、LLM が完了するまでのループを自動で実行します。 +- Python ファースト: 新しい抽象を覚えることなく、言語が元々備える機能でエージェントをオーケストレーションし、チェーンできます。 +- ハンドオフ: 複数のエージェント間の連携と委任を可能にする強力な機能です。 +- ガードレール: エージェントと並行して入力の検証を行い、チェックに失敗した場合は早期に処理を終了します。 +- セッション: エージェントの実行をまたいで会話履歴を自動管理し、状態を手動で扱う手間を排除します。 +- 関数ツール: 任意の Python 関数を tools に変換し、スキーマを自動生成して Pydantic ベースの検証を行います。 +- トレーシング: フローの可視化、デバッグ、モニタリングが行える組み込み機能。さらに OpenAI の評価、ファインチューニング、蒸留ツール群も利用できます。 ## インストール @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index f2342d57f..4ed357d4d 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -2,25 +2,25 @@ search: exclude: true --- -# モデル・コンテキスト・プロトコル（MCP） +# モデルコンテキストプロトコル (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（通称 MCP）は、LLM にツールとコンテキストを提供するための仕組みです。MCP ドキュメントには次のように説明されています。 +[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP ドキュメントより : -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続するための標準化された方法を提供するように、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続する標準化された手段を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続するための標準化された手段を提供します。 -Agents SDK は MCP をサポートしており、幅広い MCP サーバーを利用してエージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを利用してエージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、MCP 仕様では使用するトランスポートメカニズムに基づいて次の 3 種類のサーバーが定義されています。 +現在、MCP の仕様では使用するトランスポートメカニズムに基づいて 3 種類のサーバーが定義されています : -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動くイメージです。 -2. **HTTP over SSE** サーバー: リモートで実行され、URL 経由で接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義されている Streamable HTTP トランスポートを用いてリモートで実行されます。 +1. **stdio** サーバーはアプリケーションのサブプロセスとして実行されます。ローカルで動作していると考えてください。 +2. **HTTP over SSE** サーバーはリモートで実行されます。URL 経由で接続します。 +3. **Streamable HTTP** サーバーは、MCP 仕様で定義されている Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらのサーバーへ接続するには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用します。 -たとえば、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を利用する場合は次のようになります。 +たとえば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -39,9 +39,9 @@ async with MCPServerStdio( tools = await server.list_tools(run_context, agent) ``` -## MCP サーバーの利用 +## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェント実行時に毎回 MCP サーバーへ `list_tools()` を呼び出し、LLM へ MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。Agents SDK はエージェントの実行ごとに MCP サーバーへ `list_tools()` を呼び出します。これによって LLM は MCP サーバーのツールを認識できます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を呼び出します。 ```python @@ -52,13 +52,13 @@ agent=Agent( ) ``` -## ツールのフィルタリング +## ツールフィルタリング -MCP サーバー上でツールフィルターを設定することで、エージェントが利用できるツールを制御できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーでツールフィルターを設定することで、エージェントが利用できるツールを制限できます。SDK は静的および動的の両方のツールフィルタリングをサポートしています。 ### 静的ツールフィルタリング -単純な許可 / ブロックリストには静的フィルタリングを使用できます。 +単純な許可 / ブロックリストの場合、静的フィルタリングを使用できます : ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方を設定した場合、処理順序は次のとおりです。** -1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールのみを保持 -2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定したツールを除外 +**`allowed_tool_names` と `blocked_tool_names` の両方を設定した場合の処理順序:** +1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールだけを残します。 +2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定したツールを除外します。 -たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、利用できるのは `read_file` と `write_file` のみになります。 +たとえば `allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、`read_file` と `write_file` だけが利用可能になります。 ### 動的ツールフィルタリング -より複雑なロジックが必要な場合は、関数を用いた動的フィルターを使用できます。 +より複雑なフィルタリング ロジックには、関数を使った動的フィルターを利用できます : ```python from agents.mcp import ToolFilterContext @@ -134,21 +134,21 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次の情報にアクセスできます。 -- `run_context`: 現在の実行コンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +`ToolFilterContext` からは次の情報にアクセスできます : +- `run_context` : 現在の実行コンテキスト +- `agent` : ツールを要求しているエージェント +- `server_name` : MCP サーバー名 ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用性の高い instruction テンプレートを作成できます。 +MCP サーバーはプロンプトも提供でき、これを使ってエージェントの instructions を動的に生成できます。再利用可能な instructions テンプレートをパラメーター付きでカスタマイズできます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します。 +プロンプトをサポートする MCP サーバーは以下の 2 つの主要メソッドを提供します : -- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを列挙 -- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得 +- `list_prompts()` : サーバー上で利用可能なプロンプトを列挙 +- `get_prompt(name, arguments)` : 指定した名前のプロンプトをパラメーター付きで取得 ```python # List available prompts @@ -173,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、MCP サーバーへ `list_tools()` が呼び出されます。サーバーがリモートの場合は特にレイテンシが増える可能性があります。ツール一覧を自動でキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないと確信できる場合のみ設定してください。 +エージェントが実行されるたびに、MCP サーバーへ `list_tools()` が呼ばれます。サーバーがリモートの場合、これはレイテンシーの原因になります。ツール一覧を自動でキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡してください。ツールリストが変わらないと確信できる場合のみ行ってください。 -キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。 ## エンドツーエンドのコード例 -動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。 +完全な動作例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。 ## トレーシング -[トレーシング](./tracing.md) は次の MCP 操作を自動的にキャプチャします。 +[トレーシング](./tracing.md) では MCP 操作が自動的に記録されます : 1. MCP サーバーへのツール一覧取得呼び出し -2. 関数呼び出しにおける MCP 関連情報 +2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index f836ef6ba..c34927e71 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,54 +4,54 @@ 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](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、[Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 ## 非 OpenAI モデル -ほとんどの OpenAI 以外のモデルは、[LiteLLM integration](../litellm.md) 経由で利用できます。まず、litellm の依存関係グループをインストールします。 +ほとんどの非 OpenAI モデルは [LiteLLM 連携](./litellm.md) を通じて利用できます。まず、litellm の依存関係グループをインストールします: ```bash pip install "openai-agents[litellm]" ``` -その後、`litellm/` プレフィックスを付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 +次に、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) を使用します: ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### OpenAI 以外のモデルを利用するその他の方法 +### 非 OpenAI モデルのその他の使用方法 -他の LLM プロバイダーを統合する方法はあと 3 つあります（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーを統合する方法は、さらに 3 つあります（[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) に code examples）: 1. [`set_default_openai_client`][agents.set_default_openai_client] - `AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに利用したい場合に便利です。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) を参照してください。 + `AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。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) を参照してください。 + `Runner.run` レベルで使用します。この方法では、「この 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 integration](../litellm.md) があります。 + 特定の `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 - これらの例では Chat Completions API／モデルを使用しています。理由は、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしご利用の LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの例では Chat Completions API / モデルを使用しています。ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないためです。LLM プロバイダーが Responses API をサポートしている場合は、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. 任意のモデル名と、それを [`ModelProvider`][agents.models.interface.ModelProvider] が Model インスタンスにマッピングできるように渡す +3. [`Model`][agents.models.interface.Model] 実装を直接渡す !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、ワークフローごとに 1 つのモデル形状を使用することを推奨します。2 つの形状では利用できる機能やツールが異なるためです。もしワークフローで混在させる場合は、利用する機能が双方でサポートされていることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとに 1 つのモデル形状を使用することを推奨します。両モデル形状は利用できる機能や tools が異なるためです。ワークフローで複数形状を混在させる場合は、使用するすべての機能が両方で利用可能か確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -84,10 +84,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接設定しています。 -2. [`Model`][agents.models.interface.Model] の実装を渡しています。 +1. OpenAI モデル名を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに細かく設定したい場合は、`temperature` などのオプションを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。 +エージェントで使用するモデルをさらに設定したい場合は、`temperature` などのオプション設定を持つ [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -100,7 +100,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する際には、`user` や `service_tier` など[いくつかの追加パラメーター](https://platform.openai.com/docs/api-reference/responses/create)があります。トップレベルにない場合でも、`extra_args` を使って渡すことが可能です。 +また、OpenAI の Responses API を使用する場合、`user` や `service_tier` など [追加のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、`extra_args` で渡せます。 ```python from agents import Agent, ModelSettings @@ -116,29 +116,29 @@ english_agent = Agent( ) ``` -## 他社 LLM プロバイダー利用時によくある問題 +## 他の LLM プロバイダーを使用する際のよくある問題 -### Tracing client error 401 +### トレーシング クライアント エラー 401 -トレーシング関連のエラーが出る場合、トレースが OpenAI のサーバーへアップロードされるのに OpenAI API キーがないことが原因です。次のいずれかで解決できます。 +トレーシング関連のエラーが出る場合、トレースは 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] +2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. OpenAI 以外のトレースプロセッサーを使用する。詳しくは [tracing docs](../tracing.md#custom-tracing-processors) を参照してください。 +3. 非 OpenAI のトレースプロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーはまだ対応していません。その結果として 404 などのエラーが発生することがあります。対応策は 2 つあります。 +SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーはまだ対応していません。その結果、404 などのエラーが発生することがあります。解決策は 2 つあります: 1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す - これは `OPENAI_API_KEY` と `OPENAI_BASE_URL` を環境変数で設定している場合に機能します。 + これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する - コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 + 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) をサポートしていません。その場合、次のようなエラーが発生することがあります: ``` @@ -146,12 +146,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダーの制限で、JSON 出力には対応しているものの、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーを使用することを推奨します。そうでない場合、JSON が不正形式になるたびにアプリが壊れる可能性があります。 +これは一部プロバイダーの制限です。JSON 出力には対応していても、出力に使用する `json_schema` を指定できません。現在この問題を解決中ですが、JSON スキーマ出力をサポートするプロバイダーを使用することを推奨します。そうでない場合、無効な JSON が生成され、アプリが頻繁に壊れる可能性があります。 -## プロバイダーをまたいだモデルの組み合わせ +## プロバイダーをまたいだモデルの混在 -モデルプロバイダー間の機能差を理解していないと、エラーが発生することがあります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search や web search をサポートしていますが、多くの他社プロバイダーはこれらの機能をサポートしていません。以下の制限に注意してください。 +モデルプロバイダー間の機能差に注意しないと、エラーの原因になります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホストされた file search や web search をサポートしていますが、多くの他プロバイダーはこれらをサポートしていません。次の制限に注意してください: -- 対応していない `tools` を理解しないプロバイダーに送らない -- テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON outputs をサポートしないプロバイダーでは、不正な JSON が返ることがある点に注意する \ No newline at end of file +- 対応していないプロバイダーには `tools` を送信しない +- テキスト専用モデルを呼び出す前にマルチモーダル入力を除去する +- structured JSON 出力をサポートしていないプロバイダーでは、無効な JSON が生成されることがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 31a2fd147..15a768894 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM 経由で任意のモデルを使用する +# LiteLLM を介した任意モデルの使用 !!! note - LiteLLM 統合は現在ベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題を見つけた場合は [GitHub の issues](https://github.com/openai/openai-agents-python/issues) でご報告ください。迅速に対応します。 + LiteLLM 統合は現在 beta 版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題を見つけた場合は [GitHub issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応いたします。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。 Agents SDK では、あらゆる AI モデルを利用できるように LiteLLM 統合を追加しました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、1 つのインターフェースで 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 プロバイダー ドキュメント](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM がサポートするモデルの一覧は [litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 97500f3bf..237f983ad 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -2,40 +2,40 @@ search: exclude: true --- -# 複数エージェントのオーケストレーション +# 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内でエージェントがどのように動作するか、どのエージェントがどの順序で実行されるか、そして次に何を行うかを決定する流れを指します。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でエージェントがどのように動き、どの順序で実行され、次に何をするかを決定する流れを指します。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定を任せる方法: LLM の知能を活用して計画・推論し、それに基づいて次のステップを決定します。 -2. コードでオーケストレーションする方法: コードによってエージェントの流れを制御します。 +1. LLM に判断させる: LLM の知能を活用して計画・推論を行い、その結果に基づいて次のステップを決定します。 +2. code でオーケストレーションする: コードでエージェントの流れを決定します。 -これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使うこともできます。それぞれにトレードオフがあるため、以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、 instructions、 tools、 handoffs を備えた LLM です。これにより、オープンエンドなタスクに対して、 LLM が自律的に計画を立て、ツールを使ってアクションを実行・データを取得し、 handoffs を使ってサブエージェントにタスクを委任できます。たとえば、リサーチエージェントには次のようなツールを装備できます。 +エージェントは instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、 LLM はツールを使ってアクションを実行しデータを取得し、handoffs でサブエージェントへ委譲しながら、自律的にタスクへの取り組み方を計画できます。たとえば、リサーチを行うエージェントには次のようなツールを持たせられます。 -- Web 検索によるオンライン情報の取得 -- ファイル検索とリトリーバルによる独自データや接続の検索 -- コンピュータ操作による PC 上でのアクション実行 -- コード実行によるデータ分析 -- プランニングやレポート作成に優れた専門エージェントへの handoffs +- Web 検索でオンライン情報を見つける +- ファイル検索と取得で独自データや接続を検索する +- コンピュータ操作でコンピュータ上の操作を実行する +- コード実行でデータ分析を行う +- 計画立案やレポート作成などに優れた専門エージェントへの handoffs -このパターンは、タスクがオープンエンドで LLM の知能に依存したい場合に最適です。主な戦術は次のとおりです。 +このパターンはタスクがオープンエンドで、 LLM の知能に依存したい場合に最適です。重要なポイントは次のとおりです。 -1. 良いプロンプトに投資すること。利用可能なツール、使い方、遵守すべきパラメーターを明確に示します。 -2. アプリを監視し、改善を重ねること。問題が起こる箇所を確認し、プロンプトを反復的に改善します。 -3. エージェントに内省と改善を許可すること。たとえばループ内で実行し、自己批評させる、あるいはエラーメッセージを提供して改善させます。 -4. 何でもこなす汎用エージェントではなく、特定タスクに特化したエージェントを用意すること。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資すること。エージェントを訓練してタスク遂行能力を向上させられます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、そして遵守すべきパラメーターを明確に示します。 +2. アプリをモニタリングして改善を重ねる。問題が発生した箇所を確認し、プロンプトを改良します。 +3. エージェントに内省と改善をさせる。たとえばループで実行し自己批評させたり、エラーメッセージを渡して改善させたりします。 +4. なんでもこなす汎用エージェントより、特定タスクに特化したエージェントを用意します。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を向上させられます。 -## コードによるオーケストレーション +## code によるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの面でより決定論的かつ予測しやすくなります。代表的なパターンは以下のとおりです。 +LLM によるオーケストレーションは強力ですが、code でオーケストレーションすると速度・コスト・性能の面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに応じて次のエージェントを選択します。 -- あるエージェントの出力を次のエージェントの入力へと変換してエージェントを連鎖させる。ブログ記事作成なら「リサーチ→アウトライン作成→記事執筆→批評→改善」のようにタスクを分解できます。 -- タスクを実行するエージェントを `while` ループで動かし、評価とフィードバックを行うエージェントと組み合わせ、評価者が基準を満たしたと判断するまで繰り返します。 -- 複数エージェントを並列実行する。たとえば Python の basic components である `asyncio.gather` などを用います。相互依存しない複数タスクを高速に処理したい場合に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ方法があります。 +- 複数のエージェントをチェーンし、一方の出力を次の入力へ変換する。ブログ記事作成を「リサーチ → アウトライン作成 → 本文作成 → 批評 → 改善」のような一連のステップに分解できます。 +- タスクを実行するエージェントを `while` ループで回し、評価とフィードバックを行うエージェントとセットで動かし、評価者が基準を満たすと判断するまで繰り返す。 +- `asyncio.gather` などの Python プリミティブを用いて複数のエージェントを並列実行する。互いに依存しない複数タスクがある場合に速度面で有効です。 -コード例については [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) を参照してください。 \ 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 5f4ae45b5..3aed2b0ba 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -この作業は一度だけで大丈夫です。 +この操作は一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -14,23 +14,23 @@ cd my_project python -m venv .venv ``` -### 仮想環境のアクティブ化 +### 仮想環境の有効化 -新しいターミナルセッションを開始するたびに実行してください。 +新しいターミナルセッションを開くたびに実行してください。 ```bash source .venv/bin/activate ``` -### Agents SDK のインストール +### Agents SDK のインストール ```bash pip install openai-agents # or `uv add openai-agents`, etc ``` -### OpenAI API キーの設定 +### OpenAI API キーの設定 -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 - エージェント は instructions、名前、そして任意の config（`model_config` など）で定義します。 +エージェントは instructions、名前、そして `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 @@ -93,9 +93,9 @@ async def main(): print(result.final_output) ``` -## ガードレールを追加する +## ガードレールの追加 -入力または出力に対して実行するカスタム ガードレール を定義できます。 +入力または出力に対して実行するカスタムガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてをまとめる +## まとめて実行 -ハンドオフと入力 ガードレール を使用して、ワークフロー全体をまとめて実行しましょう。 +これまでのすべてを組み合わせ、ハンドオフと入力ガードレールを使用してワークフロー全体を実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースを表示する +## トレースの表示 - エージェント 実行中に何が起こったかを確認するには、 OpenAI ダッシュボードの [Trace viewer](https://platform.openai.com/traces) に移動して実行のトレースを表示してください。 +エージェント実行中に何が起こったかを確認するには、 [OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動してエージェント実行のトレースを閲覧してください。 ## 次のステップ より複雑なエージェントフローの構築方法を学びましょう: -- [エージェント](agents.md) の設定方法について学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md) について学びます。 \ No newline at end of file +- [エージェント](agents.md) の設定方法について学ぶ +- [エージェントの実行](running_agents.md) について学ぶ +- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md) について学ぶ \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index cab2be05a..d70815c1a 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 の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 -!!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +!!! warning "Beta feature" +Realtime エージェントはベータ版です。今後の改善に伴い、互換性が壊れる変更が入る可能性があります。 ## 概要 -Realtime エージェントは、音声とテキストの入力をリアルタイムで処理し、音声で応答できる会話フローを実現します。 OpenAI の Realtime API と永続的に接続することで、低遅延かつ自然な音声対話が可能になり、ユーザーによる割り込みにもスムーズに対応できます。 +Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答できる会話フローを実現します。OpenAI の Realtime API との永続的な接続を維持し、低遅延かつ自然な音声会話や割り込みへのスムーズな対応が可能です。 ## アーキテクチャ ### コアコンポーネント -Realtime システムは次の主要コンポーネントで構成されています。 +realtime システムは以下の主要コンポーネントで構成されています。 -- **RealtimeAgent**: instructions、 tools、 handoffs を設定したエージェント -- **RealtimeRunner**: 設定を管理します。 `runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出すとセッションが取得できます。 +- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話終了まで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装）。 ### セッションフロー -典型的な realtime セッションの流れは次のとおりです。 +一般的な realtime セッションの流れは次のとおりです。 -1. **RealtimeAgent** を instructions、 tools、 handoffs とともに作成します。 -2. **RealtimeRunner** をエージェントと設定オプションでセットアップします。 -3. `await runner.run()` を使用して **セッションを開始** し、 RealtimeSession を取得します。 -4. `send_audio()` または `send_message()` を使って **音声またはテキストメッセージを送信** します。 -5. セッションをイテレートして **イベントをリッスン** します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーなどが含まれます。 -6. ユーザーがエージェントの発話中に話し始めた場合は **割り込みを処理** し、現在の音声生成を自動的に停止します。 +1. **RealtimeAgent を作成** し、instructions・tools・handoffs を設定します。 +2. **RealtimeRunner をセットアップ** し、エージェントと各種オプションを指定します。 +3. `await runner.run()` で **セッションを開始** し、RealtimeSession を取得します。 +4. `send_audio()` または `send_message()` を使用して **音声またはテキストメッセージを送信** します。 +5. セッションをイテレートして **イベントを監視** します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどがあります。 +6. ユーザーがエージェントの発話を遮った場合に **割り込みを処理** します。これにより現在の音声生成が自動で停止します。 -セッションは会話履歴を保持し、 realtime モデルとの永続的接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は通常の Agent クラスとほぼ同じですが、いくつかの重要な違いがあります。詳細な API は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] を参照してください。 +RealtimeAgent は通常の Agent クラスとほぼ同様に機能しますが、いくつか重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスを参照してください。 -主な違いは次のとおりです。 +通常のエージェントとの主な違い: -- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 -- structured outputs（ `outputType` ）はサポートされていません。 -- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- tools、 handoffs、 instructions などその他の機能は同じように動作します。 +- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 +- structured outputs（`outputType`）はサポートされません。 +- Voice はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、handoffs、instructions などその他の機能は同じように使えます。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの挙動を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声の選択（alloy、 echo、 fable、 onyx、 nova、 shimmer）、対応モダリティ（テキスト／音声）を設定可能です。入力と出力の音声形式は設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび/または音声）を指定可能です。音声フォーマットは入力・出力ともに設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定では、音声入力および出力の処理方法を制御します。Whisper などのモデルを用いた入力音声の書き起こし、言語設定、ドメイン固有の用語認識向上のための書き起こしプロンプトを指定できます。ターン検知設定では、音声活動検出のしきい値、無音時間、検出した音声の前後のパディングなど、エージェントがいつ応答を開始・終了すべきかを調整できます。 +音声設定では、音声入力と出力の取り扱いを制御します。Whisper などのモデルを使った音声入力の文字起こし、言語設定、ドメイン固有用語の精度向上のための transcription prompts を指定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出された発話前後のパディングなどを調整し、エージェントが発話を開始・終了するタイミングを制御します。 -## Tools と Functions +## ツールと関数 -### Tools の追加 +### ツールの追加 -通常のエージェントと同様に、 realtime エージェントは会話中に実行される function tools をサポートします。 +通常のエージェントと同様に、realtime エージェントでも会話中に実行される function tools を利用できます。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフを利用すると、専門化されたエージェント間で会話を引き継ぐことができます。 +ハンドオフを使用すると、会話を専門化されたエージェント間で転送できます。 ```python from agents.realtime import realtime_handoff @@ -119,40 +119,40 @@ 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**: tool 実行のライフサイクル +- **handoff**: エージェント間のハンドオフが発生 +- **error**: 処理中にエラーが発生 -完全なイベント詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -Realtime エージェントでは出力ガードレールのみがサポートされています。パフォーマンス低下を防ぐため、ガードレールはデバウンスされ、リアルタイム生成の度にではなく定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 +realtime エージェントでは出力ガードレールのみサポートされます。性能への影響を避けるため、ガードレールはデバウンスされ、リアルタイム生成のすべての単語ではなく一定間隔ごと（デフォルト 100 文字）に実行されます。設定で変更可能です。 -ガードレールが発動すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能のバランスを保ちます。テキストエージェントと異なり、 realtime エージェントではガードレール発動時に Exception は発生しません。 +ガードレールが発動すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンスによって安全性とリアルタイム性能のバランスを取ります。テキストエージェントと異なり、realtime エージェントではガードレール発動時に Exception は発生しません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用して音声を、 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストをセッションに送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] で音声を、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] でテキストを送信できます。 -音声出力を再生するには `audio` イベントをリッスンし、好みの音声ライブラリでデータを再生してください。ユーザーが割り込んだ際には `audio_interrupted` イベントを受け取って再生を即座に停止し、キューにある音声をクリアするようにしてください。 +音声出力を受け取るには `audio` イベントを監視し、好みのオーディオライブラリで再生してください。`audio_interrupted` イベントをリッスンして、ユーザーが割り込んだ際に再生を即座に停止し、キューに残っている音声もクリアするようにしましょう。 -## 直接モデルへのアクセス +## 直接モデルアクセス -より低レベルの制御が必要な場合、基盤となるモデルへアクセスしてカスタムリスナーを追加したり高度な操作を行えます。 +下位レベルの制御やカスタムリスナー追加のために、基盤モデルへ直接アクセスできます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、 [`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスでき、接続の詳細を細かく制御する高度なユースケースに対応します。 +これにより、高度なユースケース向けに [`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## 例 +## コード例 -完全な動作例は [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 UI あり／なしのデモが含まれています。 \ No newline at end of file +完全な動作例は [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI あり・なしのデモが含まれています。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index a19a70e31..bde46d5cb 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,26 +4,26 @@ search: --- # クイックスタート -Realtime エージェントを使用すると、OpenAI の Realtime API を通じて AI エージェントと音声会話ができます。このガイドでは、最初のリアルタイム音声エージェントを作成する手順を説明します。 +Realtime エージェントを使用すると、OpenAI の Realtime API を介して音声でエージェントと会話できます。このガイドでは、初めてのリアルタイム音声エージェントの作成方法を説明します。 !!! warning "Beta feature" -Realtime エージェントはベータ版です。実装の改善に伴い、後方互換性のない変更が入る可能性があります。 +Realtime エージェントはベータ版です。実装を改善する過程で破壊的変更が入る可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 ## インストール -OpenAI Agents SDK をまだインストールしていない場合は、以下を実行してください： +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください。 ```bash pip install openai-agents ``` -## 最初のリアルタイム エージェントを作成する +## 初めてのリアルタイム エージェント作成 ### 1. 必要なコンポーネントをインポート @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. ランナーを設定 +### 3. Runner をセットアップ ```python runner = RealtimeRunner( @@ -81,7 +81,7 @@ asyncio.run(main()) ## 完全な例 -以下は動作する完全な例です： +以下は動作する完全なサンプルです。 ```python import asyncio @@ -139,40 +139,40 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`：利用可能なリアルタイムモデルを選択（例：`gpt-4o-realtime-preview`） -- `voice`：音声を選択（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） -- `modalities`：テキストおよび／またはオーディオを有効化（`["text", "audio"]`） +- `model_name`: 利用可能なリアルタイムモデルを選択（例: `gpt-4o-realtime-preview`） +- `voice`: 音声を選択（`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`） +- `modalities`: テキストおよび／または音声を有効化（`["text", "audio"]`） ### オーディオ設定 -- `input_audio_format`：入力オーディオの形式（`pcm16`、`g711_ulaw`、`g711_alaw`） -- `output_audio_format`：出力オーディオの形式 -- `input_audio_transcription`：文字起こしの設定 +- `input_audio_format`: 入力音声のフォーマット（`pcm16`, `g711_ulaw`, `g711_alaw`） +- `output_audio_format`: 出力音声のフォーマット +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`：検出方法（`server_vad`、`semantic_vad`） -- `threshold`：音声活動のしきい値（0.0-1.0） -- `silence_duration_ms`：ターン終了を検出する無音時間 -- `prefix_padding_ms`：発話前のオーディオパディング +- `type`: 検出方法（`server_vad`, `semantic_vad`） +- `threshold`: 音声検出しきい値（0.0–1.0） +- `silence_duration_ms`: ターン終了と判断する無音時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [リアルタイム エージェントについてさらに学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーの動作する例を確認 -- エージェントに tools を追加 -- エージェント間のハンドオフを実装 -- 安全のためのガードレールを設定 +- [リアルタイム エージェントについて詳しく学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーの作動するコード例を参照 +- エージェントにツールを追加 +- エージェント間のハンドオフを実装 +- 安全性のためのガードレールを設定 ## 認証 -OpenAI API キーを環境変数に設定してください： +OpenAI API キーが環境変数に設定されていることを確認してください。 ```bash export OPENAI_API_KEY="your-api-key-here" ``` -またはセッション作成時に直接渡します： +または、セッション作成時に直接渡すこともできます。 ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 2f4babefa..cc8ce00ef 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリースプロセス／変更履歴 +# リリースプロセス/変更ログ -プロジェクトでは、`0.Y.Z` 形式を用いたわずかに変更されたセマンティックバージョニングを採用しています。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントの増分ルールは以下のとおりです。 +本プロジェクトでは、`0.Y.Z` という形式を用いた、セマンティックバージョニングをやや変更した方式を採用しています。先頭の `0` は、 SDK が急速に進化している段階であることを示します。各コンポーネントの増分ルールは次のとおりです。 -## マイナー（`Y`）バージョン +## マイナー ( `Y` ) バージョン -ベータでない公開インターフェースに **破壊的変更** がある場合、マイナーバージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれることがあります。 +ベータでない公開インターフェースに破壊的変更が入る場合、マイナーバージョン `Y` を上げます。たとえば `0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることを推奨します。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定することを推奨します。 -## パッチ（`Z`）バージョン +## パッチ ( `Z` ) バージョン -非破壊的変更の場合は `Z` を上げます。 +破壊的でない変更については `Z` を増加させます。 - バグ修正 - 新機能 -- プライベートインターフェースの変更 +- 非公開インターフェースの変更 - ベータ機能の更新 -## 破壊的変更の変更履歴 +## 破壊的変更の変更ログ ### 0.2.0 -このバージョンでは、これまで `Agent` を引数に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。たとえば、MCP サーバーの `list_tools()` 呼び出しが該当します。これは型に関する変更のみで、実際には引き続き `Agent` オブジェクトを受け取ります。更新する際は、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 +このバージョンでは、これまで引数として `Agent` を受け取っていたいくつかの箇所が、代わりに `AgentBase` を受け取るようになりました。たとえば、 MCP サーバーの `list_tools()` 呼び出しなどです。これは型のみの変更であり、実際には引き続き `Agent` オブジェクトが渡されます。アップデートする際は、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` をサブクラス化しているクラスには、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承するクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 8c88ef085..b1ec3626e 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,4 +18,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループ内でユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成され次第モデルの出力を ストリーミング します。ループを終了するには `quit` または `exit` と入力するか（または Ctrl-D を押してください）。 \ No newline at end of file +`run_demo_loop` はループ内でユーザー入力を促し、各ターン間の会話履歴を保持します。デフォルトでは、生成されると同時にモデル出力をストリーミングします。ループを終了するには `quit` または `exit` と入力するか、`Ctrl-D` を押してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index df4515155..bb563344d 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 結果 -` Runner.run ` メソッドを呼び出すと、返されるのは次のいずれかです。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返されます: -- [`RunResult`][agents.result.RunResult] ─ ` run ` または ` run_sync ` を呼び出した場合 -- [`RunResultStreaming`][agents.result.RunResultStreaming] ─ ` run_streamed ` を呼び出した場合 +- [`RunResult`][agents.result.RunResult] （ `run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming] （ `run_streamed` を呼び出した場合） -これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はそこに含まれています。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が入ります。内容は以下のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されます。内容は次のいずれかです。 -- 最後のエージェントで ` output_type ` が定義されていない場合は ` str ` -- エージェントで ` output_type ` が定義されている場合は ` last_agent.output_type ` 型のオブジェクト +- `output_type` が定義されていない場合は `str` +- `output_type` が定義されている場合は `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] を使うと、元の入力にエージェント実行中に生成されたアイテムを連結した入力リストを取得できます。これにより、あるエージェントの出力を別の実行に渡したり、ループで実行して毎回新しい user 入力を追加したりすることが簡単になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、次回のユーザー入力時にこれが役立つことがよくあります。たとえば、一次受付のエージェントが言語別エージェントへハンドオフする場合、最後のエージェントを保存しておけば、ユーザーが次にメッセージを送った際に再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 user が入力する際にこれを利用すると便利です。たとえば、フロントラインのトリアージエージェントが言語別エージェントにハンドオフする場合、最後のエージェントを保存しておき、次回のメッセージで再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`][agents.items.RunItem] でラップされており、LLM が生成した raw アイテムを保持します。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが格納されます。アイテムは [`RunItem`][agents.items.RunItem] です。RunItem は LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は、LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツール応答です。アイテムから source/target エージェントにもアクセスできます。 -- [`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 アイテムはツール呼び出しアイテムです。 +- [`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_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が格納されています。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が格納されます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、` run ` メソッドへ渡した元の入力が入ります。多くの場合は不要ですが、必要に応じて参照できます。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が格納されます。通常は必要ありませんが、必要に応じて利用できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 04436080b..97f4e4512 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,14 +4,14 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。方法は 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスを介して実行できます。方法は 3 つあります。 1. [`Runner.run()`][agents.run.Runner.run] - 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 + 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync] - 同期メソッドで、内部的には `.run()` を呼び出します。 + 同期メソッドで、内部では `.run()` を呼び出します。 3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] - 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを順次ストリームします。 + 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリームします。 ```python from agents import Agent, Runner @@ -26,55 +26,64 @@ async def main(): # Infinite loop's dance ``` -詳細は [results guide](results.md) を参照してください。 +詳細は [結果ガイド](results.md) をご覧ください。 ## エージェントループ -`Runner` の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）を指定できます。 +`Runner` の run メソッドを使用する際には、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムのリスト（input items）のいずれかです。 -Runner は次のループを実行します。 +runner は次のループを実行します。 1. 現在のエージェントと入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. `final_output` を返した場合、ループを終了し結果を返します。 - 2. ハンドオフが行われた場合、現在のエージェントと入力を更新してループを再実行します。 - 3. ツール呼び出しがある場合、それらを実行し結果を追加してループを再実行します。 + 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらのツールを実行し、結果を追加してループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「final output」と見なされるルールは、希望する型のテキスト出力を生成し、ツール呼び出しが存在しない場合です。 + LLM の出力が「final output」と見なされるルールは、望ましい型のテキスト出力であり、かつツール呼び出しが存在しない場合です。 ## ストリーミング -ストリーミングを使用すると、LLM 実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には実行に関する完全な情報（生成されたすべての新しい出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [streaming guide](streaming.md) を参照してください。 +ストリーミングを利用すると、LLM 実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には実行に関する完全な情報（生成されたすべての新しい出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 ## Run config `run_config` パラメーターでは、エージェント実行のグローバル設定を行えます。 -- [`model`][agents.run.RunConfig.model]: 各エージェントの `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](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 つの論理ターンを表します。例: +- [`model`][agents.run.RunConfig.model] + 各エージェントの `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` の設定を推奨します。group ID は複数の実行にまたがるトレースを関連付ける optional フィールドです。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata] + すべてのトレースに含めるメタデータ。 + +## 会話／チャットスレッド + +いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（ひいては 1 つ以上の LLM 呼び出し）が実行されますが、チャット会話上は 1 つの論理ターンに相当します。例: 1. ユーザーターン: ユーザーがテキストを入力 2. Runner 実行: - - 最初のエージェントが LLM を呼び出し、ツールを実行し、第 2 のエージェントへハンドオフ - - 第 2 のエージェントがさらにツールを実行し、出力を生成 + - 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフ + - 2 つ目のエージェントがさらにツールを実行し、出力を生成 -エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。エージェントが生成したすべての新規アイテムを見せることも、最終出力のみを見せることも可能です。どちらの場合でも、ユーザーが追質問をした場合は再度 run メソッドを呼び出します。 +エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。たとえば、エージェントが生成したすべての新しいアイテムを表示するか、最終出力のみを表示するかです。いずれの場合も、ユーザーがフォローアップ質問をしたら、再度 run メソッドを呼び出します。 -### 手動での会話管理 +### 会話を手動で管理する [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して、次ターンの入力を取得し、会話履歴を手動で管理できます。 @@ -96,9 +105,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 @@ -121,25 +130,29 @@ async def main(): # California ``` -Sessions は自動的に以下を行います。 +Sessions は次を自動で行います。 - 各実行前に会話履歴を取得 - 各実行後に新しいメッセージを保存 -- 異なる session ID ごとに個別の会話を維持 +- 異なる session ID ごとに独立した会話を維持 詳細は [Sessions ドキュメント](sessions.md) を参照してください。 +## 長時間実行エージェント & human-in-the-loop + +Agents SDK は [Temporal](https://temporal.io/) との統合により、人間を介在させたタスクを含む耐久性のある長時間実行ワークフローを実現できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) をご覧ください。ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) にあります。 + ## 例外 -特定の状況で SDK は例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです。 +SDK は状況に応じて例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです。 - [`AgentsException`][agents.exceptions.AgentsException] - SDK で送出されるすべての例外の基底クラス。 + SDK が送出するすべての例外の基底クラスです。 - [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] - 実行が `max_turns` を超えた場合に送出されます。 + 実行が run メソッドに渡した `max_turns` を超えた場合に送出されます。 - [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError] - モデルが無効な出力（例: 不正な JSON、存在しないツールの使用）を生成した場合に送出されます。 + モデルが無効な出力（例: 不正な JSON、存在しないツールの呼び出しなど）を生成した場合に送出されます。 - [`UserError`][agents.exceptions.UserError] - SDK を使用する開発者が誤った使い方をした場合に送出されます。 + SDK を使用する開発者の誤用時に送出されます。 - [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] [ガードレール](guardrails.md) がトリップした際に送出されます。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 064d1a58e..a80e8aef3 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK には、セッションメモリが組み込まれており、複数回のエージェント実行にわたって会話履歴を自動的に保持します。そのため、ターンごとに `.to_input_list()` を手動で扱う必要がありません。 +Agents SDK にはセッションメモリが組み込まれており、複数回のエージェント実行にわたって会話履歴を自動的に保持します。これにより、各ターンで `.to_input_list()` を手動で扱う必要がなくなります。 -Sessions は特定のセッションの会話履歴を保存し、明示的なメモリ管理をしなくてもエージェントがコンテキストを維持できるようにします。チャットアプリケーションやマルチターンの会話で、エージェントに以前のやり取りを覚えさせたい場合に特に便利です。 +セッションは特定のセッションに対する会話履歴を保存し、明示的なメモリ管理を行わなくてもエージェントがコンテキストを維持できるようにします。チャットアプリケーションやマルチターンの会話で、エージェントに過去のやり取りを覚えさせたい場合に特に便利です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリが有効な場合: +セッションメモリを有効にすると、以下のように動作します。 -1. **各実行前**: runner が自動的にそのセッションの会話履歴を取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成された新しいアイテム (ユーザー入力、アシスタント応答、ツール呼び出しなど) がすべて自動でセッションに保存されます。 -3. **コンテキスト保持**: 同じセッションで後続の実行を行うたびに、完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 +1. **各実行前**: Runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **各実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）はすべて自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出して会話状態を管理する必要がなくなります。 ## メモリ操作 ### 基本操作 -Sessions では、会話履歴を管理するための複数の操作がサポートされています。 +セッションでは、会話履歴を管理するための操作がいくつか用意されています。 ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### pop_item を使った修正 +### 取り消しのための `pop_item` の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に特に便利です。 +`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に便利です。 ```python from agents import Agent, Runner, SQLiteSession @@ -119,7 +119,7 @@ print(f"Agent: {result.final_output}") ## メモリオプション -### メモリなし (デフォルト) +### メモリなし（デフォルト） ```python # Default behavior - no session memory @@ -170,7 +170,7 @@ result2 = await Runner.run( ## カスタムメモリ実装 -独自のセッションメモリを実装するには、[`Session`][agents.memory.session.Session] プロトコルに準拠したクラスを作成します。 +独自のセッションメモリを実装する場合は、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します。 ```python from agents.memory import Session @@ -214,19 +214,19 @@ result = await Runner.run( ## セッション管理 -### Session ID 命名 +### セッション ID の命名 -会話を整理しやすいように意味のある Session ID を使用してください。 +会話を整理しやすいよう、意味のあるセッション ID を使用してください。 -- ユーザーベース: `"user_12345"` -- スレッドベース: `"thread_abc123"` -- コンテキストベース: `"support_ticket_456"` +- User-based: `"user_12345"` +- Thread-based: `"thread_abc123"` +- Context-based: `"support_ticket_456"` ### メモリ永続化 -- 一時的な会話にはインメモリ SQLite (`SQLiteSession("session_id")`) を使用 -- 永続的な会話にはファイルベース SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用 -- 本番システムではカスタムセッションバックエンド (Redis、PostgreSQL など) の実装を検討 +- 一時的な会話にはインメモリ SQLite (`SQLiteSession("session_id")`) を使用 +- 永続的な会話にはファイルベース SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用 +- 運用環境では Redis や PostgreSQL など、カスタムセッションバックエンドの実装を検討してください ### セッション管理 @@ -254,7 +254,7 @@ result2 = await Runner.run( ## 完全な例 -以下はセッションメモリの動作を示す完全な例です。 +以下は、セッションメモリが動作する完全な例です。 ```python import asyncio @@ -320,5 +320,5 @@ if __name__ == "__main__": 詳細な API ドキュメントは以下を参照してください。 -- [`Session`][agents.memory.Session] - プロトコルインターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 \ No newline at end of file +- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 2a25d2a37..0af930e7f 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,13 +4,13 @@ search: --- # ストリーミング -ストリーミングを利用すると、エージェント実行の進行に応じて更新を購読できます。これにより、エンドユーザーへ進捗状況や部分的なレスポンスを表示することが可能です。 +ストリーミングを利用すると、エージェント実行の進行に合わせて更新を購読できます。これにより、エンドユーザーへ進捗情報や部分的な応答を表示する際に便利です。 -ストリーミングを行うには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、後述の [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが取得できます。 +ストリーミングを行うには、 `Runner.run_streamed()` を呼び出すと、 `RunResultStreaming` が返されます。 `result.stream_events()` を呼び出すと、以下で説明する `StreamEvent` オブジェクトの非同期ストリームが得られます。 -## Raw response イベント +## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は LLM から直接渡される raw イベントです。これらは OpenAI Responses API フォーマットで提供され、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれています。生成されたメッセージを即座にユーザーへストリーミングしたい場合に便利です。 +`RawResponsesStreamEvent` は、 LLM から直接渡される生のイベントです。これらは OpenAI Responses API 形式であり、各イベントには `response.created`、`response.output_text.delta` などの type と data が含まれます。これらのイベントは、生成されたメッセージをすぐにユーザーへストリーミングしたい場合に便利です。 たとえば、次のコードは LLM が生成したテキストをトークンごとに出力します。 @@ -37,9 +37,9 @@ if __name__ == "__main__": ## Run item イベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。各アイテムが完全に生成されたタイミングを通知するため、トークンではなく「メッセージが生成された」「ツールが実行された」といった単位で進捗を更新できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、ハンドオフなどによって現在のエージェントが変わった際に更新を受け取れます。 +`RunItemStreamEvent` はより高レベルのイベントです。アイテムが完全に生成されたときに通知します。これにより、トークン単位ではなく「メッセージが生成された」「ツールが実行された」などのレベルで進捗をプッシュできます。同様に、 `AgentUpdatedStreamEvent` は現在のエージェントが変更されたとき（例: ハンドオフの結果など）に更新を提供します。 -たとえば、次のコードは raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 +たとえば、次のコードは raw イベントを無視し、ユーザーへアップデートをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 095c855f0..18d014685 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールはエージェントに、データ取得、コード実行、外部 API 呼び出し、さらには コンピュータ操作 まで、さまざまなアクションを実行させます。Agents SDK には、次の 3 つのクラスのツールがあります。 +ツールはエージェントがアクションを実行する手段です。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作まで行えます。Agents SDK には 3 種類のツールがあります。 -- ホスト型ツール: これらは LLM サーバー 上で AI モデルと並行して実行されます。OpenAI は retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 -- Function Calling: あらゆる Python 関数 をツールとして利用できます。 -- エージェントをツールとして使用: エージェント自身をツールとして扱い、ハンドオフなしに他のエージェントを呼び出せます。 +- ホスト済みツール: これらは LLM サーバー上で AI モデルとともに実行されます。OpenAI はリトリーバル、Web 検索、コンピュータ操作をホスト済みツールとして提供しています。 +- Function Calling: 任意の Python 関数をツールとして利用できます。 +- エージェントをツールとして: エージェントをツールとして扱うことで、ハンドオフせずに他のエージェントを呼び出せます。 -## ホスト型ツール +## ホスト済みツール -[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際、OpenAI にはいくつかの組み込みツールがあります。 +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 から取得されます（こちらも上書き可能） -- 関数引数から入力スキーマが自動生成されます -- 各入力の説明は docstring から取得されます（無効化も可能） +- ツール名は Python 関数名になります（名前を指定することも可能）。 +- ツールの説明は関数の 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,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数引数には任意の Python 型 を使用でき、同期関数でも非同期関数でも構いません。 -2. docstring があれば、ツールおよび各引数の説明を取得します。 -3. 関数はオプションで `context`（先頭の引数）を受け取れます。また、ツール名や説明、docstring スタイルなどの上書きも可能です。 -4. 修飾された関数を tools のリストに渡してください。 +1. 引数には任意の Python 型を使え、関数は同期・非同期いずれも対応します。 +2. Docstring があれば、ツール全体および各引数の説明に使用されます。 +3. 関数は任意で `context` を最初の引数として受け取れます。また、ツール名や説明、docstring スタイルなどのオーバーライド設定も可能です。 +4. デコレートした関数を tools のリストに渡します。 -??? note "クリックして出力を表示" +??? note "出力を見るには展開" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数 をそのままツールにしたくない場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。必要な項目は以下のとおりです。 +Python 関数をそのままツールにしたくない場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次の項目を指定してください。 -- `name` -- `description` -- `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツールの出力文字列を返す async 関数） +- `name` +- `description` +- `params_json_schema` : 引数の JSON スキーマ +- `on_invoke_tool` : [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツールの出力文字列を返す async 関数 ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 引数および docstring の自動解析 +### 引数と docstring の自動解析 -前述のとおり、関数シグネチャと docstring を自動解析してツールのスキーマと説明を生成します。主なポイントは次のとおりです。 +前述のとおり、関数シグネチャからツールのスキーマを、docstring からツールや各引数の説明を自動で取得します。ポイントは次のとおりです。 -1. `inspect` によりシグネチャを解析し、型アノテーションから Pydantic モデル を動的に生成します。Python の基本型、Pydantic モデル、TypedDict など多くの型をサポートします。 -2. `griffe` で docstring を解析します。対応フォーマットは `google`、`sphinx`、`numpy` です。自動判定はベストエフォートで行われますが、`function_tool` 呼び出し時に明示的に指定することも、`use_docstring_info` を `False` にして無効化することも可能です。 +1. シグネチャ解析には `inspect` を使用します。型アノテーションを基に引数の型を判断し、Pydantic モデルを動的に構築して全体のスキーマを表現します。Python のプリミティブ型、Pydantic モデル、TypedDict など多くの型をサポートします。 +2. docstring 解析には `griffe` を使用します。`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: @@ -315,12 +315,12 @@ json_tool = data_agent.as_tool( ) ``` -## 関数ツールのエラー処理 +## 関数ツールにおけるエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。この関数は、ツール呼び出しがクラッシュしたときに LLM へ返すエラーレスポンスを生成します。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これはツール呼び出しが失敗した場合に LLM へエラーレスポンスを返す関数です。 -- 省略した場合は `default_tool_error_function` が実行され、LLM にエラーが発生したことを通知します。 -- 独自のエラー関数を渡した場合は、それが実行され、その結果が LLM へ送信されます。 -- 明示的に `None` を渡すと、ツール呼び出しのエラーは再送出されます。たとえば、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などです。 +- 何も渡さない場合、デフォルトで `default_tool_error_function` が実行され、LLM にエラーが発生したことを伝えます。 +- 独自のエラー関数を渡すと、その関数が実行され、LLM へレスポンスが送られます。 +- 明示的に `None` を渡すと、ツール呼び出しエラーは再スローされます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになります。 -`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 b01dbabba..1166b7daf 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,48 +4,48 @@ 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 の Zero Data Retention (ZDR) ポリシー下で API を利用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 1 つの "ワークフロー" のエンドツーエンドの操作を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります。 - - `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 生成情報などを含みます。 +- **トレース** は 1 つの「ワークフロー」の end-to-end 操作を表します。複数のスパンで構成されます。トレースには以下のプロパティがあります。 + - `workflow_name`：論理的なワークフローまたはアプリ名。例： `Code generation` や `Customer service` など + - `trace_id`：トレースの一意 ID。渡さなかった場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`：オプションのグループ ID。同じ会話の複数トレースをリンクする目的で使用します。たとえばチャットスレッド ID など。 + - `disabled`： `True` の場合、このトレースは記録されません。 + - `metadata`：トレースに対するオプションのメタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。 + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id`（存在する場合） + - スパンに関する情報を格納する `span_data`。たとえば `AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報が含まれます。 ## デフォルトのトレーシング デフォルトでは、SDK は以下をトレースします。 -- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます -- エージェント が実行されるたびに `agent_span()` でラップされます -- LLM 生成は `generation_span()` でラップされます -- 関数ツール 呼び出しはそれぞれ `function_span()` でラップされます -- ガードレール は `guardrail_span()` でラップされます -- ハンドオフ は `handoff_span()` でラップされます -- 音声入力 (音声→テキスト) は `transcription_span()` でラップされます -- 音声出力 (テキスト→音声) は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされる +- エージェントが実行されるたびに `agent_span()` でラップされる +- LLM 生成は `generation_span()` でラップされる +- 関数ツール呼び出しはそれぞれ `function_span()` でラップされる +- ガードレールは `guardrail_span()` でラップされる +- ハンドオフは `handoff_span()` でラップされる +- 音声入力（speech-to-text）は `transcription_span()` でラップされる +- 音声出力（text-to-speech）は `speech_span()` でラップされる +- 関連する音声スパンは `speech_group_span()` の下に親子関係を持つ場合がある -デフォルトでは、トレース名は「Agent workflow」です。`trace` を使用してこの名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 +デフォルトでは、トレース名は "Agent workflow" です。 `trace` を使用して名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを構成できます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へプッシュできます (置き換えまたは追加送信先)。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先に送信（置き換えまたは追加）することも可能です。 ## より高レベルのトレース @@ -64,61 +64,63 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` に包まれているため、個別に 2 つのトレースを作成するのではなく、1 つのトレースにまとめられます。 +1. 2 回の `Runner.run` 呼び出しが `with trace()` でラップされているため、それぞれが個別のトレースを作成する代わりに 1 つのトレースに含まれます。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要で、次の 2 通りの方法があります。 +[`trace()`][agents.tracing.trace] 関数でトレースを作成できます。トレースは開始と終了が必要で、次の 2 通りの方法があります。 -1. **推奨**: コンテキストマネージャとして trace を使用する (`with trace(...) as my_trace`)。これにより、適切なタイミングで自動的に開始・終了します。 -2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 +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] を構成することで、この音声データの保存を無効化できます。 +同様に、Audio スパンは既定で入力と出力オーディオの base64 エンコード PCM データを含みます。このオーディオデータの取得は [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] の設定で無効化できます。 ## カスタムトレーシングプロセッサー トレーシングの高レベルアーキテクチャは次のとおりです。 -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースを生成します。 -- その `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。Exporter はスパンとトレースを OpenAI バックエンドへバッチ送信します。 +- 初期化時に、グローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースの生成を担当します。 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、バッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] にトレース／スパンを送信します。この Exporter が OpenAI バックエンドへバッチ送信します。 -このデフォルト設定をカスタマイズし、他のバックエンドへトレースを送信したり、Exporter の動作を変更するには、次の 2 つの方法があります。 +デフォルト設定をカスタマイズして別または追加のバックエンドへ送信したり、Exporter の挙動を変更したりするには、次の 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` を含める必要があります。 ## 外部トレーシングプロセッサー一覧 -- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) -- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) -- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) -- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) \ No newline at end of file +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index be3302ea9..161f13c17 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,9 +2,9 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェント可視化を使用すると、 ** Graphviz ** を用いてエージェントとその関係を構造的なグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化を使用すると、 ** Graphviz ** を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、およびハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,11 +16,11 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は有向グラフを作成し、以下のように表現します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数では、以下のような有向グラフが作成されます: -- ** エージェント ** は黄色のボックスで表示されます。 -- ** ツール ** は緑色の楕円で表示されます。 -- ** ハンドオフ ** はあるエージェントから別のエージェントへの有向エッジです。 +- ** エージェント ** は黄色のボックスで表されます。 +- ** ツール ** は緑色の楕円で表されます。 +- ** ハンドオフ ** は一方のエージェントから別のエージェントへの有向エッジで示されます。 ### 使用例 @@ -54,31 +54,33 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、 ** triage エージェント ** とそのサブエージェントやツールへの接続を視覚的に表現したグラフが生成されます。 +これにより、 ** triage agent ** の構造とサブエージェントおよびツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 生成されたグラフには次が含まれます: -- エントリポイントを示す ** start ノード ** (`__start__`) -- 黄色で塗りつぶされた ** 長方形 ** で表されるエージェント -- 緑色で塗りつぶされた ** 楕円 ** で表されるツール -- 相互作用を示す有向エッジ - - エージェント間ハンドオフには ** 実線矢印 ** - - ツール呼び出しには ** 点線矢印 ** -- 実行の終了を示す ** end ノード ** (`__end__`) +- エントリーポイントを示す ** start node ** (`__start__`) +- 黄色で塗りつぶされた ** 長方形 ** として表されるエージェント +- 緑色で塗りつぶされた ** 楕円 ** として表されるツール +- 相互作用を示す有向エッジ: + - エージェント間のハンドオフには ** 実線矢印 ** を使用 + - ツール呼び出しには ** 破線矢印 ** を使用 +- 実行が終了する位置を示す ** end node ** (`__end__`) ## グラフのカスタマイズ -### グラフの表示 -既定では、`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 0b02cdca4..6fce04ad3 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -`VoicePipeline` は、エージェントベースのワークフローを音声アプリに簡単に変換できるクラスです。実行したいワークフローを渡すと、パイプラインが入力音声の文字起こし、発話終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフローの出力を音声へ変換する処理を自動で行います。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントベースのワークフローを音声アプリへ簡単に変換できるクラスです。ワークフローを渡すだけで、入力音声の文字起こし、話し終わりの検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理までをパイプラインが自動で行います。 ```mermaid graph LR @@ -36,27 +36,34 @@ graph LR パイプラインを作成する際には、次の項目を設定できます。 -1. `workflow` — 新しい音声が文字起こしされるたびに実行されるコードです。 -2. `speech-to-text` および `text-to-speech` モデル -3. `config` — 以下のような設定を行えます。 - - モデルプロバイダー：モデル名を実際のモデルにマッピングします - - トレーシング：トレーシングの有効／無効、音声ファイルのアップロード可否、ワークフロー名、トレース ID など - - TTS と STT モデルの設定：プロンプト、言語、データ型 など +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] + 新しい音声が文字起こしされるたびに実行されるコードです。 +2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] モデル +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] + ここでは以下のような内容を設定できます。 + - モデル名をモデルへマッピングするモデルプロバイダー + - トレーシングの有効・無効、音声ファイルのアップロードの有無、ワークフロー名、トレース ID などのトレーシング設定 + - プロンプト、言語、使用するデータ型など、TTS と STT モデルの設定 ## パイプラインの実行 -パイプラインは `run()` メソッドで実行できます。音声入力は次の 2 つの形式で渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は次の 2 つの形式で渡せます。 -1. `AudioInput` — 完全な音声トランスクリプトがある場合に使用します。発話の終了検知が不要なケース、たとえば事前録音済みの音声や push-to-talk アプリのようにユーザーの発話終了が明確な場合に便利です。 -2. `StreamedAudioInput` — ユーザーの発話終了を検知する必要がある場合に使用します。音声チャンクをリアルタイムでプッシュでき、パイプラインが自動でアクティビティ検知を行い、適切なタイミングでエージェントワークフローを実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] + 完全な音声の文字起こしが既にある場合に使用します。録音済み音声や、プッシュ・トゥ・トークのようにユーザーが話し終わるタイミングが明確なアプリで便利です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] + ユーザーが話し終わったタイミングを検知する必要がある場合に使用します。音声チャンクを逐次送信でき、パイプラインが「アクティビティ検知」により適切なタイミングでエージェントワークフローを自動実行します。 ## 結果 -音声パイプラインの実行結果は `StreamedAudioResult` です。このオブジェクトを通じて、発生するイベントをストリーミング形式で受け取れます。`VoiceStreamEvent` には次の種類があります。 +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。このオブジェクトからイベントをストリーミング形式で受け取れます。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] には次の種類があります。 -1. `VoiceStreamEventAudio` — 音声チャンクを含みます。 -2. `VoiceStreamEventLifecycle` — ターンの開始や終了などライフサイクルイベントを通知します。 -3. `VoiceStreamEventError` — エラーイベントです。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] + 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] + ターン開始や終了などのライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] + エラーイベントです。 ```python @@ -76,4 +83,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK には `StreamedAudioInput` に対する組み込みの割り込み機能はまだありません。そのため、検知された各ターンごとにワークフローが個別に実行されます。アプリケーション内で割り込みを扱いたい場合は、`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 afbddb9c8..9a9c75efa 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -4,9 +4,9 @@ search: --- # クイックスタート -## 前提条件 +## 事前準備 -Agents SDK の基本 [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。そのうえで、SDK からオプションの音声依存関係をインストールします: +まず、基礎的な [クイックスタート手順](../quickstart.md) に従って Agents SDK をセットアップし、仮想環境を作成してください。その後、SDK のオプション音声依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -ここで理解すべき主要な概念は `VoicePipeline` で、次の 3 つのステップで構成されます: +理解しておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは次の 3 ステップで構成されます。 -1. 音声をテキストに変換する Speech-to-Text モデルを実行します。 -2. 通常はエージェント的ワークフローであるコードを実行して、実行結果を生成します。 -3. 実行結果のテキストを音声に戻す Text-to-Speech モデルを実行します。 +1. 音声をテキストに変換する speech-to-text モデルを実行する。 +2. 通常はエージェント的ワークフローであるあなたのコードを実行し、結果を生成する。 +3. 結果のテキストを音声に変換する text-to-speech モデルを実行する。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定しましょう。この SDK でエージェントを構築したことがある方にはおなじみの作業です。ここでは 2 つのエージェントとハンドオフ、そして 1 つのツールを用意します。 +まず、いくつかのエージェントを設定します。この作業は、これまでに SDK でエージェントを構築したことがある場合は馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして `SingleAgentVoiceWorkflow` を使用し、シンプルな音声パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインを構築します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけます！ 自分でエージェントと会話できるデモとして、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例もぜひご覧ください。 \ No newline at end of file +この例を実行すると、エージェントがあなたに話しかけてきます！自身でエージェントと会話できるデモを確認するには、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のサンプルを参照してください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index a4de0a6a1..6afc2def9 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -エージェントのトレーシングと同様に、音声パイプラインも自動でトレーシングされます。 +[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシングについては上記のトレーシングドキュメントをご覧ください。加えて、 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使用してパイプラインのトレーシングを設定できます。 +基本的なトレーシング情報については上記のドキュメントをご覧ください。また、`VoicePipelineConfig` を使用してパイプラインのトレーシングを追加で設定できます。 -主なトレーシング関連フィールドは次のとおりです。 +主なトレーシング関連フィールドは次のとおりです: -- [`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] : トレース Workflow の名前。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id] : 複数のトレースを関連付けるための `group_id` 。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled] : トレースに追加するメタデータ。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、 Workflow 内部の処理には影響しません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース Workflow の名前です。 +- [`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