diff --git a/docs/ja/agents.md b/docs/ja/agents.md index e461d54f1..03698e118 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,22 +4,23 @@ search: --- # エージェント -エージェントはアプリケーションの主要な構成要素です。エージェントとは、instructions と tools で構成された大規模言語モデル (LLM) です。 +エージェントは、アプリの中核となるビルディングブロックです。エージェントは、 instructions とツールで構成された大規模言語モデル LLM です。 ## 基本設定 -エージェントでよく設定するプロパティは次のとおりです。 +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 -- `model`: 使用する LLM を指定します。任意の `model_settings` で temperature、top_p などのモデル調整パラメーターを設定できます。 -- `tools`: エージェントがタスクを達成するために使用できる tools です。 +- `name`: エージェントを識別する必須の文字列 +- `instructions`: developer メッセージ、または system prompt とも呼ばれます +- `model`: 使用する LLM と、temperature や top_p などのモデルチューニングパラメーターを指定するオプションの `model_settings` +- `tools`: エージェントがタスク達成のために使用できるツール ```python from agents import Agent, ModelSettings, function_tool @function_tool def get_weather(city: str) -> str: + """returns weather info for the specified city.""" return f"The weather in {city} is sunny" agent = Agent( @@ -32,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは汎用的に `context` 型を取り込みます。コンテキストは dependency-injection (依存性注入) 用のオブジェクトで、あなたが作成して `Runner.run()` に渡すことで、すべてのエージェント、tool、ハンドオフなどに共有されます。実行中の依存関係や状態をまとめて保持する入れ物として機能し、任意の Python オブジェクトを渡せます。 +エージェントは `context` 型に対してジェネリックです。 context は依存性インジェクション用のツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係と状態の入れ物として機能します。 context には任意の Python オブジェクトを指定できます。 ```python @dataclass @@ -50,7 +51,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](https://docs.pydantic.dev/) オブジェクトですが、 Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型 (dataclass、list、TypedDict など) であればサポートされます。 ```python from pydantic import BaseModel @@ -71,11 +72,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは必要に応じてそれらに委任できます。これは、単一タスクに特化したモジュール化されたエージェントをオーケストレーションする強力なパターンです。詳しくは [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すことで、エージェントは関連がある場合にそれらへ委任を選択できます。これは、単一タスクに特化したモジュール化されたエージェントをオーケストレーションできる強力なパターンです。詳しくは [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -96,7 +97,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を渡せますが、関数を介して動的に instructions を生成することも可能です。その関数は agent と context を受け取り、プロンプトを返さなければなりません。同期関数と `async` 関数のどちらも利用できます。 +多くの場合、エージェント作成時に instructions を指定できますが、関数を介して動的に instructions を提供することも可能です。この関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を受け付けます。 ```python def dynamic_instructions( @@ -111,17 +112,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクル イベント (hooks) -エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスを継承し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観察したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。 `hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールを利用すると、エージェントの実行と並行してユーザー入力のチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 +ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をチェックすることが可能です。詳しくは [ガードレール](guardrails.md) のドキュメントをご覧ください。 -## エージェントのクローン／コピー +## エージェントのクローン / コピー -エージェントの `clone()` メソッドを使うと、既存のエージェントを複製し、必要に応じて任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -138,15 +139,15 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -tools のリストを渡しても、LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、ツール使用を強制できます。有効な値は次のとおりです。 +ツールのリストを渡しても、 LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです。 -1. `auto`：LLM がツールを使うかどうかを判断します。 -2. `required`：LLM にツール使用を必須とします (ただしどのツールを使うかは賢く選択します)。 -3. `none`：LLM にツールを使用しないことを必須とします。 -4. 具体的な文字列 (例: `my_tool`) を設定すると、LLM はそのツールを必ず使用します。 +1. `auto` : LLM がツールを使用するかどうかを判断します。 +2. `required` : LLM にツール使用を必須にします (どのツールを使うかはインテリジェントに選択)。 +3. `none` : LLM にツールを使用しないことを要求します。 +4. 具体的な文字列 (例: `my_tool`) を指定すると、その特定のツールを LLM に使用させます。 !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に自動で `tool_choice` を "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。ツールの実行結果が再び LLM に送られ、`tool_choice` の設定により新たなツール呼び出しが発生し続けるのが無限ループの原因です。 + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。無限ループの原因は、ツールの結果が LLM に送信され、その結果 `tool_choice` により再度ツール呼び出しが生成される、という循環にあります。 - ツール呼び出し後に自動モードで継続せず完全に停止したい場合は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定してください。ツールの出力をそのまま最終応答として使用し、追加の LLM 処理を行いません。 \ No newline at end of file + ツール呼び出し後に (auto モードで続行せず) エージェントを完全に停止させたい場合は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定してください。これにより、ツールの出力をそのまま最終応答として使用し、追加の LLM 処理を行いません。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index ca7dea2ca..d540cb9f4 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、 SDK は import された時点で、 LLM リクエストとトレーシング用に `OPENAI_API_KEY` 環境変数を探します。アプリを起動する前にその環境変数を設定できない場合は、[`set_default_openai_key()`][agents.set_default_openai_key] 関数を使ってキーを設定できます。 +既定では、 SDK はインポート時に LLM リクエストおよびトレーシング用の `OPENAI_API_KEY` 環境変数を参照します。アプリ起動前にこの環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -別の方法として、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。これを変更したい場合は、[`set_default_openai_client()`][agents.set_default_openai_client] 関数を使用してください。 +別の方法として、使用する OpenAI クライアントを構成することもできます。既定では、 SDK は `AsyncOpenAI` インスタンスを作成し、前述の環境変数またはデフォルトキーを使用します。 [set_default_openai_client()][agents.set_default_openai_client] 関数を使ってこれを変更できます。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは、 OpenAI Responses API を使用します。これを Chat Completions API に変更したい場合は、[`set_default_openai_api()`][agents.set_default_openai_api] 関数をご利用ください。 +さらに、使用する OpenAI API をカスタマイズすることも可能です。既定では OpenAI Responses API が使用されます。 [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 ガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログに含まれる機微なデータ +### ログ内の機微データ -一部のログには機微なデータ（例: ユーザー データ）が含まれる場合があります。これらのデータの記録を無効化したい場合は、以下の環境変数を設定してください。 +一部のログには (ユーザーデータなどの) 機微データが含まれる場合があります。これらのデータをログに出力したくない場合は、次の環境変数を設定してください。 -LLM の入力および出力のロギングを無効にするには: +LLM の入力および出力のログを無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力および出力のロギングを無効にするには: +ツールの入力および出力のログを無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index eb1410d93..8c082759b 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +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 などの ユーザー 情報) -- 依存関係 (例: ロガーオブジェクト、データフェッチャーなど) -- ヘルパー関数 +- 実行に関するコンテキストデータ（例: username/uid やその他の user 情報など） +- 依存関係（例: logger オブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは **LLM に送信されません**。あくまでローカルで読み書きやメソッド呼び出しを行うためのオブジェクトです。 + コンテキストオブジェクトは **LLM には送信されません**。ローカル専用のオブジェクトであり、読み書きやメソッド呼び出しが自由に行えます。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型で構いません。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。 2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. エージェントにジェネリック型 `UserInfo` を指定することで、型チェッカーがエラーを検出できます（異なるコンテキスト型のツールを渡そうとした場合など）。 +3. エージェントにジェネリック型 `UserInfo` を付与することで型チェッカーが誤りを検出できます（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント / LLM コンテキスト -LLM が呼び出される際、LLM が参照できるデータは会話履歴のみです。そのため、新しいデータを LLM に渡したい場合は、会話履歴に含める形で提供する必要があります。主な方法は次のとおりです。 +LLM が呼び出されるとき、LLM が閲覧できるデータは会話履歴に含まれるもの **のみ** です。したがって、新しいデータを LLM に参照させたい場合は、会話履歴に組み込む形で提供する必要があります。代表的な方法は次のとおりです。 -1. Agent の `instructions` に追加する。これは「システムプロンプト」や「デベロッパーメッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。ユーザー名や現在の日付など、常に有用な情報を渡す場合によく使われます。 -2. `Runner.run` を呼び出す際の `input` に追加する。`instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 上でより下位のメッセージとして渡せます。 -3. function tools を通じて公開する。オンデマンドでコンテキストを取得させたい場合に便利で、LLM が必要に応じてツールを呼び出してデータを取得します。 -4. retrieval や web search を使用する。retrieval はファイルやデータベースから関連データを取得し、web search は Web から取得します。これにより、回答を関連コンテキストで「グラウンディング」できます。 \ No newline at end of file +1. Agent の `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。system prompt は静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でもかまいません。たとえば user の名前や現在の日付など、常に有用な情報を渡す際によく使われます。 +2. `Runner.run` を呼び出す際の `input` に追加する。この方法は `instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位メッセージとして配置できる点が異なります。 +3. 関数ツール経由で公開する。オンデマンドでコンテキストを取得させたい場合に便利です。LLM が必要に応じてツールを呼び出し、データを取得できます。 +4. retrieval や web search を使用する。これらはファイルやデータベースから関連データを取得する retrieval、または Web から情報を取得する web search といった特殊ツールです。関連コンテキストに基づいた「根拠づけ」を行いたい場合に有効です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index b00ce3f9a..2ca510701 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,41 +4,45 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションには、SDK のさまざまな実装例が掲載されています。これらの例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +さまざまな サンプル実装 を、[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで確認できます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 + ## カテゴリー -- **[エージェントパターン](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーでは、以下のような一般的なエージェント設計パターンを紹介します。 +- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** + このカテゴリーのコード例では、一般的な エージェント の設計パターンを示しています。例: + - 決定論的ワークフロー - - エージェントをツールとして利用 - - 複数エージェントの並列実行 + - ツールとしての エージェント + - エージェント の並列実行 -- **[基本](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - ここでは、SDK の基礎となる機能を確認できます。 - - 動的な system prompt - - ストリーミング出力 - - ライフサイクルイベント +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + 基本的な SDK の機能を紹介するコード例です。例: -- **[ツール例](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索やファイル検索などの OpenAI がホストするツールを実装し、エージェントに統合する方法を学べます。 + - 動的な システムプロンプト + - ストリーミング 出力 + - ライフサイクル イベント -- **[モデルプロバイダー](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを SDK と併用する方法を学べます。 +- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + Web 検索 や ファイル検索 など、OpenAI がホストするツール を実装し、エージェントに統合する方法を学べます。 -- **[ハンドオフ](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフを実践的に示す例です。 +- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK と組み合わせて使う方法を紹介します。 -- **[MCP](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP でエージェントを構築する方法を学べます。 +- **[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 を使った エージェント の構築方法を学べます。 - **[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**: シンプルな deep research クローン。 + より実践的なアプリケーションを示す 2 つの構築例 + + - **customer_service**: 航空会社向けカスタマーサービス システムの例 + - **research_bot**: シンプルな ディープリサーチ クローン -- **[音声](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS や STT モデルを使用した音声エージェントの例を確認できます。 +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + TTS と STT モデルを用いた ボイス エージェント の例をご覧いただけます。 -- **[リアルタイム](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を用いてリアルタイム体験を構築する方法を示す例です。 \ No newline at end of file +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使って リアルタイム 体験を構築する方法を示すコード例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index 568c6c50c..17f5fbe5c 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックとバリデーションを行えます。たとえば、非常に高性能（その分、低速かつ高コスト）のモデルを用いて顧客の問い合わせを処理するエージェントがあるとします。悪意のあるユーザーに、そのモデルを使って数学の宿題を解かせたくはありません。そこで、低コストかつ高速なモデルでガードレールを実行します。ガードレールが不正利用を検知した場合、ただちにエラーを発生させ、高価なモデルの実行を止めて時間とコストを節約できます。 +ガードレールはエージェントと _並列_ に実行され、ユーザー入力のチェックおよびバリデーションを行えるようにします。たとえば、カスタマーリクエストを処理するために非常に高性能（つまり遅くて高価）なモデルを使用する エージェント があるとしましょう。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせようとするのは避けたいはずです。そこで、低コストかつ高速なモデルでガードレールを実行できます。ガードレールが悪意ある使用を検知した場合、直ちにエラーを発生させ、高価なモデルの実行を止めて時間とコストを節約できます。 -ガードレールには 2 種類あります: +ガードレールには 2 種類あります。 -1. Input ガードレールは最初のユーザー入力に対して実行されます -2. Output ガードレールは最終的なエージェント出力に対して実行されます +1. 入力ガードレール: 初期ユーザー入力に対して実行されます +2. 出力ガードレール: 最終エージェント出力に対して実行されます -## Input ガードレール +## 入力ガードレール -Input ガードレールは 3 段階で実行されます: +入力ガードレールは 3 ステップで実行されます。 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成します。その結果は [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップされます。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへ適切に応答するか、例外を処理できます。 +2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップされます。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な対応や例外処理を行えます。 !!! Note - Input ガードレールはユーザー入力に対して実行されることを想定しています。そのためガードレールはエージェントが *最初の* エージェントである場合にのみ実行されます。「`guardrails` プロパティがエージェントにあるのはなぜで、`Runner.run` に渡さないのか？」と思うかもしれません。ガードレールは実際のエージェントと強く関連する傾向があるため、エージェントごとに異なるガードレールを設定します。コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントが *最初* のエージェントである場合にのみガードレールが実行されます。「guardrails」プロパティがエージェント上にある理由は何でしょうか？ `Runner.run` に渡さないのは、ガードレールが実際の Agent に密接に関係する傾向があるためです。エージェントごとに異なるガードレールを実行することが多く、コードを同じ場所に置くことで可読性が向上します。 -## Output ガードレール +## 出力ガードレール -Output ガードレールは 3 段階で実行されます: +出力ガードレールは 3 ステップで実行されます。 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成します。その結果は [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップされます。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへ適切に応答するか、例外を処理できます。 +2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップされます。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な対応や例外処理を行えます。 !!! Note - Output ガードレールは最終的なエージェント出力に対して実行されることを想定しています。そのためガードレールはエージェントが *最後の* エージェントである場合にのみ実行されます。Input ガードレールと同様に、ガードレールは実際のエージェントと強く関連するため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終エージェント出力に対して実行されることを想定しているため、エージェントが *最後* のエージェントである場合にのみガードレールが実行されます。入力ガードレールと同様に、ガードレールは実際の Agent に密接に関係するため、コードを同じ場所に置くことで可読性が向上します。 -## Tripwires +## トリップワイヤ -入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーが発火したガードレールを検知すると、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤでそれを通知できます。トリップワイヤが発火したガードレールを検知するとすぐに `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。以下の例では、その裏でエージェントを実行してこれを行います。 +入力を受け取り [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、その内部で エージェント を実行してガードレールを実装します。 ```python from pydantic import BaseModel @@ -94,12 +94,12 @@ async def main(): print("Math homework guardrail tripped") ``` -1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果には追加情報を含めることができます。 -4. こちらがワークフローを定義する実際のエージェントです。 +1. この エージェント をガードレール関数内で使用します。 +2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレール結果に追加情報を含めることができます。 +4. こちらが実際のエージェントで、ワークフローを定義します。 -Output ガードレールも同様です。 +出力ガードレールも同様です。 ```python from pydantic import BaseModel @@ -152,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 f8e29cca2..3da4ab341 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,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のように エージェント を直接渡すことも、`handoff()` 関数を使用することもできます。 +1. `billing_agent` のように エージェント を直接渡すことも、`handoff()` 関数を使うこともできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数ではさまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数を使うと、以下の項目をカスタマイズできます。 -- `agent`: ハンドオフ先の エージェント です。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、これは `transfer_to_` になります。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` の既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されたことがわかった時点でデータ取得を開始するなどに役立ちます。この関数は エージェント コンテキストを受け取り、オプションで LLM が生成した入力も受け取ることができます。入力データは `input_type` パラメーターによって制御されます。 -- `input_type`: ハンドオフが受け取る入力の型 (任意)。 -- `input_filter`: 次の エージェント が受け取る入力をフィルターできます。詳細は後述します。 +- `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 from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフの入力 +## ハンドオフ入力 -状況によっては、ハンドオフを呼び出す際に LLM から何らかのデータを渡してほしい場合があります。たとえば「Escalation agent」へのハンドオフを考えてみましょう。理由を渡してログに残したいかもしれません。 +状況によっては、ハンドオフを呼び出す際に LLM から追加データを渡したい場合があります。たとえば「 Escalation agent 」へのハンドオフでは、記録用に理由を渡したいかもしれません。 ```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 a13c6ec3b..37ec0d97b 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 とツールを備えた LLM +- **ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任できる +- **ガードレール**: エージェントへの入力を検証できる +- **セッション**: エージェントの実行をまたいで会話履歴を自動的に保持する -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係性を表現でき、学習コストを抑えながら実運用レベルのアプリケーションを構築できます。さらに、SDK にはワークフローを可視化・デバッグできる **トレーシング** が組み込まれており、評価やファインチューニング、蒸留など OpenAI の各種ツールも利用可能です。 +Python と組み合わせることで、これらの基本コンポーネントだけでツールとエージェント間の複雑な関係を表現でき、急な学習コストなく実運用レベルのアプリケーションを構築できます。さらに、SDK には **トレーシング** が組み込まれており、エージェントのフローを可視化・デバッグできるだけでなく、評価やモデルのファインチューニングにも活用できます。 -## Agents SDK の利点 +## Agents SDK を使用する理由 -本 SDK には、次の 2 つの設計原則があります。 +SDK には次の 2 つの設計原則があります: -1. 使う価値がある十分な機能を備えつつ、学習が速いように基本コンポーネントを最小限にする。 -2. すぐに使える状態で動作する一方、挙動を細かくカスタマイズできる。 +1. 使う価値のある十分な機能を備えつつ、基本コンポーネントを少数に絞り、学習が迅速に行えること。 +2. 箱から出してすぐに使える一方で、動作を細部までカスタマイズできること。 -主な機能は以下のとおりです。 +SDK の主な機能は次のとおりです: -- **Agent loop**: ツール呼び出し、結果を LLM へ送信、LLM が完了するまでループする処理を内蔵 -- **Python ファースト**: 新しい抽象を覚えることなく、Python の言語機能でエージェントをオーケストレーション・連鎖可能 -- **ハンドオフ**: 複数エージェント間の協調や委任を行える強力な機能 -- **ガードレール**: エージェントと並行して入力検証を実行し、チェック失敗時には早期終了 -- **セッション**: エージェント実行間の会話履歴を自動管理し、手動での状態管理を不要化 -- **Function tools**: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic でのバリデーションを提供 -- **トレーシング**: ワークフローの可視化・デバッグ・モニタリングに加え、OpenAI の評価、ファインチューニング、蒸留ツールを利用可能 +- Agent loop: ツール呼び出し、結果を LLM へ送信、LLM が完了するまでのループ処理を行うループが組み込み済み。 +- Python ファースト: 新しい抽象を学ぶことなく、Python の言語機能でエージェントをオーケストレーションおよび連鎖できます。 +- ハンドオフ: 複数のエージェント間で調整・委任を行う強力な機能。 +- ガードレール: エージェントと並列に入力検証やチェックを実行し、チェックに失敗した時点で早期に停止します。 +- セッション: エージェント実行間の会話履歴を自動で管理し、手動で状態を扱う必要をなくします。 +- Function tools: どんな Python 関数でもツール化でき、自動的にスキーマを生成し、Pydantic による検証を行います。 +- トレーシング: ワークフローを可視化・デバッグ・監視できるトレーシングが組み込まれており、OpenAI の評価、ファインチューニング、蒸留ツールも利用できます。 ## インストール @@ -36,7 +36,7 @@ Python と組み合わせることで、これらの基本コンポーネント pip install openai-agents ``` -## Hello World 例 +## Hello World の例 ```python from agents import Agent, Runner @@ -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 6d45c717e..6538218f1 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -2,25 +2,25 @@ search: exclude: true --- -# Model context protocol (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 にコンテキストを提供する方法を標準化するオープンプロトコルです。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 filesystem サーバーを使用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーへ `list_tools()` を呼び出し、LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出し、 LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 ```python @@ -54,11 +54,11 @@ agent=Agent( ## ツールのフィルタリング -MCP サーバーではツールフィルターを設定して、エージェントが利用できるツールを制御できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーではツールフィルタを設定することで、エージェントが利用できるツールを制限できます。SDK では静的フィルタリングと動的フィルタリングの両方をサポートしています。 ### 静的ツールフィルタリング -単純な許可 / ブロック リストの場合は静的フィルタリングを使用します。 +単純な許可 / ブロックリストの場合は静的フィルタリングを使用できます。 ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方を設定した場合の処理順序は次のとおりです。** -1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールのみを残します。 -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 @@ -141,14 +141,14 @@ server = MCPServerStdio( ## プロンプト -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()` を呼び出します。 -## エンドツーエンド code examples +## エンドツーエンドのコード例 -完全な動作例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) に動作する完全なコード例があります。 ## トレーシング -[トレーシング](./tracing.md) は MCP 操作を自動的に記録します。内容は次のとおりです。 +[トレーシング](./tracing.md) では MCP の操作が自動的に記録されます。具体的には次の内容が含まれます。 -1. ツール一覧取得のための MCP サーバー呼び出し +1. MCP サーバーへのツール一覧取得呼び出し 2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index a32e93d05..f236a76e4 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,54 +4,49 @@ search: --- # モデル -Agents SDK には OpenAI モデルの 2 種類が標準でサポートされています: +Agents SDK には、すぐに使える OpenAI モデルが 2 種類用意されています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい Responses API を用いて OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、Chat Completions API を用いて 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 を呼び出します。 -## Non-OpenAI モデル +## OpenAI 以外のモデル -ほとんどの Non-OpenAI モデルは [LiteLLM インテグレーション](./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", ...) ``` -### Non-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 互換エンドポイントを持つ場合、`base_url` と `api_key` を設定できます。設定例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] - これは `Runner.run` レベルで、「この実行ではすべてのエージェントにカスタムモデルプロバイダーを使う」と指定できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) をご覧ください。 -3. [`Agent.model`][agents.agent.Agent.model] - 特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせられます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) をご覧ください。多くのモデルを簡単に使う方法として [LiteLLM インテグレーション](./litellm.md) があります。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、`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) をご覧ください。 +3. [`Agent.model`][agents.agent.Agent.model] を使うと、特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。詳細は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) をご覧ください。ほとんどのモデルを簡単に利用する方法としては [LiteLLM 連携](./litellm.md) が便利です。 -`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することをおすすめします。 +`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 !!! note - - これらの例では、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API/モデルを使用しています。もしご利用の LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 + これらの例では Chat Completions API/モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もし LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 ## モデルの組み合わせ -1 つのワークフロー内でエージェントごとに異なるモデルを使いたい場合があります。たとえば、簡単な振り分けには小さく高速なモデルを、複雑なタスクには大きく高性能なモデルを使うといったパターンです。[`Agent`][agents.Agent] を設定する際には、次のいずれかでモデルを指定できます: +一つのワークフロー内でエージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型かつ高速なモデルを、複雑なタスクには大型で高性能なモデルを使用する、といった具合です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選択できます。 1. モデル名を直接渡す -2. 任意のモデル名 + その名前を Model インスタンスにマップできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す -3. [`Model`][agents.models.interface.Model] 実装を直接渡す +2. 任意のモデル名と、それを Model インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す +3. [`Model`][agents.models.interface.Model] 実装を直接渡す !!!note - - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとに 1 種類のモデル形状を使うことを推奨します。両者は対応する機能や tools が異なるためです。もし混在が必要な場合は、利用する全機能が両方でサポートされているか確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、ワークフローごとに単一のモデル形状を使用することを推奨します。両形状はサポートする機能や tools が異なるためです。もし両形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能かを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -85,9 +80,9 @@ async def main(): ``` 1. OpenAI モデル名を直接設定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +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 +95,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使う場合は [追加のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) (例: `user`, `service_tier` など) も利用できます。トップレベルにない場合は `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 +111,29 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー利用時によくある問題 +## 他社 LLM プロバイダー使用時の一般的な問題 -### トレーシング クライアントのエラー 401 +### Tracing クライアントエラー 401 -トレースは OpenAI サーバーへアップロードされるため、OpenAI API キーがない場合にエラーが発生します。以下のいずれかで解決できます: +Tracing 関連のエラーが発生する場合、トレースが 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] - このキーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. OpenAI 以外のトレースプロセッサーを使用: [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照 +1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] + ※ この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. OpenAI 以外のトレースプロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、ほとんどの LLM プロバイダーはまだ対応していません。そのため 404 などのエラーが発生する場合があります。以下のいずれかで解決してください: +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/) にあります。 + 例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 ### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーになることがあります: +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。次のようなエラーが発生する場合があります。 ``` @@ -146,12 +141,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは、JSON 出力には対応しているものの、出力に使用する `json_schema` を指定できないプロバイダーの制限です。修正に取り組んでいますが、JSON スキーマ出力に対応しているプロバイダーを利用することを推奨します。そうでない場合、生成される JSON が不正でアプリが頻繁に壊れる可能性があります。 +これは一部プロバイダーの制限で、JSON 出力には対応していても `json_schema` を指定できないためです。現在修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーを利用することを推奨します。そうしないと、JSON が不正な形式で返されアプリが壊れることがあります。 -## プロバイダーをまたいだモデルの組み合わせ +## プロバイダー間でのモデル混在 -モデルプロバイダー間の機能差に注意しないとエラーが発生することがあります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホストされたファイル検索と Web 検索をサポートしますが、多くの他プロバイダーは対応していません。以下の制限に注意してください: +モデルプロバイダーごとの機能差に注意しないと、エラーが発生する可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホストされた file search・web search をサポートしていますが、多くの他社プロバイダーはこれらをサポートしていません。以下の制限に注意してください。 -- 対応していないプロバイダーにはサポート外の `tools` を送らない -- テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしないプロバイダーは無効な JSON を返す場合がある点を認識する \ No newline at end of file +- サポートしていない `tools` を理解しないプロバイダーへ送らない +- テキストのみ対応のモデルを呼び出す前にマルチモーダル入力を除外する +- structured JSON outputs に対応していないプロバイダーでは、不正な JSON が返ることがある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index dd3a53d58..82978bda8 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 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題を見つけた場合は [ GitHub の issue ](https://github.com/openai/openai-agents-python/issues) で報告してください。迅速に対応します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加したことで、任意の AI モデルを使用できるようになりました。 +[ LiteLLM ](https://docs.litellm.ai/docs/) は、 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`、API キーに OpenAI API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic API キー +- モデルに `openai/gpt-4.1` 、API キーに OpenAI API キー +- モデルに `anthropic/claude-3-5-sonnet-20240620` 、API キーに Anthropic API キー - など -LiteLLM がサポートしているモデルの一覧は、[litellm providers docs](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 6b32b6d21..07c6c294d 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. コードによるオーケストレーション: コードでエージェントのフローを決定します。 -これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあるため、以下で説明します。 +これらのパターンは組み合わせることができ、それぞれに以下のようなトレードオフがあります。 ## LLM によるオーケストレーション -エージェントとは、LLM に instructions、tools、handoffs を組み合わせたものです。オープンエンドなタスクが与えられた場合、LLM はタスクに取り組む方法を自律的に計画し、tools を使って行動やデータ取得を行い、handoffs を使ってサブエージェントにタスクを委任できます。たとえば、リサーチ用エージェントには次のようなツールを持たせることができます。 +エージェントとは、instructions・tools・ハンドオフを備えた LLM です。これにより、オープンエンドなタスクに対して LLM が自律的に計画を立て、tools を使ってアクションを実行しデータを取得し、ハンドオフでサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のような tools を装備できます。 - Web 検索でオンライン情報を取得 -- ファイル検索とリトリーバルで独自データや接続先を検索 +- ファイル検索と取得で独自データや接続先を検索 - コンピュータ操作でコンピュータ上のアクションを実行 -- コード実行でデータ解析を実施 -- 計画立案やレポート作成などに長けた専門エージェントへの handoffs +- コード実行でデータ分析を行う +- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドであり LLM の知性に頼りたい場合に最適です。主なポイントは以下のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知性に依存したい場合に適しています。重要なポイントは次のとおりです。 -1. 質の高いプロンプトに投資する。利用可能なツール、その使い方、守るべきパラメーターを明確にします。 -2. アプリを監視し、改善を重ねる。問題が発生した箇所を確認し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえばループで実行し、自己批評させる、またはエラーメッセージを提供して改善させるなどです。 -4. 何でもこなす汎用エージェントではなく、 1 つのタスクに特化したエージェントを用意します。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク性能を向上できます。 +1. 質の高いプロンプトに投資する。利用可能な tools・その使い方・動作パラメーターを明確に伝えます。 +2. アプリをモニタリングして改善を繰り返す。問題が起きる箇所を確認し、プロンプトを調整します。 +3. エージェントに内省と改善を許可する。たとえばループで実行し自己批評させる、エラーメッセージを渡して改善させるなどです。 +4. 何でもできる汎用エージェントより、一つのタスクに特化したエージェントを用意しましょう。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を向上させられます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードでオーケストレーションすると速度・コスト・性能面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を用いて、コードで検査できる適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーへ分類させ、そのカテゴリーに応じて次のエージェントを選択できます。 -- 複数のエージェントをチェーンし、前の出力を次の入力に変換する。ブログ記事執筆を例にすると、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善という一連のステップに分解できます。 -- タスクを実行するエージェントと、評価してフィードバックを返すエージェントを `while` ループで回し、評価者が基準を満たしたと判断するまで繰り返します。 -- Python の基本コンポーネントである `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 8797a4ee7..8c876a993 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -この手順は一度だけ実行すれば十分です。 +一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -22,7 +22,7 @@ python -m venv .venv source .venv/bin/activate ``` -### Agents SDK のインストール +### Agents SDK のインストール ```bash pip install openai-agents # or `uv add openai-agents`, etc @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -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-... ``` -## 最初のエージェントを作成する +## 最初の エージェント の作成 -エージェントは instructions、名前、そして `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 @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## ハンドオフを定義する +## ハンドオフの定義 -各エージェントでは、タスクを進めるために選択できる送信側ハンドオフオプションの一覧を定義できます。 +各エージェントで、タスクを進めるために選択できる送信先ハンドオフのインベントリを定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ 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 Dashboard の Trace viewer](https://platform.openai.com/traces) に移動してトレースを表示してください。 +エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace ビューア](https://platform.openai.com/traces)に移動し、エージェント実行のトレースを確認してください。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう。 +より複雑なエージェント フローの構築方法を学びましょう。 -- [Agents](agents.md) の設定方法を学ぶ。 -- [エージェントの実行](running_agents.md) について学ぶ。 -- [tools](tools.md)、[guardrails](guardrails.md)、[models](models/index.md) について学ぶ。 \ No newline at end of file +- [エージェント](agents.md) の設定方法を学ぶ +- [エージェントの実行](running_agents.md) について学ぶ +- [tools](tools.md)、[guardrails](guardrails.md)、[models](models/index.md) について学ぶ \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index d48e5c391..47c3b41cb 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,66 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK のリアルタイム機能を使って音声対応 AI エージェントを構築する方法を詳しく説明します。 +本ガイドでは、OpenAI Agents SDK の realtime 機能を利用して音声対応の AI エージェントを構築する方法を詳しく解説します。 -!!! warning "ベータ機能" -リアルタイムエージェントはベータ版です。実装の改善に伴い、互換性が壊れる変更が発生する可能性があります。 +!!! warning "Beta 機能" +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -リアルタイムエージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する対話フローを実現します。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声会話を行いながら、割り込みにもスムーズに対応できます。 +Realtime エージェントは、音声とテキストをリアルタイムで処理し、リアルタイム音声で応答する対話フローを実現します。OpenAI の Realtime API との持続的な接続を維持し、低レイテンシーで自然な音声会話を可能にし、割り込みにもスムーズに対応します。 ## アーキテクチャ ### コアコンポーネント -リアルタイムシステムは、以下の主要コンポーネントで構成されます。 +Realtime システムは以下の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 1 回の対話セッション。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェント。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得します。 +- **RealtimeSession**: 1 つの対話セッション。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装）。 ### セッションフロー -典型的なリアルタイムセッションは次の流れで進みます。 +典型的な realtime セッションは以下の流れで進行します。 -1. instructions、tools、handoffs を使用して **RealtimeAgent** を作成する -2. エージェントと設定オプションを指定して **RealtimeRunner** をセットアップする -3. `await runner.run()` で **セッションを開始** し、RealtimeSession を受け取る -4. `send_audio()` または `send_message()` で **音声またはテキストメッセージを送信** する -5. セッションをイテレートして **イベントを監視** する - - イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーなどが含まれます -6. ユーザーがエージェントの発話を遮った場合に **割り込みを処理** する（現在の音声生成が自動で停止） +1. instructions、tools、handoffs を指定して **RealtimeAgent** を作成します。 +2. エージェントと設定オプションを使用して **RealtimeRunner** をセットアップします。 +3. `await runner.run()` で **セッションを開始**し、RealtimeSession を取得します。 +4. `send_audio()` または `send_message()` を使って **音声またはテキストメッセージを送信**します。 +5. セッションをイテレートして **イベントを監視**します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどがあります。 +6. ユーザーがエージェントの発話に被せて話した場合は **割り込みを処理**し、現在の音声生成を自動的に停止します。 -セッションは会話履歴を保持し、リアルタイムモデルとの永続接続を管理します。 +セッションは会話履歴を保持し、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 などその他の機能は同様に動作します。 ## セッション設定 ### モデル設定 -セッション設定では基盤となるリアルタイムモデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声（alloy、echo、fable、onyx、nova、shimmer）や対応モダリティ（テキスト／音声）を指定できます。音声の入出力フォーマットは PCM16 がデフォルトですが、変更可能です。 +セッション設定では、基盤となる realtime モデルの挙動を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、voice の選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text と/または audio）を設定できます。入出力の音声フォーマットは両方とも設定可能で、デフォルトは PCM16 です。 ### オーディオ設定 -オーディオ設定では、音声入力と出力の扱いを制御します。Whisper などのモデルを使った音声入力の文字起こし、言語の指定、ドメイン固有語句の精度を高めるための transcription prompts を設定できます。ターン検出では、音声活動検出の閾値、無音時間、検出前後のパディングなどにより、エージェントが応答を開始・停止するタイミングを調整します。 +オーディオ設定では、音声入力と出力の扱い方を制御します。Whisper などのモデルを用いた入力音声の文字起こし、言語設定、ドメイン固有用語の認識精度を高める文字起こしプロンプトを指定できます。ターン検知設定では、音声活動検出のしきい値、無音時間、検出された音声前後のパディングを調整し、エージェントがいつ応答を開始・停止すべきかを制御します。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、リアルタイムエージェントでも会話中に実行される function tools を利用できます。 +通常のエージェントと同様に、realtime エージェントでも会話中に実行される function tools をサポートしています。 ```python from agents import function_tool @@ -91,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフを使うと、会話を専門化されたエージェント間で引き継げます。 +ハンドオフを使用すると、会話を専門のエージェント間で転送できます。 ```python from agents.realtime import realtime_handoff @@ -118,42 +117,42 @@ main_agent = RealtimeAgent( ) ``` -## イベント処理 +## イベントハンドリング -セッションはストリーミングでイベントを送信するため、セッションオブジェクトをイテレートして受け取ります。主なイベント: +セッションはイベントをストリーミングします。セッションオブジェクトをイテレートしてイベントを監視できます。主なイベントは次のとおりです。 -- **audio**: エージェントの応答からの raw 音声データ +- **audio**: エージェントの応答から得られる raw 音声データ - **audio_end**: エージェントの発話が終了 -- **audio_interrupted**: ユーザーがエージェントの発話を遮った -- **tool_start/tool_end**: ツール実行の開始／終了 -- **handoff**: エージェントのハンドオフが発生 +- **audio_interrupted**: ユーザーがエージェントを割り込み +- **tool_start/tool_end**: tool 実行のライフサイクル +- **handoff**: エージェント間の handoff が発生 - **error**: 処理中にエラーが発生 -詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +完全なイベント詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -リアルタイムエージェントでは出力ガードレールのみサポートされます。リアルタイム生成中のパフォーマンスを保つためにデバウンスされ、毎回の単語ではなく一定間隔で実行されます。デフォルトのデバウンス長は 100 文字ですが、設定で変更できます。 +Realtime エージェントでは出力ガードレールのみがサポートされています。パフォーマンスへの影響を避けるため、ガードレールは毎単語ではなくデバウンス（間隔制御）されて定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレールが発動すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答を割り込むことがあります。デバウンスにより、安全性とリアルタイム性能のバランスを取ります。テキストエージェントと異なり、リアルタイムエージェントではガードレール発動時に 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 57e6a0c16..3397976b3 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,16 +4,16 @@ search: --- # クイックスタート -リアルタイム エージェントを使用すると、OpenAI の Realtime API を利用して AI エージェントとの音声会話が可能になります。このガイドでは、初めてのリアルタイム音声エージェントの作成方法を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を実現します。本ガイドでは、初めての Realtime 音声エージェントを作成する手順を説明します。 !!! warning "Beta feature" -リアルタイム エージェントはベータ版です。実装を改善する過程で破壊的変更が入る可能性があります。 +Realtime エージェントはベータ版です。今後の実装改善に伴い、破壊的変更が発生する可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK への基本的な習熟 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK に関する基本的な知識 ## インストール @@ -23,16 +23,16 @@ search: pip install openai-agents ``` -## 初めてのリアルタイム エージェントの作成 +## 初めての Realtime エージェントの作成 -### 1. 必要なコンポーネントのインポート +### 1. 必要なコンポーネントをインポートする ```python import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. リアルタイム エージェントを作成 +### 2. Realtime エージェントを作成する ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. ランナーを設定 +### 3. ランナーを設定する ```python runner = RealtimeRunner( @@ -56,7 +56,7 @@ runner = RealtimeRunner( ) ``` -### 4. セッションを開始 +### 4. セッションを開始する ```python async def main(): @@ -81,7 +81,7 @@ asyncio.run(main()) ## 完全なコード例 -以下は動作する完全なコード例です: +以下は、動作する完全なコード例です: ```python import asyncio @@ -139,30 +139,30 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択します (例: `gpt-4o-realtime-preview`) -- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストおよび/またはオーディオを有効にします (`["text", "audio"]`) +- `model_name`: 利用可能な Realtime モデルから選択します（例: `gpt-4o-realtime-preview`） +- `voice`: 音声を選択します（`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`） +- `modalities`: テキストおよび/またはオーディオを有効にします（`["text", "audio"]`） ### オーディオ設定 -- `input_audio_format`: 入力オーディオのフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力オーディオのフォーマット -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_format`: 入力オーディオのフォーマット（`pcm16`, `g711_ulaw`, `g711_alaw`） +- `output_audio_format`: 出力オーディオのフォーマット +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声アクティビティの閾値 (0.0–1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前のオーディオパディング +- `type`: 検出方法（`server_vad`, `semantic_vad`） +- `threshold`: 音声アクティビティのしきい値 (0.0 – 1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前のオーディオパディング ## 次のステップ -- [リアルタイム エージェントについてさらに学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作するコード例を参照してください -- エージェントに tools を追加する -- エージェント間のハンドオフを実装する -- 安全のためにガードレールを設定する +- [Realtime エージェントについてさらに学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作する code examples をご覧ください +- エージェントに tools を追加する +- エージェント間のハンドオフを実装する +- 安全性のためにガードレールを設定する ## 認証 @@ -172,7 +172,7 @@ OpenAI API キーが環境変数に設定されていることを確認してく 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 7a06e2505..aa903dbd5 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリースプロセス／変更履歴 +# リリースプロセス / 変更履歴 -本プロジェクトでは、`0.Y.Z` 形式のわずかに変更した semantic versioning を採用しています。先頭の `0` は SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します。 +本プロジェクトでは、`0.Y.Z` 形式を用いたセマンティックバージョニングをわずかに変更した方式に従っています。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントの増分ルールは以下のとおりです。 -## マイナー ( `Y` ) バージョン +## マイナー (`Y`) バージョン -beta でないパブリックインターフェースに対する breaking changes がある場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新では互換性のない変更が含まれる可能性があります。 +`beta` とマークされていない公開インターフェースに **破壊的変更** がある場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -breaking changes を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することを推奨します。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 -## パッチ ( `Z` ) バージョン +## パッチ (`Z`) バージョン -非互換性のない変更の場合に `Z` を増やします。 +互換性を壊さない変更では `Z` を増やします。 -- Bug fixes +- バグ修正 - 新機能 -- プライベートインターフェースへの変更 +- 非公開インターフェースの変更 - beta 機能の更新 -## 互換性のない変更履歴 +## 破壊的変更の変更履歴 ### 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 d6e383bb9..6145a4ef3 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 b44669bc8..824d797d3 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,52 +4,53 @@ search: --- # 結果 -` Runner.run ` メソッドを呼び出すと、戻り値は次のいずれかになります。 +`Runner.run` メソッドを呼び出すと、以下のいずれかが返されます。 -- [`RunResult`][agents.result.RunResult] （ `run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming] （ `run_streamed` を呼び出した場合） +- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] +- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。 ## 最終出力 -[`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] を使うと、元の入力にエージェント実行中に生成された項目を連結した入力リストへ変換できます。これにより、あるエージェント実行の出力を別の実行へ渡したり、ループ内で実行して毎回新しいユーザー入力を追加したりするのが簡単になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが入っています。アプリケーションによっては、ユーザーが次に入力する際にこれを再利用すると便利です。たとえば、最初にフロントラインのトリアージエージェントが言語別エージェントへハンドオフする場合、最後のエージェントを保存しておけば、ユーザーが次にメッセージを送ったときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが入ります。アプリケーションによっては、これはユーザーが次に入力する際に役立つことが多いです。たとえば、一次対応のトリアージ エージェントが言語特化型エージェントへハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にメッセージを送ったときに再利用できます。 -## 新規アイテム +## 新しい項目 -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが入っています。アイテムは [`RunItem`][agents.items.RunItem] でラップされており、LLM が生成した生のアイテムを保持します。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しい項目が含まれます。各項目は [`RunItem`][agents.items.RunItem] です。RunItem は LLM が生成した raw 項目をラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。生のアイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。生のアイテムはツールコールアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。生のアイテムはハンドオフツールコールへのツール応答です。アイテムからソース／ターゲットエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが実行されたことを示します。生のアイテムはツール応答です。ツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。生のアイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw 項目は生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM が handoff ツールを呼び出したことを示します。raw 項目は LLM からのツール呼び出し項目です。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は handoff が発生したことを示します。raw 項目は handoff ツール呼び出しに対するツールの応答です。この項目からソース／ターゲット エージェントにもアクセスできます。 +- [`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 a26be1478..560978fde 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,12 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスを介して実行できます。選択肢は 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。選択肢は 3 つあります: -1. 非同期で実行し、[`RunResult`][agents.result.RunResult] を返す [`Runner.run()`][agents.run.Runner.run] -2. 同期メソッドで、内部的に `.run()` を実行する [`Runner.run_sync()`][agents.run.Runner.run_sync] -3. 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返す [`Runner.run_streamed()`][agents.run.Runner.run_streamed] - LLM をストリーミング モードで呼び出し、受信したイベントを逐次配信します。 +1. [`Runner.run()`][agents.run.Runner.run] — 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync] — 同期メソッドで、内部的には `.run()` を呼び出します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] — 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリーミングします。 ```python from agents import Agent, Runner @@ -24,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) をご覧ください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -` Runner ` の run メソッドを使用する際は、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または OpenAI Responses API の項目リストのいずれかです。 +`Runner` の run メソッドを使用する際には、開始エージェントと入力を渡します。入力は文字列 (ユーザー メッセージと見なされます) か、OpenAI Responses API のアイテム リスト (input items) のいずれかです。 -Runner は次のループを実行します。 +ランナーは次のループを実行します: -1. 現在のエージェントに対して LLM を呼び出し、現在の入力を渡します。 +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 の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、かつツール呼び出しが存在しない場合です。 + LLM の出力が「最終出力」と見なされるルールは、望ましい型を持つテキスト出力を生成し、かつツール呼び出しが存在しない場合です。 ## ストリーミング -ストリーミングを利用すると、LLM 実行中のイベントを逐次受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には実行に関する完全な情報（生成されたすべての新規出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミング イベントを取得できます。詳細は [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングを使用すると、LLM の実行中にストリーミングイベントを追加で受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行に関する完全な情報 (生成されたすべての新しい出力を含む) が格納されます。ストリーミングイベントは `.stream_events()` で取得できます。詳しくは [ストリーミング ガイド](streaming.md) をご覧ください。 ## Run 設定 -` 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 にフィルターが指定されていない場合に適用されるグローバル入力フィルター。新しいエージェントへ送信する入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にします。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微情報をトレースに含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` の設定を推奨します。group ID は複数実行にまたがるトレースを関連付けるための任意フィールドです。 +- [`model`][agents.run.RunConfig.model]: 各エージェントの `model` 設定に関係なく、使用するグローバルな LLM モデルを設定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダー。デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力または出力ガードレールのリスト。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに入力フィルターが設定されていない場合に適用するグローバル入力フィルター。新しいエージェントへ送信する入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化します。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` を設定することを推奨します。グループ ID は複数の実行にまたがるトレースを関連付けるための任意項目です。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 -## 会話／チャットスレッド +## 会話 / チャットスレッド -いずれかの run メソッドを呼び出すと、1 回または複数回のエージェント実行（つまり複数回の LLM 呼び出し）が発生しますが、チャット会話における 1 つの論理ターンを表します。例: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェント (ひいては 1 つ以上の LLM 呼び出し) が実行されますが、チャット会話における 1 つの論理ターンを表します。例: -1. ユーザー ターン: ユーザーがテキストを入力 -2. Runner 実行: 第 1 エージェントが LLM を呼び出しツールを実行、次に第 2 エージェントへハンドオフし追加のツールを実行、最終出力を生成 +1. ユーザーターン: ユーザーがテキストを入力 +2. Runner 実行: 1 つ目のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフします。2 つ目のエージェントがさらにツールを実行し、その後出力を生成します。 -エージェント実行後、ユーザーにどの項目を表示するか選択できます。たとえば、エージェントが生成したすべての新規項目を表示することも、最終出力のみを表示することもできます。いずれの場合でも、ユーザーがフォローアップ質問をしたら再度 run メソッドを呼び出せます。 +エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。たとえば、エージェントが生成したすべての新しいアイテムを表示するか、最終出力のみを表示するかです。いずれの場合も、ユーザーが続けて質問したら、再度 run メソッドを呼び出せばよいです。 -### 手動の会話管理 +### 手動での会話管理 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して次のターンの入力を取得し、会話履歴を手動で管理できます。 +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って、次のターンの入力を取得し、会話履歴を手動で管理できます: ```python async def main(): @@ -92,9 +91,9 @@ async def main(): # California ``` -### Sessions による自動会話管理 +### Sessions を用いた自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使用すると `.to_input_list()` を手動で呼ばずに会話履歴を自動管理できます。 +より簡単な方法として、[Sessions](sessions.md) を利用して `.to_input_list()` を手動で呼び出さずに会話履歴を自動管理できます: ```python from agents import Agent, Runner, SQLiteSession @@ -117,20 +116,20 @@ async def main(): # California ``` -Sessions は次を自動で行います。 +Sessions は次の処理を自動で行います: - 各実行前に会話履歴を取得 -- 各実行後に新規メッセージを保存 +- 各実行後に新しいメッセージを保存 - 異なるセッション ID ごとに個別の会話を維持 -詳細は [Sessions のドキュメント](sessions.md) を参照してください。 +詳細は [Sessions ドキュメント](sessions.md) を参照してください。 ## 例外 -SDK は特定の場合に例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 +SDK は特定の状況で例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです: -- [`AgentsException`][agents.exceptions.AgentsException] : SDK で送出されるすべての例外の基底クラス -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] : 実行が run メソッドに渡した `max_turns` を超えた場合に送出 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError] : モデルが無効な出力（例: 不正な JSON や存在しないツールの使用）を生成した場合に送出 -- [`UserError`][agents.exceptions.UserError] : SDK を使用するコードの記述者が誤った使い方をした場合に送出 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] : [ガードレール](guardrails.md) がトリップした際に送出 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK で送出されるすべての例外の基底クラス。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 実行が run メソッドに渡した `max_turns` を超えた場合に送出されます。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: モデルが不正な出力 (例: 不正な 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 cb006fedc..ff030c192 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 は特定のセッションに対して会話履歴を保存し、エージェントが明示的なメモリー管理なしでコンテキストを維持できるようにします。チャットアプリケーションやマルチターンの会話で、エージェントに前回の対話内容を覚えさせたい場合に特に便利です。 +Sessions は特定のセッションの会話履歴を保存し、手動でメモリを管理しなくてもエージェントがコンテキストを維持できるようにします。チャットアプリケーションやマルチターンの会話を構築する際、エージェントに以前のやり取りを記憶させたい場合に特に便利です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリーが有効な場合: +セッションメモリが有効な場合: -1. **各実行前**: Runner はそのセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成された新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出しなど) がすべて自動的にセッションに保存されます。 -3. **コンテキスト維持**: 同じセッションでの後続の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを保持できます。 +1. **各実行前**: Runner はセッションの会話履歴を自動で取得し、それを入力項目の先頭に追加します。 +2. **各実行後**: 実行中に生成された新しい項目 (ユーザー入力、アシスタントの応答、ツール呼び出しなど) はすべて自動でセッションに保存されます。 +3. **コンテキスト保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 -## メモリー操作 +## メモリ操作 ### 基本操作 -Sessions では会話履歴を管理するためのさまざまな操作がサポートされています: +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 @@ -117,16 +117,16 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリーオプション +## メモリオプション -### メモリーなし（デフォルト） +### メモリなし (デフォルト) ```python # Default behavior - no session memory result = await Runner.run(agent, "Hello") ``` -### SQLite メモリー +### SQLite メモリ ```python from agents import SQLiteSession @@ -168,9 +168,9 @@ result2 = await Runner.run( ) ``` -## カスタムメモリー実装 +## カスタムメモリ実装 -独自のセッションメモリーを実装する場合は、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成してください: +独自のセッションメモリを実装するには、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します: ````python from agents.memory import Session @@ -230,15 +230,15 @@ Use meaningful session IDs that help you organize conversations: ### Session management ```python -# Clear a session when conversation should start fresh +# 会話をリセットしたい場合にセッションをクリア await session.clear_session() -# Different agents can share the same session +# 異なるエージェントが同じセッションを共有可能 support_agent = Agent(name="Support") billing_agent = Agent(name="Billing") session = SQLiteSession("user_123") -# Both agents will see the same conversation history +# どちらのエージェントも同じ会話履歴を参照 result1 = await Runner.run( support_agent, "Help me with my account", @@ -261,19 +261,19 @@ from agents import Agent, Runner, SQLiteSession async def main(): - # Create an agent + # エージェントを作成 agent = Agent( name="Assistant", instructions="Reply very concisely.", ) - # Create a session instance that will persist across runs + # 複数回の実行で永続化されるセッションインスタンスを作成 session = SQLiteSession("conversation_123", "conversation_history.db") print("=== Sessions Example ===") print("The agent will remember previous messages automatically.\n") - # First turn + # 1 ターン目 print("First turn:") print("User: What city is the Golden Gate Bridge in?") result = await Runner.run( @@ -284,7 +284,7 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # Second turn - the agent will remember the previous conversation + # 2 ターン目 - エージェントは前回の会話を記憶 print("Second turn:") print("User: What state is it in?") result = await Runner.run( @@ -295,7 +295,7 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # Third turn - continuing the conversation + # 3 ターン目 - 会話を継続 print("Third turn:") print("User: What's the population of that state?") result = await Runner.run( diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index f765a06ef..62c7236e8 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、エージェントの実行が進行するにつれて、その更新情報を購読できます。これは、エンドユーザーに進捗状況や途中経過のレスポンスを表示する際に役立ちます。 +ストリーミングを利用すると、エージェント実行の進行に合わせて更新を購読できます。これはエンドユーザーに進捗状況や途中結果を表示する際に役立ちます。 -ストリーミングを行うには、 `Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。続いて `result.stream_events()` を呼び出すと、 `StreamEvent` オブジェクトの async ストリームが取得できます。これらは後述します。 +ストリーミングを行うには、`Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。続いて `result.stream_events()` を呼ぶと、`StreamEvent` オブジェクトの非同期ストリームを取得できます。詳しくは後述します。 -## Raw response イベント +## raw レスポンスイベント -`RawResponsesStreamEvent` は、 LLM から直接渡される raw イベントです。これらは OpenAI Responses API フォーマットであり、各イベントにはタイプ（ `response.created` 、 `response.output_text.delta` など）とデータが含まれます。生成された直後にレスポンスメッセージをユーザーにストリーミングしたい場合に便利です。 +`RawResponsesStreamEvent` は LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式で、各イベントには `response.created`, `response.output_text.delta` などの type と data が含まれます。生成されたメッセージを即座にユーザーへストリーミングしたい場合に便利です。 -たとえば、以下のコードは LLM が生成したテキストをトークンごとに出力します。 +例えば、次のコードは LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## Run item イベントとエージェントイベント -`RunItemStreamEvent` は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、トークンごとの更新ではなく「メッセージが生成された」「ツールが実行された」などの粒度で進捗をユーザーに伝えられます。同様に、 `AgentUpdatedStreamEvent` は、ハンドオフの結果などで現在のエージェントが変化した際に更新を通知します。 +`RunItemStreamEvent` はより高レベルのイベントで、アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」といった粒度で進捗をプッシュできます。同様に、`AgentUpdatedStreamEvent` はハンドオフなどによって現在のエージェントが変わったときに更新を通知します。 -例として、以下のコードは raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 +例えば、次のコードは raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index b6b2b1de1..6a93b4c14 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 関数をツールとして使用できます。 -- エージェントをツールとして使用: ハンドオフを行わずに、エージェント同士が相互に呼び出せるようにします。 +- Hosted tools: これらは LLM サーバー上で AI モデルと並行して実行されます。OpenAI は retrieval、Web 検索、コンピュータ操作を hosted tools として提供しています。 +- Function calling: 任意の Python 関数をツールとして使用できます。 +- Agents as tools: エージェントをツールとして使用し、ハンドオフせずに他のエージェントを呼び出せます。 -## ホスト型ツール +## Hosted tools -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。 +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています: -- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。 -- [`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(): ## Function tools -任意の Python 関数をツールとして使用できます。Agents SDK が自動的に設定を行います。 +任意の Python 関数をツールとして利用できます。Agents SDK がツールを自動で設定します: -- ツール名は Python 関数名になります（または名前を指定可能）。 -- ツールの説明は関数の docstring から取得されます（または説明を指定可能）。 -- 関数の引数から入力スキーマが自動生成されます。 -- 各入力の説明は docstring から取得されます（無効化可）。 +- ツール名は Python 関数の名前になります (または任意の名前を指定可能) +- ツールの説明は関数の docstring から取得されます (または説明を指定可能) +- 関数入力のスキーマは関数の引数から自動生成されます +- 各入力の説明は、無効化しない限り関数の docstring から取得されます -関数シグネチャの抽出には Python の `inspect` モジュールを使用し、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ作成には `pydantic` を使用しています。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成しています。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 引数には任意の Python 型を使用でき、関数は sync / async いずれでも構いません。 -2. docstring があれば、説明や引数の説明を取得します。 -3. 関数の最初の引数として `context` を取ることができます。また、ツール名や説明、docstring スタイルなどのオーバーライドも設定可能です。 -4. デコレーターを付けた関数をツールのリストに渡せます。 +1. 関数の引数にはあらゆる Python 型を使用でき、同期関数でも非同期関数でも構いません。 +2. Docstring がある場合、ツールの説明および引数の説明を取得します。 +3. 関数の第一引数として `context` を取ることができます。また、ツール名・説明・docstring スタイルなどの上書き設定も可能です。 +4. デコレートした関数をツールのリストに渡すだけで使用できます。 -??? note "出力を表示" +??? note "展開して出力を確認" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### カスタム Function tool +### カスタム function 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 文字列の引数を受け取り、文字列としてツール出力を返す非同期関数 ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを解析してツールのスキーマを生成し、docstring を解析してツールおよび各引数の説明を取得します。ポイントは次のとおりです。 +前述のとおり、関数シグネチャを自動解析してツールのスキーマを抽出し、docstring を解析してツールおよび個々の引数の説明を取得します。主なポイントは以下のとおりです: -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションを利用して引数の型を理解し、Pydantic モデルを動的に構築してスキーマを表現します。Python プリミティブ、Pydantic モデル、TypedDict などほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。自動判定を試みますが、`function_tool` 呼び出し時に明示的に指定することもできます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 +1. シグネチャの解析は `inspect` モジュールで行います。型アノテーションを利用して引数の型を理解し、動的に Pydantic モデルを構築して全体のスキーマを表現します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 +2. Docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。Docstring 形式は自動検出を試みますがベストエフォートであり、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## エージェントをツールとして使用 +## Agents as tools -ワークフローによっては、ハンドオフせずに中央のエージェントが専門エージェント群をオーケストレーションしたい場合があります。その際、エージェントをツールとしてモデル化できます。 +一部のワークフローでは、ハンドオフせずに中央のエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。そのようなケースでは、エージェントをツールとしてモデル化できます。 ```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 @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 出力のカスタム抽出 +### カスタム出力抽出 -場合によっては、中央エージェントに返す前にツール化したエージェントの出力を加工したいことがあります。例えば次のようなケースです。 +状況によっては、中央エージェントへ返す前にツールエージェントの出力を加工したい場合があります。たとえば次のようなケースです: -- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出したい。 -- エージェントの最終回答を別形式に変換したい（例: Markdown → プレーンテキストや CSV）。 -- 出力を検証し、欠損・不正な場合にはフォールバック値を返したい。 +- サブエージェントのチャット履歴から特定の情報 (例: JSON ペイロード) を抽出したい +- エージェントの最終回答を変換または再フォーマットしたい (例: Markdown をプレーンテキストや CSV に変換) +- 出力を検証し、エージェントの応答が欠落または不正な場合にフォールバック値を提供したい -これを行うには、`as_tool` メソッドに `custom_output_extractor` 引数を渡します。 +`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -315,12 +315,12 @@ json_tool = data_agent.as_tool( ) ``` -## Function tool 内のエラー処理 +## Function tools におけるエラー処理 -`@function_tool` で Function tool を作成する際、`failure_error_function` を渡すことができます。これはツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。 +`@function_tool` で 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 b328f4899..8aef93fba 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,7 +4,7 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生する LLM 生成、関数ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまでを含む包括的なイベント履歴を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中および本番環境でワークフローをデバッグ・可視化・モニタリングできます。 +Agents SDK には組み込みのトレーシング機能があり、エージェント実行中のイベントを包括的に記録します： LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまで取得します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中や本番環境でワークフローをデバッグ・可視化・監視できます。 !!!note @@ -13,43 +13,43 @@ Agents SDK にはトレーシングが組み込まれており、エージェン 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化する 2. 単一の実行に対しては [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する -***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシーを採用している組織では、トレーシングは利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 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 回のエンドツーエンドの「ワークフロー」操作を表し、複数のスパンで構成されます。トレースには次のプロパティがあります： + - `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 は以下をトレースします。 +デフォルトで SDK は次をトレースします。 -- `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()` の下に配置される場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ +- エージェント実行ごとに `agent_span()` でラップ +- LLM 生成を `generation_span()` でラップ +- 関数ツール呼び出しを `function_span()` でラップ +- ガードレールを `guardrail_span()` でラップ +- ハンドオフを `handoff_span()` でラップ +- 音声入力（音声→テキスト）を `transcription_span()` でラップ +- 音声出力（テキスト→音声）を `speech_span()` でラップ +- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります -デフォルトでは、トレース名は「Agent workflow」です。`trace` を使用してこの名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを構成できます。 +デフォルトではトレース名は `"Agent workflow"` です。`trace` を使用して名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを設定できます。 -さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へ送ることもできます (置き換え、または追加送信)。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の送信先へ転送（置き換えまたは追加の送信先として）することもできます。 ## 上位レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `trace()` でラップしてください。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,62 +64,62 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個別トレースは作成されず、全体で 1 つのトレースになります。 +1. 2 回の `Runner.run` 呼び出しが `with trace()` でラップされているため、個別のトレースは作成されず、両方の実行が 1 つのトレースに含まれます。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数でトレースを作成できます。トレースには開始と終了が必要で、方法は 2 つあります。 +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要で、方法は 2 通りあります。 -1. **推奨**: `with trace(...) as my_trace` のように context manager として使用する。開始と終了が自動で行われます。 +1. **推奨**：コンテキストマネージャーとして使用する（例：`with trace(...) as my_trace`）。開始と終了が自動で行われます。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理でも自動的に機能します。トレースを手動で開始・終了する場合は、`start()`/`finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新する必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理でも自動で動作します。トレースを手動で開始／終了する場合は、`start()`／`finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新してください。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドでスパンを作成できますが、通常は手動で作成する必要はありません。カスタムスパン情報を追跡するには [`custom_span()`][agents.tracing.custom_span] を利用できます。 +各種 [`*_span()`][agents.tracing.create] メソッドでスパンを作成できますが、手動作成は通常不要です。カスタム情報を追跡したい場合は [`custom_span()`][agents.tracing.custom_span] を利用してください。 -スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。これも Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡しています。 +スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。この情報も Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 ## 機密データ -一部のスパンは機密データを含む可能性があります。 +一部のスパンは機密性の高いデータを記録する可能性があります。 -`generation_span()` は LLM の入力／出力を、`function_span()` は関数呼び出しの入力／出力を保存します。これらが機密情報を含む場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] で記録を無効化できます。 +`generation_span()` は LLM の入出力を、`function_span()` は関数呼び出しの入出力を保存します。機密データが含まれる場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] で記録を無効化できます。 -同様に、オーディオスパンはデフォルトで base64 エンコードされた PCM データ (入力・出力音声) を含みます。音声データの記録を無効化するには、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定してください。 +同様に、オーディオスパンはデフォルトで base64 エンコードされた PCM データ（入力および出力音声）を含みます。これを無効化するには、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定してください。 ## カスタムトレーシングプロセッサー トレーシングの高レベルアーキテクチャは次のとおりです。 -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースの生成を担当させます。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、バッチ単位でスパンとトレースを [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。このエクスポーターが OpenAI バックエンドへバッチ送信します。 +- 初期化時に、トレースを作成するグローバル [`TraceProvider`][agents.tracing.setup.TraceProvider] を生成します。 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、スパン／トレースをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] へ送信し、OpenAI バックエンドへエクスポートします。 -デフォルト設定をカスタマイズして、別のバックエンドへ送信したり、エクスポーターの動作を変更したりするには、次の 2 通りがあります。 +デフォルト設定をカスタマイズして別のバックエンドへ送信したり、エクスポーターの挙動を変更したりする場合は次の 2 つの方法があります。 1. [`add_trace_processor()`][agents.tracing.add_trace_processor] - 追加のトレースプロセッサーを登録し、トレース／スパンが準備完了した時点で受け取ります。OpenAI バックエンドへ送信しつつ独自処理を実行する場合に使用します。 + 追加のトレースプロセッサーを登録し、生成されたトレース／スパンを受け取って独自処理を行います。OpenAI バックエンドへの送信に加えて処理を追加できます。 2. [`set_trace_processors()`][agents.tracing.set_trace_processors] - デフォルトのプロセッサーを **置き換え** ます。OpenAI バックエンドへトレースが送信されなくなるので、必要に応じて送信用の `TracingProcessor` を含めてください。 + デフォルトのプロセッサーを置き換えます。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) \ No newline at end of file +- Weights & Biases +- Arize-Phoenix +- Future AGI +- MLflow (self-hosted/OSS +- MLflow (Databricks hosted +- Braintrust +- Pydantic Logfire +- AgentOps +- Scorecard +- Keywords AI +- LangSmith +- Maxim AI +- Comet Opik +- Langfuse +- Langtrace +- Okahu-Monocle +- Galileo +- Portkey AI \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 4b6311e9d..c2e9f001c 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,13 +2,13 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェント可視化を使用すると、 **Graphviz** を用いてエージェントとその関係を構造的なグラフィカル表現として生成できます。これにより、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解しやすくなります。 +エージェントの可視化を行うと、 **Graphviz** を使用してエージェントとその関係を構造化されたグラフで表現できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存グループをインストールします: +オプションの `viz` 依存関係グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -16,13 +16,13 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: + `draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- エージェントは黄色のボックスで表されます。 -- ツールは緑色の楕円で表されます。 -- ハンドオフはエージェント間の有向エッジとして表されます。 +- **エージェント** は黄色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジとして表されます。 -### 使用例 +### 使い方の例 ```python from agents import Agent, function_tool @@ -54,24 +54,24 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、 **triage agent** の構造とサブエージェントおよびツールへの接続を視覚的に示すグラフが生成されます。 +これにより、 **triage agent** の構造とサブエージェントおよびツールとの接続を視覚的に表したグラフが生成されます。 ## 可視化の理解 -生成されたグラフには次の要素が含まれます: +生成されたグラフには以下が含まれます: -- エントリーポイントを示す **start node** ( `__start__` )。 -- エージェントは黄色で塗りつぶされた長方形として表示されます。 -- ツールは緑色で塗りつぶされた楕円として表示されます。 -- 相互作用を示す有向エッジ: - - **Solid arrows** はエージェント間のハンドオフを示します。 - - **Dotted arrows** はツール呼び出しを示します。 -- 実行が終了する位置を示す **end node** ( `__end__` )。 +- エントリーポイントを示す **スタートノード** ( `__start__` ) +- 黄色で塗りつぶされた長方形として表される **エージェント** +- 緑色で塗りつぶされた楕円として表される **ツール** +- 相互作用を示す有向エッジ + - エージェント間のハンドオフには **実線の矢印** + - ツール呼び出しには **点線の矢印** +- 実行の終了地点を示す **エンドノード** ( `__end__` ) ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、 `draw_graph` はグラフをインラインで表示します。別ウィンドウで表示するには、次のようにします: +デフォルトでは、 `draw_graph` はグラフをインラインで表示します。別ウィンドウで表示する場合は、次のように記述します: ```python draw_graph(triage_agent).view() diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 99c7ce065..f6792f9fc 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント型ワークフローを音声アプリへ簡単に変換できるクラスです。実行したいワークフローを渡すだけで、入力音声の書き起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を再び音声へ変換する処理をパイプラインが自動で行います。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] クラスを使用すると、 エージェントのワークフローを簡単に音声アプリへ変換できます。 実行したいワークフローを渡すと、 パイプラインが入力音声の文字起こし、 音声終了の検出、 適切なタイミングでのワークフロー呼び出し、 そしてワークフローの出力を再び音声へ変換する処理を自動で行います。 ```mermaid graph LR @@ -34,34 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際に設定できる項目は次のとおりです。 +パイプラインを作成するときに、 次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] - 新しい音声が書き起こされるたびに実行されるコードです。 -2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] - 使用する STT／TTS モデルです。 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - 以下のような設定を行えます。 - - モデルプロバイダー : モデル名をモデルにマッピングします - - トレーシング : トレーシングの有効／無効、音声ファイルのアップロード可否、ワークフロー名、トレース ID など - - TTS と STT モデルの設定 : プロンプト、言語、使用するデータ型 など +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] — 新しい音声が文字起こしされるたびに実行されるコード +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] モデルと [`text-to-speech`][agents.voice.model.TTSModel] モデル +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] — 以下のような項目を設定できます + - モデル名をモデルにマッピングするモデルプロバイダー + - トレーシングの設定（トレーシングの無効化、 音声ファイルのアップロード有無、 ワークフロー名、 trace ID など） + - TTS および STT モデルのプロンプト、 使用言語、 データ型などの設定 ## パイプラインの実行 -[`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドでパイプラインを実行できます。音声入力は 2 つの形式で渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。 このとき、 2 つの形式で音声入力を渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声トランスクリプトがある場合に使用し、その内容に対する結果だけを生成します。発話終了検出が不要な、事前録音音声やプッシュトゥトーク アプリなどで便利です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] - 発話終了を検出する必要がある場合に使用します。検出された音声チャンクを順次プッシュでき、パイプラインが「アクティビティ検出」と呼ばれるプロセスを通じて適切なタイミングでエージェント ワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] — 完全な音声の文字起こしがあり、 その結果だけを取得したい場合に使用します。 たとえば、 あらかじめ録音された音声や、 プッシュトゥトーク方式で発話終了が明確なアプリなど、 話者の発話終了を検出する必要がないケースで便利です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] — 話者がいつ発話を終えたかを検出する必要がある場合に使用します。 検出された音声チャンクを逐次送信でき、 ボイスパイプラインが「アクティビティ検出」と呼ばれるプロセスを通じて、 適切なタイミングで自動的にエージェントワークフローを実行します。 -## 実行結果 +## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生するイベントをストリーミングできるオブジェクトで、いくつかの [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] を含みます。 +ボイスパイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。 このオブジェクトにより、 生成されるイベントをリアルタイムでストリーミングできます。 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] にはいくつか種類があり、 代表的なものは次のとおりです。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] : 音声チャンクを含みます。 -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] : ターンの開始／終了などライフサイクルイベントを通知します。 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] : エラーイベントです。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] — 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] — ターンの開始・終了などライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] — エラーイベントです。 ```python @@ -81,5 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK には [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 用のビルトイン割り込みサポートは現在ありません。そのため、検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] を監視してください。 -`turn_started` は新しいターンが書き起こされ処理が始まったことを示し、`turn_ended` は該当ターンの音声がすべて送信された後に発火します。これらのイベントを用いて、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連する音声をすべて送信し終えた後でアンミュートする、といった実装が可能です。 \ No newline at end of file +Agents SDK には現在、 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートはありません。 そのため、 検出された各ターンごとにワークフローが個別に実行されます。 アプリケーション内で割り込みを扱いたい場合は、 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。 `turn_started` は新しいターンが文字起こしされ、 処理が始まったことを示します。 `turn_ended` は該当ターンのすべての音声が配信された後にトリガーされます。 これらのイベントを利用して、 モデルがターンを開始したときに話者のマイクをミュートし、 関連する音声をすべて送信し終えたらアンミュートするといった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 50509896e..7283f73d4 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -4,21 +4,21 @@ search: --- # クイックスタート -## 必要条件 +## 前提条件 -まず、 base [クイックスタート手順](../quickstart.md) に従って Agents SDK をセットアップし、仮想環境を作成してください。次に、 SDK からオプションの音声依存関係をインストールします: +まず、 Agents SDK の基本 [クイックスタート手順](../quickstart.md) に従って仮想環境をセットアップしていることを確認してください。その後、SDK から音声オプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' ``` -## コンセプト +## 基本概念 -知っておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.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 つのハンドオフ、そして 1 つのツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。すでにこの SDK でエージェントを構築したことがある場合は、見覚えのあるパターンだと思います。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインを設定します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめ +## まとめて実行 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけてきます。自分でエージェントと会話できるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のコード例をご覧ください。 \ No newline at end of file +この例を実行すると、エージェントがあなたに話しかけてきます！自分でエージェントと会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) にある例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 19dcdc537..c6d31388e 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントがトレーシングされる方法](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 +[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントをご覧ください。また、パイプラインのトレーシングは [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じて追加設定できます。 +基本的なトレーシング情報については上記のドキュメントをご参照ください。さらに、 `VoicePipelineConfig` を通じてパイプラインのトレーシングを追加で設定できます。 -トレーシングに関連する主なフィールドは次のとおりです: +主なトレーシング関連フィールドは次のとおりです: - [`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_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 +- [`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