diff --git a/docs/ja/agents.md b/docs/ja/agents.md index b25527e90..e6d72075a 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,15 +4,15 @@ search: --- # エージェント -エージェントはアプリにおける中核的な構成要素です。エージェントは、 instructions と tools で構成された大規模言語モデル ( LLM ) です。 +エージェントは、アプリにおける中心的な構成要素です。エージェントは、instructions と tools で設定された大規模言語モデル ( LLM ) です。 -## 基本構成 +## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +一般的に設定するエージェントのプロパティは次のとおりです。 - `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージ、または system prompt とも呼ばれます。 -- `model`: 使用する LLM と、 temperature、 top_p などのモデル調整パラメーターを設定する任意の `model_settings`。 +- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 +- `model`: 使用する LLM と、`model_settings` による temperature、top_p などのチューニング パラメーターの任意設定。 - `tools`: エージェントがタスク達成のために使用できるツールです。 ```python @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態をまとめたものとして機能します。コンテキストには任意の Python オブジェクトを提供できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態をまとめて保持します。コンテキストには任意の Python オブジェクトを提供できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -既定では、エージェントはプレーンテキスト ( `str` ) を出力します。特定のタイプの出力を生成したい場合は、 `output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトの使用ですが、 Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型 ( dataclass、 list、 TypedDict など ) をサポートします。 +デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) の出力を生成します。特定のタイプの出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使うことですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型 ( dataclasses、lists、TypedDict など ) をサポートします。 ```python from pydantic import BaseModel @@ -73,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 + `output_type` を渡すと、通常のプレーンテキストの応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使うようにモデルへ指示します。 ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、関連がある場合にエージェントはそれらへ委譲できます。これは、単一のタスクに特化したモジュール式のエージェントをオーケストレーションする強力なパターンです。詳しくは [handoffs](handoffs.md) のドキュメントを参照してください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを提供すると、関連がある場合にエージェントはそれらへ委任できます。これは、単一のタスクに特化して優れた、モジュール式のエージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -96,9 +96,9 @@ triage_agent = Agent( ) ``` -## 動的 instructions +## 動的な指示 -多くの場合、エージェント作成時に instructions を指定しますが、関数を通じて動的な instructions を提供することもできます。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が利用可能です。 +多くの場合、エージェントの作成時に instructions を指定できます。しかし、関数を通じて動的な指示を提供することも可能です。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも使用できます。 ```python def dynamic_instructions( @@ -113,15 +113,15 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (フック) +## ライフサイクルイベント（フック） -エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログ記録したい、または特定のイベント発生時にデータを事前取得したい場合です。 `hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +ときには、エージェントのライフサイクルを観察したくなることがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりしたい場合があります。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェント実行と並行してユーザー入力に対するチェックや検証を行い、生成後のエージェント出力にも同様の処理を行えます。たとえば、ユーザー入力やエージェント出力の関連性をスクリーニングできます。詳しくは [guardrails](guardrails.md) のドキュメントを参照してください。 +ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック／検証を行い、エージェントの出力が生成された後にもそれを行えます。たとえば、ユーザーの入力やエージェントの出力を関連性でスクリーニングできます。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 -## エージェントのクローン/コピー +## エージェントのクローン／コピー エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを指定しても、 LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです。 +ツールのリストを指定しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定するとツール使用を強制できます。有効な値は次のとおりです。 1. `auto`: ツールを使用するかどうかを LLM に委ねます。 -2. `required`: LLM にツールの使用を要求します ( どのツールを使うかは賢く選択できます )。 -3. `none`: ツールを使用しないことを要求します。 -4. 特定の文字列 ( 例: `my_tool` ) を設定: LLM にその特定のツールの使用を要求します。 +2. `required`: LLM にツールの使用を必須にします ( どのツールを使うかは賢く判断できます )。 +3. `none`: LLM にツールを使用しないことを要求します。 +4. 文字列を指定 ( 例: `my_tool` ): その特定のツールを LLM に使用させます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -165,9 +165,9 @@ agent = Agent( ## ツール使用の挙動 -`Agent` の構成にある `tool_use_behavior` パラメーターは、ツール出力の処理方法を制御します。 -- `"run_llm_again"`: 既定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしに最終応答として使用します。 +`Agent` の設定にある `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 +- `"run_llm_again"`: デフォルト。ツールが実行され、LLM が結果を処理して最終応答を生成します。 +- `"stop_on_first_tool"`: 最初のツール呼び出しの出力をそのまま最終応答として使用し、以降の LLM 処理は行いません。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -185,7 +185,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定されたいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool from agents.agent import StopAtTools @@ -207,7 +207,7 @@ agent = Agent( tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 +- `ToolsToFinalOutputFunction`: ツールの結果を処理し、停止するか LLM を続行するかを判断するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -245,4 +245,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に自動的に `tool_choice` を "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが起きるのは、ツール結果が LLM に送られ、`tool_choice` のために LLM が再びツール呼び出しを生成し続けるためです。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、その後 `tool_choice` により LLM が再度ツール呼び出しを生成し続けるために発生します。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index d312b9eff..b1b81bfdf 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポートされた直後から LLM リクエストと トレーシング のために `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使ってキーを設定できます。 +デフォルトでは、SDK はインポートされた直後から LLM リクエストと トレーシング のために `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーから API キーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルト キーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使用するには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 +さらに、使用する OpenAI API をカスタマイズできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして Chat Completions API を使用するには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用します。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシング はデフォルトで有効です。デフォルトでは、上記の OpenAI API キー（つまり環境変数または設定したデフォルトキー）を使用します。トレーシング に使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 +トレーシング はデフォルトで有効です。デフォルトでは上記の OpenAI API キー（つまり、環境変数または設定したデフォルト キー）を使用します。トレーシング に使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -また、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシング を完全に無効化できます。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用して、トレーシング を完全に無効化することもできます。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグログ +## デバッグ ログ -SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。 +SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、警告とエラーは `stdout` に送られ、それ以外のログは抑制されます。 -詳細なログ出力を有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python logging ガイド](https://docs.python.org/3/howto/logging.html)をご覧ください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機微なデータ +### ログ内の機微データ -一部のログには機微なデータ（例: ユーザー データ）が含まれる場合があります。これらのデータの記録を無効化したい場合は、次の環境変数を設定してください。 +一部のログには機微なデータ（たとえば ユーザー データ）が含まれる場合があります。これらのデータがログに出力されないようにするには、以下の環境変数を設定してください。 -LLM の入力と出力のロギングを無効化するには: +LLM の入力と出力のログ記録を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のロギングを無効化するには: +ツールの入力と出力のログ記録を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index c74ab5322..3b514dd7a 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストは多義的な用語です。意識すべき主なコンテキストには次の 2 つのクラスがあります。 +コンテキストという用語は多義的です。ここでは主に次の 2 つのコンテキストがあります。 -1. コードからローカルに利用できるコンテキスト: これはツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になる可能性のあるデータや依存関係です。 -2. LLM に利用できるコンテキスト: これは LLM が応答を生成する際に目にするデータです。 +1. コードからローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に利用できるコンテキスト: 応答を生成する際に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスおよびその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作の概要は次のとおりです。 1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 2. そのオブジェクトを各種の実行メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 -3. すべてのツール呼び出しやライフサイクルフックなどにはラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` でアクセスできます。 +3. すべてのツール呼び出しやライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -最も重要な点: 特定のエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどは、同じ型のコンテキストを使わなければなりません。 + **最重要** なポイント: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じ型のコンテキストを使用しなければなりません。 コンテキストは次のような用途に使えます: -- 実行のための状況データ（例: ユーザー名 / uid や、ユーザーに関するその他の情報） -- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- 実行のための状況データ（例: ユーザー名 / uid やその他のユーザー情報） +- 依存関係（例: logger オブジェクト、データ取得コンポーネントなど） - ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは LLM に送信されません。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に **送信されません**。ローカル専用のオブジェクトであり、読み書きやメソッド呼び出しができます。 ```python import asyncio @@ -67,16 +67,16 @@ if __name__ == "__main__": ``` 1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、ツールの実装はコンテキストから読み取っています。 -3. 型チェッカーがエラーを検出できるように（たとえば異なるコンテキスト型を受け取るツールを渡そうとした場合など）、エージェントにジェネリックの `UserInfo` を付与しています。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、ツールの実装はコンテキストから読み取ります。 +3. エージェントにジェネリクス `UserInfo` を付けることで、型チェッカーがエラーを検出できます（たとえば、異なるコンテキスト型を取るツールを渡そうとした場合など）。 4. コンテキストは `run` 関数に渡されます。 -5. エージェントはツールを正しく呼び出して年齢を取得します。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM のコンテキスト +## エージェント / LLM コンテキスト -LLM が呼び出されると、LLM が参照できるデータは会話履歴からのものだけです。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴で利用可能になる方法で行う必要があります。方法はいくつかあります。 +LLM が呼び出されると、参照できるデータは会話履歴のみです。したがって、新しいデータを LLM に利用させたい場合は、その履歴で利用できる形で提供する必要があります。方法はいくつかあります: -1. エージェントの `instructions` に追加します。これは「system prompt」や「デベロッパーメッセージ」とも呼ばれます。system prompt は静的な文字列でも、コンテキストを受け取って文字列を出力する動的な関数でも構いません。これは常に有用な情報（例: ユーザー名や現在の日付）に一般的な戦略です。 -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 検索を使用します。これらは、ファイルやデータベース（retrieval）から、あるいは Web（Web 検索）から関連データを取得できる特別なツールです。これは、関連する状況データに応答を「グラウンディング」するのに役立ちます。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した方法です。 +2. `Runner.run` を呼び出す際の `input` に追加します。これは `instructions` に追加する方法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にあるメッセージを持たせられます。 +3. 関数ツールで公開します。これはオンデマンドのコンテキストに便利で、LLM が必要だと判断したときにツールを呼び出してデータを取得できます。 +4. リトリーバルや Web 検索を使用します。これらは、ファイルやデータベースから関連データを取得（リトリーバル）したり、Web から取得（Web 検索）したりできる特別なツールです。関連するコンテキストデータに基づいて応答を「グラウンディング」するのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 2ba3d495b..6bb457871 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,45 +4,45 @@ search: --- # コード例 -リポジトリの [code examples](https://github.com/openai/openai-agents-python/tree/main/examples) セクションで、 SDK のさまざまなサンプル実装をご覧ください。code examples は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 - +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでは、SDK のさまざまなサンプル実装をご覧いただけます。異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー -- **[エージェントパターン (agent_patterns)](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例では、次のような一般的な エージェント の設計パターンを示します。 +- **[エージェントパターン](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** + このカテゴリーの例は、一般的なエージェント設計パターンを示します。例: - 決定的なワークフロー - - ツールとしての エージェント - - エージェント の並列実行 + - ツールとしてのエージェント + - エージェントの並列実行 -- **[基本 (basic)](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらの例は、次のような SDK の基礎的な機能を紹介します。 +- **[基本](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + このコード例は、SDK の基礎的な機能を紹介します。例: - - 動的な システムプロンプト - - ストリーミング 出力 + - 動的なシステムプロンプト + - ストリーミング出力 - ライフサイクルイベント -- **[ツールのサンプルコード (tools)](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法と、それらを エージェント に統合する方法を学べます。 +- **[ツールのコード例](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + Web 検索やファイル検索などの OpenAI がホストするツールの実装方法と、 + それらをエージェントに統合する方法を学べます。 -- **[モデルプロバイダー (model_providers)](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - SDK で OpenAI 以外のモデルを使用する方法を探ります。 +- **[モデルプロバイダー](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + SDK で OpenAI 以外のモデルを使う方法を探索します。 -- **[ハンドオフ (handoffs)](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェント の ハンドオフ の実用例をご覧ください。 +- **[ハンドオフ](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + エージェントのハンドオフの実用的な例をご覧ください。 -- **[MCP (mcp)](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP で エージェント を構築する方法を学べます。 +- **[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 つあります。 +- **[カスタマーサービス](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[リサーチボット](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** + 実運用アプリケーションを示す、さらに作り込まれたコード例が 2 つあります - - **customer_service** : 航空会社向けのカスタマーサービス システムのサンプル。 - - **research_bot** : シンプルな ディープリサーチ のクローン。 + - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 + - **research_bot**: シンプルな ディープリサーチ クローン。 -- **[音声 (voice)](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを用いた音声 エージェント の例をご覧ください。 +- **[音声](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + 当社の TTS と STT モデルを用いた音声エージェントの例をご覧ください。 -- **[リアルタイム (realtime)](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイム体験を構築する方法を示す code examples。 \ No newline at end of file +- **[リアルタイム](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 5d4dc6ae1..e82b7910a 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは、エージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を行えます。たとえば、非常に賢い（そのぶん遅く/高価な）モデルでカスタマーリクエストを支援するエージェントがあるとします。悪意のあるユーザーに数学の宿題を手伝わせるような依頼をモデルにさせたくはありません。そのため、安価で高速なモデルでガードレールを実行できます。ガードレールが不正利用を検出した場合は、直ちにエラーを発生させて高価なモデルの実行を止め、時間とコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を可能にします。たとえば、非常に賢い（したがって遅く/高価な）モデルを使ってカスタマーリクエストを支援するエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせるようなことは避けたいはずです。そこで、迅速/低コストなモデルでガードレールを実行できます。ガードレールが悪意のある使用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を止め、時間と費用を節約できます。 -ガードレールには 2 つの種類があります: +ガードレールには 2 種類あります。 -1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェントの出力に対して実行されます +1. 入力ガードレールは初期のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 つの手順で実行されます: +入力ガードレールは 3 段階で実行されます。 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 入力ガードレールはユーザー入力での実行を想定しているため、エージェントのガードレールはそのエージェントが _最初の_ エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか不思議に思うかもしれません。これは、ガードレールは実際のエージェントに密接に関連する傾向があるからです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力で実行されることを意図しているため、あるエージェントのガードレールは、そのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか不思議に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するのが一般的であり、コードを同じ場所に置くことで読みやすさが向上します。 ## 出力ガードレール -出力ガードレールは 3 つの手順で実行されます: +出力ガードレールは 3 段階で実行されます。 1. まず、ガードレールはエージェントによって生成された出力を受け取ります。 2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 出力ガードレールは最終的なエージェント出力での実行を想定しているため、エージェントのガードレールはそのエージェントが _最後の_ エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的なエージェント出力で実行されることを意図しているため、あるエージェントのガードレールは、そのエージェントが「最後の」エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに関連する傾向があるため、エージェントごとに異なるガードレールを実行するのが一般的であり、コードを同じ場所に置くことで読みやすさが向上します。 ## トリップワイヤー -入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーが発動したガードレールを検出するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェントの実行を停止します。 +入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが作動したガードレールを検知するとすぐに、{Input,Output}GuardrailTripwireTriggered 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行して実現します。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。次の例では、内部でエージェントを実行してこれを行います。 ```python from pydantic import BaseModel diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index ce3ef2e8e..278405757 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,15 +4,15 @@ 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] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、任意の override や入力フィルターも指定できます。 ### 基本的な使い方 @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェントを直接使用する（`billing_agent` のように）ことも、`handoff()` 関数を使用することもできます。 +1. `billing_agent` のようにエージェントを直接使うことも、`handoff()` 関数を使うこともできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ [`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 - `agent`: ハンドオフ先のエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使われ、`transfer_to_` に解決されます。これを上書きできます。 - `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフの実行がわかった時点でデータ取得を開始するなどに便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御されます。 -- `input_type`: ハンドオフで想定される入力の型（任意）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうか。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが実行されると分かった時点でデータ取得を開始するなどに便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフが想定する入力の型（任意）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。 +- `is_enabled`: ハンドオフを有効にするかどうか。boolean または boolean を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## ハンドオフの入力 -状況によっては、ハンドオフを呼び出す際に LLM にいくつかのデータを提供させたい場合があります。たとえば、「 Escalation agent 」へのハンドオフを想定してください。ログ用に理由を提供してほしい、といったケースです。 +状況によっては、ハンドオフを呼び出す際に LLM にいくつかのデータを提供してほしい場合があります。たとえば、「エスカレーション エージェント」へのハンドオフを考えてみてください。ログのために理由を渡したいかもしれません。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、直前までの会話履歴全体を見ることができます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を見ることができます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 -一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. これは、`FAQ agent` が呼び出されたときに履歴から自動的にすべてのツールを削除します。 +1. これは、`FAQ agent` が呼び出されたときに履歴からツールを自動的にすべて削除します。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるよう、エージェント内にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] の推奨プレフィックスを使用するか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データを自動的にプロンプトへ追加できます。 +LLM にハンドオフを正しく理解させるため、エージェント内にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、プロンプトに推奨データを自動的に追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 1de117cb8..750b1fd2c 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化がごく少なく軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるツールです。以前のエージェント向け実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番運用レベルにアップグレードしたものです。Agents SDK はごく少数の基本コンポーネントを備えています。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント的な AI アプリを構築できるようにします。これは、当社のエージェントに関するこれまでの実験である [Swarm](https://github.com/openai/swarm/tree/main) のプロダクション対応版アップグレードです。Agents SDK にはごく少数の基本的なコンポーネントがあります。 - **エージェント**: instructions と tools を備えた LLM - **ハンドオフ**: 特定のタスクを他のエージェントに委譲する仕組み -- **ガードレール**: エージェントの入力・出力の検証を可能にする仕組み -- **セッション**: エージェントの実行をまたいで会話履歴を自動的に維持します +- **ガードレール**: エージェントの入力と出力を検証する機能 +- **セッション**: エージェントの実行間で会話履歴を自動的に保持 -Python と組み合わせることで、これらの基本コンポーネントだけでツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグできるほか、評価やアプリケーション向けのモデルのファインチューニングまで行えます。 +これらの基本的なコンポーネントは、Python と組み合わせることで、tools とエージェント間の複雑な関係を表現でき、急な学習曲線なしで実運用のアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグできるほか、評価を行い、アプリケーション向けにモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -SDK の設計原則は次の 2 点です。 +SDK には 2 つの設計原則があります。 -1. 使う価値があるだけの機能は備えるが、学習を素早くするため基本コンポーネントは少数に保つ。 -2. そのままでも優れた体験を提供しつつ、挙動を細部までカスタマイズできる。 +1. 使う価値のある十分な機能を備えつつ、学習が早いように基本要素は少なくすること。 +2. すぐに高い性能で使える一方で、挙動を細かくカスタマイズできること。 SDK の主な機能は次のとおりです。 -- エージェントループ: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを内蔵で処理します。 -- Python ファースト: 新しい抽象を学ぶ必要はなく、言語機能を用いてエージェントをオーケストレーションし連携させます。 -- ハンドオフ: 複数のエージェント間での調整と委譲を可能にする強力な機能です。 -- ガードレール: エージェントと並行して入力検証とチェックを実行し、失敗した場合は早期に打ち切ります。 -- セッション: エージェントの実行をまたいだ会話履歴の管理を自動化し、手動での状態管理を不要にします。 -- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と Pydantic による検証を提供します。 -- トレーシング: ワークフローの可視化・デバッグ・監視を可能にし、OpenAI の評価、ファインチューニング、蒸留ツールのスイートも活用できます。 +- エージェントループ: ツールの呼び出し、結果を LLM に渡す処理、LLM が完了するまでのループを担う組み込みのエージェントループ。 +- Python ファースト: 新しい抽象を覚えるのではなく、言語の組み込み機能でエージェントをオーケストレーションおよび連鎖。 +- ハンドオフ: 複数のエージェント間で調整・委譲できる強力な機能。 +- ガードレール: エージェントと並行して入力のバリデーションやチェックを実行し、失敗時は早期に中断。 +- セッション: エージェントの実行間で会話履歴を自動管理し、手動での状態管理を不要化。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースのバリデーションを提供。 +- トレーシング: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツール群を利用可能な組み込みトレーシング。 ## インストール @@ -36,7 +36,7 @@ SDK の主な機能は次のとおりです。 pip install openai-agents ``` -## Hello World のコード例 +## Hello world example ```python from agents import Agent, Runner diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index a5cfe0a72..bb03d30e9 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,23 +4,23 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP のドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、 LLM にツールとコンテキストを提供するための方法です。 MCP のドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションのための USB-C ポートのようなものです。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。 MCP を AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。 USB‑C がデバイスをさまざまな周辺機器やアクセサリーに接続する標準化された方法を提供するのと同様に、 MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -Agents SDK は MCP をサポートします。これにより、幅広い MCP サーバーを使用して、エージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用して、エージェントにツールやプロンプトを提供できます。 ## MCP servers -現在、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 server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) は次のように使います。 +たとえば、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を次のように使用します。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## Using MCP servers -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( ## Tool filtering -MCP サーバーでツールフィルターを設定することで、エージェントで利用可能なツールを絞り込めます。SDK は静的および動的なツールフィルタリングの両方をサポートします。 +MCP サーバー上でツールフィルターを構成することで、エージェントで使用可能なツールを絞り込めます。 SDK は静的および動的なツールフィルタリングの両方をサポートします。 ### Static tool filtering -単純な許可 / ブロックリストには、静的フィルタリングを使用できます: +単純な許可/ブロックリストには、静的フィルタリングを使用できます: ```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` のツールのみが利用可能になります。 ### Dynamic tool filtering -より複雑なフィルタリングロジックには、関数を使った動的フィルターを使用できます: +より複雑なフィルタリングロジックには、関数を用いた動的フィルターを使用できます: ```python from agents.mcp import ToolFilterContext @@ -134,7 +134,7 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次にアクセスできます: +`ToolFilterContext` では次の情報にアクセスできます: - `run_context`: 現在の実行コンテキスト - `agent`: ツールを要求しているエージェント - `server_name`: MCP サーバー名 @@ -145,10 +145,10 @@ MCP サーバーは、エージェントの instructions を動的に生成す ### Using prompts -プロンプトをサポートする 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( ## Caching -エージェントが実行されるたびに、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()` を呼び出せます。 ## End-to-end examples -完全な動作する code examples は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +完全に動作するサンプルは [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 ## Tracing -[トレーシング](./tracing.md) は MCP の操作を自動的に取得します。内容には次が含まれます: +[Tracing](./tracing.md) は、次を含む MCP の操作を自動的に取得します: -1. ツール一覧の取得のための MCP サーバー呼び出し +1. ツール一覧の取得のための MCP サーバーへの呼び出し 2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 187c40273..cfb5d19d0 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,43 +4,43 @@ search: --- # モデル -Agents SDK には、OpenAI モデル向けのサポートが 2 種類、すぐに使える形で用意されています。 +Agents SDK には、OpenAI モデルに対する標準サポートが 2 つの形で用意されています。 -- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 -## OpenAI 以外のモデル +## 非 OpenAI モデル -[LiteLLM 連携](./litellm.md) を通じて、ほとんどの OpenAI 以外のモデルを使用できます。まず、litellm の依存関係グループをインストールします。 +ほとんどの非 OpenAI モデルは [LiteLLM 連携](./litellm.md) を通じて使用できます。まず、 litellm の依存関係グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -その後、`litellm/` 接頭辞を付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 +次に、 `litellm/` プレフィックスを付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### OpenAI 以外のモデルを使う他の方法 +### 非 OpenAI モデルを使用するその他の方法 -他の LLM プロバイダーを連携する方法がさらに 3 つあります（code examples は[こちら](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/)）。 -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) 経由です。 +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 - これらの例では、Responses API をサポートしていない LLM プロバイダーがほとんどであるため、Chat Completions API/モデルを使用しています。お使いの LLM プロバイダーがサポートしている場合は、Responses の使用をおすすめします。 + これらのコード例では、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないため、 Chat Completions API / モデルを使用しています。お使いの LLM プロバイダーが対応している場合は、 Responses の使用をおすすめします。 ## モデルの組み合わせ -単一のワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使う、といった形です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選べます。 +単一のワークフロー内で、エージェント ごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小型で高速なモデルを使用し、複雑なタスクには大型で高機能なモデルを使用するなどです。[`Agent`][agents.Agent] を設定する際には、次のいずれかの方法で特定のモデルを選択できます。 1. モデル名を渡す。 2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 @@ -48,7 +48,7 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは 1 つのモデル形状に統一することをおすすめします。ワークフロー内でモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + この SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしていますが、各ワークフローでは 1 つのモデル形状に統一することをおすすめします。両者はサポートする機能やツールが異なるためです。もしワークフローでモデル形状の組み合わせが必要な場合は、使用する全機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -81,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接指定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +1. OpenAI のモデル名を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェント が使用するモデルをさらに詳細に設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。これは temperature などの任意のモデル設定 パラメーター を提供します。 +エージェント で使用するモデルをさらに細かく設定したい場合は、 `temperature` などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -97,7 +97,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、[いくつかのその他の任意 パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡せます。 +また、 OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、 `extra_args` を使って渡せます。 ```python from agents import Agent, ModelSettings @@ -113,26 +113,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー利用時の一般的な問題 +## 他社 LLM プロバイダー利用時のよくある問題 ### トレーシング クライアントのエラー 401 -トレーシング に関連するエラーが発生する場合、これはトレースが OpenAI の サーバー にアップロードされる一方で、OpenAI の API キーをお持ちでないことが原因です。解決するには次の 3 つの選択肢があります。 +トレーシング に関するエラーが発生するのは、トレースが OpenAI の サーバー にアップロードされる一方で、 OpenAI API キーをお持ちでないためです。解決策は次の 3 つです。 -1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング 用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. OpenAI 以外のトレース プロセッサーを使用する。[tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +2. トレーシング 用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだサポートしていません。その結果、404 エラーなどが発生する場合があります。解決策は 2 つあります。 +SDK は既定で Responses API を使用しますが、ほとんどの他社 LLM プロバイダーはまだサポートしていません。その結果、 404 などの問題が発生する場合があります。解決策は次の 2 つです。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 -### structured outputs のサポート +### Structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。 ``` @@ -140,12 +140,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダー側の制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないというものです。現在この問題の解決に取り組んでいますが、JSON schema 出力をサポートしているプロバイダーを利用することをおすすめします。そうでないと、不正な JSON によりアプリが頻繁に壊れてしまいます。 +これは一部のモデルプロバイダーの制約で、 JSON 出力には対応していても、出力に使用する `json_schema` を指定できないというものです。現在この点の改善に取り組んでいますが、 JSON schema 出力をサポートするプロバイダーに依存することをおすすめします。そうでないと、不正な形式の JSON によりアプリが頻繁に壊れてしまいます。 -## プロバイダーをまたいだモデルの混在 +## プロバイダーをまたぐモデルの組み合わせ -モデルプロバイダー間の機能差を理解していないと、エラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、OpenAI がホストするツール のファイル検索 と Web 検索 をサポートしていますが、多くの他プロバイダーはこれらをサポートしていません。次の制限に注意してください。 +モデルプロバイダー間の機能差に注意しないと、エラーに遭遇する可能性があります。たとえば、 OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 -- サポートしていない `tools` を理解しないプロバイダーには送らないでください -- テキスト専用モデルを呼び出す前に、マルチモーダル入力を除外してください -- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を返すことがある点に注意してください \ No newline at end of file +- 非対応の `tools` を理解しないプロバイダーに送らないでください +- テキスト専用モデルを呼び出す前に、マルチモーダル入力を除去してください +- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 945dc522c..67960da98 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM 経由で任意モデルの利用 +# LiteLLM 経由で任意のモデルの利用 !!! note - LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub の issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 + LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題があれば [GitHub Issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 連携を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM 連携を追加し、任意の AI モデルを利用できるようにしました。 ## セットアップ -`litellm` を利用可能にする必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 +`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで実現できます。 ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます。 +これは完全に動作するサンプルコードです。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます。 -- モデルに `openai/gpt-4.1`、API キーに OpenAI のもの -- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic のもの +- モデルに `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 プロバイダーのドキュメント](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 1d8c1912a..8244bfe5d 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 によるオーケストレーション -エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたとき、LLM が自律的にタスクへの取り組み方を計画し、ツールを使って行動やデータ取得を行い、ハンドオフを使ってサブエージェントにタスクを委任できることを意味します。例えば、あるリサーチエージェントには次のようなツールを装備できます。 +エージェントは、 instructions、tools、そして ハンドオフ を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM はタスクへの取り組み方を自律的に計画し、ツールを使ってアクションを実行・データを取得し、ハンドオフ を使ってサブエージェントにタスクを委譲できます。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 -- Web 検索でオンラインの情報を見つける -- ファイル検索と取得で社内データや接続を横断検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画立案、レポート作成などに優れた専門エージェントへのハンドオフ +- Web 検索 でオンラインの情報を見つける +- ファイル検索 と取得で独自データや接続を検索する +- コンピュータ操作 でコンピュータ上のアクションを実行する +- コード実行 でデータ分析を行う +- 計画策定、レポート作成などが得意な特化エージェントへの ハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に適しています。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、 LLM の知性に依存したい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、使い方、守るべきパラメーターを明確にします。 -2. アプリを監視し、反復改善する。問題が起きる箇所を把握し、プロンプトを改善します。 -3. エージェントに内省と改善を許す。例えばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもこなす汎用エージェントではなく、単一タスクに秀でた専門エージェントを用意します。 -5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク遂行能力を向上できます。 +1. 良いプロンプトに投資する。利用可能なツール、使い方、遵守すべき パラメーター を明確にする。 +2. アプリを監視して反復する。問題が起きる箇所を特定し、プロンプトを改善する。 +3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させる。 +4. 何でもできる汎用エージェントを期待するのではなく、1 つのタスクに特化して卓越したエージェントを用意する。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスク遂行能力を向上できます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の観点でより決定的かつ予測可能にできます。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成する。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次のエージェントを選びます。 -- 複数のエージェントを連結し、あるエージェントの出力を次のエージェントの入力に変換する。ブログ記事執筆のようなタスクを、調査→アウトライン作成→本文作成→批評→改善の一連のステップに分解できます。 -- タスクを実行するエージェントを `while` ループで動かしつつ、評価とフィードバックを与えるエージェントを併走させ、評価者が一定の基準を満たしたと判断するまで繰り返します。 -- 複数のエージェントを並列実行する（例: `asyncio.gather` のような Python の基本コンポーネントを使用）。相互に依存しない複数タスクがある場合、速度向上に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、タスクをいくつかの カテゴリー に分類するようエージェントに指示し、その カテゴリー に基づいて次に実行するエージェントを選ぶ。 +- あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事の執筆のようなタスクを、リサーチ→アウトライン作成→本文執筆→批評→改善という一連のステップに分解できる。 +- タスクを実行するエージェントと、それを評価してフィードバックするエージェントを `while` ループで回し、評価者が所定の基準を満たしたと判断するまで続ける。 +- 複数のエージェントを並列実行する（例: Python の基本コンポーネントである `asyncio.gather` を使用）。互いに依存しないタスクが複数ある場合、速度面で有用。 [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 43257d7e1..c9e39a8a8 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ行います。 +これは一度だけ実行すれば大丈夫です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行します。 +新しいターミナル セッションを開始するたびに実行してください。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -お持ちでない場合は、OpenAI API キーを作成するために [こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従ってください。 +まだお持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions（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( ) ``` -## handoffs の定義 +## ハンドオフの定義 -各エージェントで、タスクを前進させる方法を決めるために選択できる、送信先 handoff オプションの在庫（一覧）を定義できます。 +各エージェントで、タスクを進める方法を決めるために選択可能な、発信側のハンドオフ オプションの在庫を定義できます。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## エージェントのオーケストレーションの実行 -ワークフローが実行され、トリアージ エージェントが 2 つの専門エージェント間で正しくルーティングすることを確認しましょう。 +ワークフローが動作し、トリアージ エージェントが 2 つの専門エージェント間を正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## まとめて実行 +## すべてを組み合わせる -すべてを組み合わせて、handoffs と入力ガードレールを使い、ワークフロー全体を実行しましょう。 +すべてを組み合わせて、ハンドオフと入力ガードレールを使い、ワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して、エージェント実行のトレースを表示します。 +エージェントの実行中に何が起きたかを確認するには、OpenAI ダッシュボードの Trace viewer に移動し、エージェント実行のトレースを表示してください。(https://platform.openai.com/traces) ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう。 +より複雑なエージェント フローの構築方法を学びましょう: -- [エージェント](agents.md)の設定方法について学ぶ。 -- [エージェントの実行](running_agents.md)について学ぶ。 -- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md)について学ぶ。 \ No newline at end of file +- [エージェント](agents.md)の設定方法を学ぶ +- [エージェントの実行](running_agents.md)について学ぶ +- [ツール](tools.md)、[ガードレール](guardrails.md)、および[モデル](models/index.md)について学ぶ \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index c743bd717..ff8782393 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、 OpenAI Agents SDK の realtime 機能を使って音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、互換性のない変更が発生する可能性があります。 +realtime エージェントはベータ版です。実装の改善に伴い、互換性が壊れる変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、会話フローを可能にし、音声とテキスト入力をリアルタイムに処理して realtime 音声で応答します。 OpenAI の Realtime API と永続的に接続を維持し、低レイテンシで自然な音声会話と、割り込みに対する優雅なハンドリングを実現します。 +realtime エージェントは、会話フローに対応し、音声とテキスト入力をリアルタイムに処理し、リアルタイム音声で応答します。OpenAI の Realtime API との永続接続を維持し、低レイテンシで自然な音声対話と中断の優雅な処理を可能にします。 ## アーキテクチャ ### コアコンポーネント -realtime システムはいくつかの主要コンポーネントで構成されます: +realtime システムは以下の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェントです。 +- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェント。 - **RealtimeRunner**: 構成を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッションです。通常、 ユーザー が会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデルのインターフェース（一般的には OpenAI の WebSocket 実装）です。 +- **RealtimeSession**: 単一の対話セッション。通常は ユーザー が会話を開始するたびに作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤のモデルインターフェース（通常は OpenAI の WebSocket 実装） ### セッションフロー -一般的な realtime セッションは次のフローに従います: +典型的な realtime セッションの流れは次のとおりです。 -1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 +1. **RealtimeAgent を作成** し、instructions、tools、handoffs を設定します。 2. **RealtimeRunner をセットアップ** し、エージェントと構成オプションを指定します。 -3. **セッションを開始** `await runner.run()` を使用して開始し、RealtimeSession が返されます。 -4. **音声またはテキスト メッセージを送信** `send_audio()` または `send_message()` でセッションへ送信します。 -5. **イベントをリッスン** セッションをイテレートしてイベントを受け取ります。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. **割り込みを処理** ユーザー がエージェントの発話に被せたとき、進行中の音声生成は自動的に停止します。 +3. **セッションを開始** し、`await runner.run()` を使用して RealtimeSession を取得します。 +4. **音声またはテキストメッセージを送信** し、`send_audio()` または `send_message()` を利用します。 +5. **イベントをリッスン** し、セッションを反復処理します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーなどが含まれます。 +6. **割り込みを処理** します。ユーザー がエージェントの発話に被せた場合、現在の音声生成は自動的に停止します。 セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 -## エージェント設定 +## エージェント構成 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。完全な API 詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスと同様に機能しますが、いくつか重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 -通常のエージェントとの差分: +通常のエージェントとの主な違い: -- モデルの選択はエージェント レベルではなく、セッション レベルで構成します。 -- structured output のサポートはありません（`outputType` はサポートされません）。 -- 音声はエージェントごとに設定できますが、最初のエージェントが発話した後に変更することはできません。 -- それ以外の機能（tools、ハンドオフ、instructions）は同様に動作します。 +- モデルの選択はエージェント単位ではなくセッション単位で構成します。 +- structured outputs のサポートはありません（`outputType` はサポートされません）。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- ツール、ハンドオフ、instructions など他の機能は同様に動作します。 -## セッション設定 +## セッション構成 ### モデル設定 -セッション構成では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-4o-realtime-preview` など）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の両方に設定でき、既定は PCM16 です。 +セッション構成では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、サポートするモダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の両方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定は、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、ドメイン固有用語の精度向上のための文字起こしプロンプトを設定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出音声の前後パディングなどにより、エージェントが応答を開始・停止すべきタイミングを制御します。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使用して入力音声の文字起こしを構成し、言語設定や、ドメイン特有の用語に対する精度を高めるための書き起こしプロンプトを指定できます。ターン検出設定では、エージェントが応答を開始・終了すべきタイミングを制御し、音声活動検出のしきい値、無音の継続時間、検出された発話の前後に追加するパディングなどのオプションがあります。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします: +通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、専門特化したエージェント間で会話を移譲できます。 +ハンドオフにより、専門化されたエージェント間で会話を転送できます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションは、セッション オブジェクトをイテレートすることでリッスンできるイベントを ストリーミング します。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特にハンドリングすべき主なイベントは次のとおりです: +セッションはイベントをストリーミングし、セッションオブジェクトを反復処理することでリッスンできます。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。主に処理すべきイベントは次のとおりです。 -- **audio**: エージェントの応答からの raw オーディオ データ -- **audio_end**: エージェントの発話が終了 -- **audio_interrupted**: ユーザー による割り込みを検知 +- **audio**: エージェントの応答からの生の音声データ +- **audio_end**: エージェントの発話が完了 +- **audio_interrupted**: ユーザー がエージェントを中断 - **tool_start/tool_end**: ツール実行のライフサイクル -- **handoff**: エージェント間のハンドオフが発生 +- **handoff**: エージェントのハンドオフが発生 - **error**: 処理中にエラーが発生 -イベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +イベントの完全な詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -realtime エージェントでサポートされるのは出力ガードレールのみです。パフォーマンス問題を避けるため、これらのガードレールはデバウンスされ、リアルタイム生成中に（毎語ではなく）定期的に実行されます。既定のデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでサポートされるのは出力 ガードレール のみです。これらの ガードレール はデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために定期的（毎語ではない）に実行されます。デフォルトのデバウンス長は 100 文字ですが、構成可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` から提供できます。両方のソースからのガードレールは併用されます。 +ガードレール は `RealtimeAgent` に直接アタッチするか、セッションの `run_config` 経由で指定できます。両方のソースからの ガードレール は一緒に実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を割り込むことがあります。デバウンスの動作により、安全性とリアルタイム性能要件のバランスをとります。テキスト エージェントと異なり、realtime エージェントはガードレールにかかった場合でも Exception を送出しません。 +ガードレール がトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を中断できます。デバウンス動作は、安全性とリアルタイムのパフォーマンス要件とのバランスを取るのに役立ちます。テキストエージェントと異なり、realtime エージェントは ガードレール が作動しても Exception をスローしません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用してセッションに音声を送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使って音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使ってテキストを送信します。 -音声出力については、`audio` イベントをリッスンし、任意のオーディオ ライブラリで音声データを再生します。ユーザー がエージェントを割り込んだ際に即時再生停止とキュー済み音声のクリアを行うため、`audio_interrupted` イベントを必ずリッスンしてください。 +音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで音声データを再生してください。ユーザー がエージェントを中断した際に即座に再生を停止し、キューにある音声をクリアするために、`audio_interrupted` イベントも必ずリッスンしてください。 -## モデルへの直接アクセス +## モデル直接アクセス -基盤となるモデルにアクセスし、カスタム リスナーの追加や高度な操作を実行できます: +基盤のモデルにアクセスして、カスタムリスナーを追加したり高度な操作を実行できます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、接続をより低レベルに制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 ## コード例 -完全に動作するサンプルは、UI コンポーネントの有無それぞれのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 \ No newline at end of file +完全な動作コードは、UI コンポーネントの有無それぞれのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 52b2b92b0..d9ed88bcd 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -7,17 +7,17 @@ search: Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を可能にします。このガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、後方互換性のない変更が行われる可能性があります。 +Realtime エージェントはベータ版です。実装を改善する過程で非互換の変更が入る可能性があります。 ## 前提条件 - Python 3.9 以上 - OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- OpenAI Agents SDK の基本的な理解 ## インストール -まだの場合は、OpenAI Agents SDK をインストールしてください: +まだの場合は、OpenAI Agents SDK をインストールします: ```bash pip install openai-agents @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. Runner の設定 +### 3. Runner のセットアップ ```python runner = RealtimeRunner( @@ -81,7 +81,7 @@ asyncio.run(main()) ## 完全なコード例 -以下は動作する完全な例です: +以下は完全に動作するコード例です: ```python import asyncio @@ -139,34 +139,34 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能な realtime モデルから選択（例: `gpt-4o-realtime-preview`） +- `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) +- `threshold`: 音声活動のしきい値（0.0-1.0） - `silence_duration_ms`: ターン終了を検出する無音時間 - `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [Realtime エージェントの詳細](guide.md) -- 動作するサンプルは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダを参照してください +- [Realtime エージェントについてさらに学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作するコード例を確認 - エージェントにツールを追加 - エージェント間のハンドオフを実装 - 安全性のためのガードレールを設定 ## 認証 -OpenAI API キーが環境に設定されていることを確認してください: +環境に OpenAI API キーが設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/ja/release.md b/docs/ja/release.md index 9bff0992f..f42149de0 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリースプロセス/変更履歴 +# リリース プロセス/変更履歴 -このプロジェクトは、`0.Y.Z` という形式のセマンティック バージョニングを一部変更して採用しています。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増分します。 +本プロジェクトは、`0.Y.Z` という形式のセマンティック バージョニングをやや変更したものに従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントは次のように増分します: -## マイナー（`Y`）バージョン +## マイナー ( `Y` ) バージョン -ベータではない公開インターフェースに対する、互換性のない変更（破壊的変更）がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には破壊的変更が含まれる可能性があります。 +ベータとしてマークされていない公開インターフェースに対する **破壊的変更** の場合、マイナー バージョン `Y` を増やします。例えば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンにピン留めすることをおすすめします。 +破壊的変更を望まない場合は、プロジェクトで `0.0.x` バージョンに固定することを推奨します。 -## パッチ（`Z`）バージョン +## パッチ ( `Z` ) バージョン -互換性を壊さない変更では `Z` を増分します。 +破壊的でない変更については `Z` を増分します: -- バグ修正 -- 新機能 -- 非公開インターフェースの変更 -- ベータ機能の更新 +- バグ修正 +- 新機能 +- プライベートなインターフェースの変更 +- ベータ機能の更新 ## 破壊的変更の変更履歴 ### 0.2.0 -このバージョンでは、これまで `Agent` を引数に取っていた箇所の一部が、代わりに `AgentBase` を引数に取るようになりました。たとえば、MCP サーバーでの `list_tools()` 呼び出しです。これは純粋に型付け上の変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 +このバージョンでは、以前は引数として `Agent` を受け取っていた一部の箇所が、代わりに引数として `AgentBase` を受け取るようになりました。例えば、MCP サーバーにおける `list_tools()` 呼び出しです。これは純粋に型に関する変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正してください。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承する任意のクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 2 つの新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` をサブクラス化するすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 3e106bb3d..02174422a 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,8 @@ search: --- # REPL ユーティリティ -この SDK は、ターミナル上でエージェントの動作を手早く対話的にテストできる `run_demo_loop` を提供します。 +この SDK は、ターミナルでエージェントの動作を素早く対話的にテストできる `run_demo_loop` を提供します。 + ```python import asyncio @@ -18,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` は、ループでユーザー入力を求め、ターン間の会話履歴を保持します。既定では、生成と同時にモデル出力をストリーミングします。上の例を実行すると、 run_demo_loop が対話的なチャットセッションを開始します。継続的に入力を求め、ターン間の会話全体の履歴を記憶します（エージェントが何が議論されたかを把握できるように）。また、生成され次第、エージェントの応答をリアルタイムで自動ストリーミングします。 +`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成と同時にモデル出力をストリーミングします。上記の例を実行すると、run_demo_loop は対話型のチャット セッションを開始します。あなたの入力を継続的に求め、ターン間の会話全体を記憶し（エージェントが何について話したかを把握できるように）、生成と同時にエージェントの応答をリアルタイムで自動ストリーミングします。 -このチャットセッションを終了するには、`quit` または `exit` と入力し（そして Enter を押す）、または `Ctrl-D` キーボードショートカットを使用してください。 \ No newline at end of file +チャット セッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボード ショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index d7b217f66..6cdd23b76 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 実行結果 -`Runner.run` メソッドを呼び出すと、次のいずれかを受け取ります。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼んだ場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼んだ場合） -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれます。 +いずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はそこに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: - 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は、`last_agent.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] です。Run item は、LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。RunItem は、LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しに対するツールのレスポンスです。アイテムからソース/ターゲットの エージェント にもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツールのレスポンスです。アイテムからツールの出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は、LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem]: LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem]: LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem]: LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]: ツールが呼び出されたことを示します。raw アイテムはツールの応答です。アイテムからツールの出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem]: LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 ### ガードレールの実行結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの実行結果（ある場合）が含まれます。ガードレールの実行結果には、ログや保存に有用な情報が含まれる場合があるため、利用できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、存在する場合にガードレールの実行結果が含まれます。ガードレールの実行結果には、ログや保存に役立つ情報が含まれることがあるため、参照できるようにしています。 -### Raw 応答 +### Raw レスポンス [`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。多くの場合これは不要ですが、必要な場合に備えて利用可能です。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が含まれます。多くの場合、これは不要ですが、必要に応じて参照できるように提供しています。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index eef5f83c2..2765e6a87 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。オプションは 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。方法は 3 つあります。 1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的に `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM を ストリーミング モードで呼び出し、受信したイベントを逐次 ストリーミング します。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリーミングします。 ```python from agents import Agent, Runner @@ -23,53 +23,53 @@ async def main(): # Infinite loop's dance ``` -詳しくは [結果ガイド](results.md) をご覧ください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API のアイテムのリスト（入力アイテム）を指定できます。 +`Runner` の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ユーザーのメッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）です。 Runner は次のループを実行します。 1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 - 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM が ツール呼び出し を生成した場合、それらを実行して結果を追加し、ループを再実行します。 -3. 渡した `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 + 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新して、ループを再実行します。 + 3. LLM が ツール呼び出し を生成した場合、それらを実行し、結果を追加して、ループを再実行します。 +3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM の出力が「final output」と見なされるルールは、目的の型のテキスト出力を生成し、ツール呼び出しがないことです。 ## ストリーミング -ストリーミング により、LLM の実行中に ストリーミング イベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成された新しい出力を含む実行に関する完全な情報が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して受け取れます。詳しくは [ストリーミング ガイド](streaming.md) をご覧ください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了時、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成された新しい出力を含む実行の完全な情報が入ります。ストリーミングイベントは `.stream_events()` を呼び出してください。詳細は [ストリーミングガイド](streaming.md) を参照してください。 -## 実行設定 +## 実行設定 (Run config) -`run_config` パラメーターでは、エージェント実行のグローバル設定を構成できます。 +`run_config` パラメーターでは、エージェント実行のグローバル設定を行えます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、使用するグローバルな LLM モデルを設定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関わらず、使用するグローバルな LLM モデルを設定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名の解決に使うモデルプロバイダーで、デフォルトは OpenAI です。 - [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力の ガードレール のリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: すべての ハンドオフ に適用するグローバルな入力フィルター（すでにフィルターが設定されていない場合）。入力フィルターにより、新しいエージェントに送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントをご覧ください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体に対して [トレーシング](tracing.md) を無効化します。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、LLM やツール呼び出しの入出力など、機微なデータを含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。最低でも `workflow_name` の設定を推奨します。グループ ID は、複数の実行にまたがるトレースを関連付けるための任意のフィールドです。 +- [`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]: すべてのトレースに含めるメタデータです。 -## 会話/チャットスレッド +## 会話／チャットスレッド -任意の実行メソッドを呼び出すと、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される可能性がありますが、チャット会話における 1 回の論理的なターンを表します。例: +任意の run メソッドの呼び出しは、1 つ以上のエージェント（つまり 1 回以上の LLM 呼び出し）の実行につながる可能性がありますが、チャット会話の 1 つの論理的なターンを表します。例: 1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへ ハンドオフ、2 番目のエージェントがさらにツールを実行し、出力を生成 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへ ハンドオフ、2 つ目のエージェントがさらにツールを実行し、その後に出力を生成。 -エージェント実行の終了時に、ユーザーへ何を表示するかを選べます。たとえば、エージェントが生成した新しいすべてのアイテムを見せるか、最終出力のみを見せるかです。いずれにしても、その後にユーザーがフォローアップの質問をするかもしれず、その場合は再度 run メソッドを呼び出せます。 +エージェントの実行が終わったら、ユーザーに何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを表示するか、最終出力のみを表示します。いずれにしても、ユーザーが追質問をするかもしれないため、その場合は再度 run メソッドを呼び出せます。 -### 手動での会話管理 +### 手動の会話管理 次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出さずに会話履歴を自動的に処理できます。 +より簡単な方法として、[Sessions](sessions.md) を使えば、`.to_input_list()` を手動で呼び出さずに会話履歴を自動で扱えます。 ```python from agents import Agent, Runner, SQLiteSession @@ -118,24 +118,24 @@ async def main(): Sessions は自動で次を行います。 -- 各実行の前に会話履歴を取得 -- 各実行の後に新しいメッセージを保存 -- 異なるセッション ID ごとに個別の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- セッション ID ごとに別々の会話を維持 -詳細は [Sessions のドキュメント](sessions.md) をご覧ください。 +詳細は [Sessions のドキュメント](sessions.md) を参照してください。 -## 長時間実行エージェントと human-in-the-loop +## 長時間実行エージェントとヒューマン・イン・ザ・ループ -Agents SDK の [Temporal](https://temporal.io/) 連携により、human-in-the-loop のタスクを含む、永続的で長時間実行のワークフローを動かせます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で、ドキュメントは[こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)をご覧ください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使用して、ヒューマン・イン・ザ・ループを含む、永続的で長時間実行のワークフローを実行できます。Temporal と Agents SDK が連携して長時間実行タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を参照し、[こちらのドキュメント](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) もご覧ください。 ## 例外 -SDK は特定のケースで例外を送出します。全リストは [`agents.exceptions`][] にあります。概要は以下のとおりです。 +SDK は特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかの特定の例外はすべてこの型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` に渡された `max_turns` 制限を超えたときに送出されます。指定したやり取り回数内にエージェントがタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤のモデル（LLM）が予期しない、または不正な出力を生成したときに発生します。たとえば次を含みます。 - - 不正な JSON: 特定の `output_type` が定義されている場合などに、ツール呼び出しや直接の出力で不正な JSON 構造を返したとき。 - - 予期しないツール関連の失敗: モデルが期待どおりにツールを使用できなかったとき -- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（SDK を使ってコードを書く人）が誤りを犯した場合に送出されます。これは通常、不正なコード実装、無効な構成、SDK の API の誤用が原因です。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 入力 ガードレール または出力 ガードレール の条件が満たされたときに、それぞれ送出されます。入力 ガードレール は処理前に受信メッセージを検査し、出力 ガードレール は配信前にエージェントの最終応答を検査します。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外はここから派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` に渡された `max_turns` の上限を超えたときに送出されます。指定された対話ターン数の範囲でタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。以下を含むことがあります。 + - 不正な JSON: 特定の `output_type` が定義されている場合に特に、ツール呼び出しや直接の出力に不正な JSON 構造を返した場合。 + - 予期しないツール関連の失敗: モデルが期待どおりの方法でツールを使用できなかった場合 +- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（SDK を用いてコードを書く人）が誤りを犯した場合に送出されます。これは通常、不正なコード実装、無効な設定、または SDK の API の誤用に起因します。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ、入力 ガードレール または出力 ガードレール の条件が満たされたときに送出されます。入力 ガードレール は処理前に受信メッセージをチェックし、出力 ガードレール は配信前にエージェントの最終応答をチェックします。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index a3cdeb0dd..cd775c9a3 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に保持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 +Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に保持するための組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 -セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッションに対する会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -51,11 +51,11 @@ print(result.final_output) # "Approximately 39 million" セッションメモリが有効な場合: -1. ** 各実行前 **: ランナーはセッションの会話履歴を自動的に取得し、入力項目の先頭に追加します。 -2. ** 各実行後 **: 実行中に生成されたすべての新しい項目 (ユーザー入力、アシスタントの応答、ツール呼び出しなど) が自動的にセッションに保存されます。 -3. ** コンテキストの保持 **: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）はすべて自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 -これにより、実行間で手動で `.to_input_list()` を呼び出して会話状態を管理する必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出して実行間の会話状態を管理する必要がなくなります。 ## メモリ操作 @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 訂正のための pop_item の使用 +### 修正のための pop_item の使用 -`pop_item` メソッドは、会話内の最後の項目を取り消したり修正したりしたい場合に特に有用です: +`pop_item` メソッドは、会話内の最後のアイテムを取り消したり修正したりしたい場合に特に有用です: ```python from agents import Agent, Runner, SQLiteSession @@ -119,7 +119,7 @@ print(f"Agent: {result.final_output}") ## メモリオプション -### メモリなし (デフォルト) +### メモリなし（デフォルト） ```python # Default behavior - no session memory @@ -216,7 +216,7 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすい意味のあるセッション ID を使用します: +会話を整理するのに役立つ意味のあるセッション ID を使用してください: - ユーザー単位: `"user_12345"` - スレッド単位: `"thread_abc123"` @@ -224,9 +224,9 @@ result = await Runner.run( ### メモリの永続化 -- 一時的な会話にはインメモリ SQLite (`SQLiteSession("session_id")`) を使用します -- 永続的な会話にはファイルベースの SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用します -- 本番システムではカスタムのセッションバックエンド (Redis、PostgreSQL など) の実装を検討します +- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します +- 本番システム向けにカスタムセッションバックエンド（Redis、PostgreSQL など）の実装を検討してください ### セッション管理 @@ -252,9 +252,9 @@ result2 = await Runner.run( ) ``` -## 完全な例 +## 完全なコード例 -セッションメモリがどのように機能するかを示す完全な例です: +以下は、セッションメモリの動作を示す完全なコード例です: ```python import asyncio @@ -318,7 +318,7 @@ if __name__ == "__main__": ## API リファレンス -詳しい API ドキュメントは以下を参照してください: +詳細な API ドキュメントは次を参照してください: - [`Session`][agents.memory.Session] - プロトコルインターフェース - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 0b5d12d95..6a8c32eb1 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、エージェントの実行が進むにつれて更新を受け取れます。エンドユーザーに進行状況の更新や部分的な応答を表示するのに役立ちます。 +ストリーミングを使うと、進行中のエージェントの実行に対するアップデートを購読できます。これは、エンドユーザーに進捗や部分的な応答を表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出して [`RunResultStreaming`][agents.result.RunResultStreaming] を取得します。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これは [`RunResultStreaming`][agents.result.RunResultStreaming] を返します。`result.stream_events()` を呼ぶと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 ## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API フォーマットであり、各イベントは `response.created` や `response.output_text.delta` などのタイプとデータを持ちます。これらは、生成され次第、ユーザーに応答メッセージをストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。形式は OpenAI Responses API で、各イベントには `response.created` や `response.output_text.delta` などの type とデータがあります。これらのイベントは、生成され次第、ユーザーにレスポンスメッセージをストリーミングしたい場合に有用です。 -例えば、次のコードは LLM が生成したテキストをトークンごとに出力します。 +たとえば、次の例は LLM が生成するテキストをトークンごとに出力します。 ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## Run item イベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルなイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などの粒度で進行状況をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更された（例: ハンドオフの結果として）際の更新を通知します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などの粒度で進捗を更新できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果として）の更新を提供します。 -例えば、次のコードは raw イベントを無視して、ユーザーへ更新をストリーミングします。 +たとえば、次の例は raw なイベントを無視し、ユーザーにアップデートをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 4e9e67bb0..2fb29e964 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行できるようにします。たとえばデータの取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作 などです。Agents SDK にはツールのクラスが 3 つあります。 +ツールは エージェント にアクションを実行させます。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作 まで可能です。Agents SDK には 3 つのツールのクラスがあります: -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は ファイル検索、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 -- 関数呼び出し: 任意の Python 関数をツールとして使用できます。 -- ツールとしてのエージェント: エージェント をツールとして使用でき、ハンドオフ せずに他の エージェント を呼び出せます。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI はリトリーバル、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 +- Function calling: 任意の Python 関数 をツールとして使用できます。 +- ツールとしての エージェント: エージェント をツールとして使用でき、ハンドオフ せずに他の エージェント を呼び出せます。 ## ホスト型ツール -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。 +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかのビルトインツールを提供しています: - [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web を検索させます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を可能にします。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストア から情報を取得できます。 +- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 タスクを自動化できます。 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 - [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバー のツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はあなたのマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして使用できます。Agents SDK が自動でツールを設定します。 +任意の Python 関数 をツールとして使用できます。Agents SDK が自動でツールをセットアップします: -- ツール名は Python 関数名になります（または任意の名前を指定できます） -- ツールの説明は関数の docstring から取得されます（または説明を指定できます） +- ツール名は 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 型を使用でき、関数は同期・非同期どちらでも構いません。 -2. docstring がある場合、説明および引数の説明の取得に使用します。 -3. 関数は任意で `context` を最初の引数として受け取れます。ツール名や説明、docstring スタイルなどの上書きも設定できます。 -4. デコレートした関数はツールのリストに渡せます。 +1. 関数の引数として任意の Python 型 を使用でき、関数は同期・非同期いずれでも構いません。 +2. docstring が存在する場合、説明および引数の説明として使用します。 +3. 関数はオプションで `context` を最初の引数として受け取れます。ツール名、説明、docstring スタイルなどのオーバーライドを設定することもできます。 +4. デコレートした関数をツールのリストに渡せます。 -??? note "展開して出力を見る" +??? note "出力を表示するには展開してください" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。その場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。以下を指定する必要があります。 +Python 関数 をツールとして使いたくない場合もあります。代わりに直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次の指定が必要です: - `name` - `description` - `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツールの出力文字列を返す async 関数） +- `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 モデル、TypedDicts など大半の型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。形式の自動検出も試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に指定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することもできます。 +1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションを用いて引数の型を把握し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することもできます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 ## ツールとしてのエージェント -一部のワークフローでは、制御をハンドオフ する代わりに、中央の エージェント が専門 エージェント のネットワークをオーケストレーションしたい場合があります。エージェント をツールとしてモデル化することで実現できます。 +一部のワークフローでは、ハンドオフ せずに中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。エージェント をツールとしてモデル化することで実現できます。 ```python from agents import Agent, Runner @@ -269,7 +269,7 @@ async def main(): ### ツール化したエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント を簡単にツール化するための補助メソッドです。ただし、すべての設定をサポートしているわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください。 +`agent.as_tool` 関数は、エージェント をツール化するための簡便メソッドです。ただし、すべての設定をサポートしているわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を変更したいことがあります。たとえば次のような場合に有用です。 +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に便利です: -- サブエージェント のチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 +- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 - エージェント の最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 -- エージェント の応答が欠落または不正な場合に、出力を検証したりフォールバック値を提供したりする。 +- 出力を検証し、エージェント の応答が欠落している、または不正な場合にフォールバック値を提供する。 -これは、`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで行えます。 +`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -315,13 +315,81 @@ json_tool = data_agent.as_tool( ) ``` -## 関数ツールにおけるエラー処理 +### ツールの条件付き有効化 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラー応答を提供する関数です。 +実行時に `is_enabled` パラメーター を使用して エージェント のツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザー の嗜好、実行時条件に基づいて、LLM に利用可能なツールを動的にフィルタリングできます。 -- 既定（何も渡さない場合）では、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 -- 独自のエラー関数を渡した場合はそれが実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、呼び出し元で処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになり得ます。 +```python +import asyncio +from agents import Agent, AgentBase, Runner, RunContextWrapper +from pydantic import BaseModel + +class LanguageContext(BaseModel): + language_preference: str = "french_spanish" + +def french_enabled(ctx: RunContextWrapper[LanguageContext], agent: AgentBase) -> bool: + """Enable French for French+Spanish preference.""" + return ctx.context.language_preference == "french_spanish" + +# Create specialized agents +spanish_agent = Agent( + name="spanish_agent", + instructions="You respond in Spanish. Always reply to the user's question in Spanish.", +) + +french_agent = Agent( + name="french_agent", + instructions="You respond in French. Always reply to the user's question in French.", +) + +# Create orchestrator with conditional tools +orchestrator = Agent( + name="orchestrator", + instructions=( + "You are a multilingual assistant. You use the tools given to you to respond to users. " + "You must call ALL available tools to provide responses in different languages. " + "You never respond in languages yourself, you always use the provided tools." + ), + tools=[ + spanish_agent.as_tool( + tool_name="respond_spanish", + tool_description="Respond to the user's question in Spanish", + is_enabled=True, # Always enabled + ), + french_agent.as_tool( + tool_name="respond_french", + tool_description="Respond to the user's question in French", + is_enabled=french_enabled, + ), + ], +) + +async def main(): + context = RunContextWrapper(LanguageContext(language_preference="french_spanish")) + result = await Runner.run(orchestrator, "How are you?", context=context.context) + print(result.final_output) + +asyncio.run(main()) +``` + +`is_enabled` パラメーター は次を受け付けます: +- **真偽値**: `True`（常に有効）または `False`（常に無効） +- **呼び出し可能関数**: `(context, agent)` を受け取り、真偽値を返す関数 +- **非同期関数**: 複雑な条件ロジック向けの async 関数 + +無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: +- ユーザー 権限に基づく機能ゲーティング +- 環境別のツール可用性（dev と prod の違い） +- 異なるツール構成の A/B テスト +- 実行時状態に基づく動的ツールフィルタリング + +## 関数ツールでのエラー処理 + +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを提供する関数です。 + +- 既定では（何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 +- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しエラーは再スローされ、あなたが処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、あなたのコードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -344,4 +412,4 @@ def get_user_profile(user_id: str) -> str: ``` -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数の内部でエラー処理を行う必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラー処理を行う必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 88c4e9042..c1bf6a7dd 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,48 +4,48 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェント実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまで含まれます。[Traces ダッシュボード](https://platform.openai.com/traces)を使用して、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。例えば、 LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまで含まれます。 [Traces ダッシュボード](https://platform.openai.com/traces) を使って、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。トレーシングを無効化する方法は 2 つあります。 + トレーシングはデフォルトで有効です。トレーシングを無効化する方法は 2 つあります: 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 単一の実行に対して、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 2. 単一の実行でトレーシングを無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し、 Zero Data Retention (ZDR) ポリシーに基づいて運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース (Traces)** は「ワークフロー」の単一のエンドツーエンド処理を表します。スパンで構成されます。トレースには次のプロパティがあります。 +- **トレース (Traces)** は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されます。トレースには次のプロパティがあります: - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 同一会話からの複数のトレースを紐付けるための任意のグループ ID。例: チャットスレッド ID など - - `disabled`: True の場合、このトレースは記録されません。 - - `metadata`: トレースの任意メタデータ -- **スパン (Spans)** は開始と終了時間を持つ処理を表します。スパンには次があります。 - - `started_at` と `ended_at` タイムスタンプ - - `trace_id`: 所属するトレースを表します - - `parent_id`: このスパンの親スパン (ある場合) を指します - - `span_data`: スパンに関する情報。例えば、`AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報が含まれます。 + - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースを関連付けるために使用します。例えば、チャットスレッド ID を使用できます。 + - `disabled`: True の場合、トレースは記録されません。 + - `metadata`: トレースの省略可能なメタデータ。 +- **スパン (Spans)** は開始と終了時刻を持つ操作を表します。スパンには次があります: + - `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()` にラップされます -- 音声入力 (音声認識) は `transcription_span()` にラップされます -- 音声出力 (音声合成) は `speech_span()` にラップされます -- 関連する音声スパンは `speech_group_span()` の下に親子付けされることがあります +- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます。 +- エージェントが実行されるたびに、`agent_span()` でラップされます +- LLM 生成は `generation_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます +- ガードレールは `guardrail_span()` でラップされます +- ハンドオフは `handoff_span()` でラップされます +- 音声入力 (音声認識) は `transcription_span()` でラップされます +- 音声出力 (テキスト読み上げ) は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親子関係で配置される場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合にこの名前を設定できますし、または [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] を使って名前やその他のプロパティを構成できます。 -さらに、[カスタムトレース プロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先に送信できます (置き換えまたは副次的な宛先として)。 +さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、トレースを別の送信先へ送ることもできます (置き換えや、セカンダリ送信先として)。 ## より高レベルのトレース @@ -64,46 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `with trace()` で 2 回の `Runner.run` 呼び出しがラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. `with trace()` で 2 回の `Runner.run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります。 +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。次の 2 つの方法があります: -1. 推奨: トレースをコンテキストマネージャとして使用します。例: `with trace(...) as my_trace`。これにより、適切なタイミングでトレースが自動的に開始・終了します。 -2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出すこともできます。 +1. 推奨: トレースをコンテキストマネージャとして使用します。例: `with trace(...) as my_trace`。これにより適切なタイミングでトレースが自動的に開始・終了します。 +2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これにより、自動的に並行処理で機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。つまり、自動的に並行処理で機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために、[`custom_span()`][agents.tracing.custom_span] 関数が利用可能です。 +さまざまな [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が用意されています。 -スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される最も近い現在のスパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、 Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される最も近い現在のスパンの下にネストされます。 ## 機微なデータ -一部のスパンでは、機微なデータが取得される可能性があります。 +一部のスパンは機微なデータを取得する可能性があります。 -`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそれらのデータの取得を無効化できます。 -同様に、音声スパンにはデフォルトで、入力および出力音声の base64 でエンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成して、この音声データの取得を無効化できます。 +同様に、音声スパンはデフォルトで入力および出力音声の 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] にトレース/スパンを送信します。`BackendSpanExporter` はスパンとトレースを OpenAI バックエンドにバッチでエクスポートします。 -このデフォルト設定をカスタマイズして、トレースを別のバックエンドや追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります。 +デフォルト設定をカスタマイズし、別のバックエンドへ送信したり、追加のバックエンドへ送信したり、エクスポーターの動作を変更するには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第それらを受け取る、追加のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーで置き換えられます。つまり、OpenAI バックエンドにトレースを送信する `TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第、受け取る追加のトレースプロセッサーを追加できます。これにより、 OpenAI のバックエンドへの送信に加えて独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーで置き換えることができます。つまり、 OpenAI バックエンドにトレースを送信するには、そのための `TracingProcessor` を含める必要があります。 -## OpenAI 以外のモデルでのトレーシング +## 非 OpenAI モデルでのトレーシング -OpenAI の API キーを OpenAI 以外のモデルと併用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。 +OpenAI の API キーを非 OpenAI モデルで使用することで、トレーシングを無効化せずに OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -125,7 +125,7 @@ agent = Agent( ``` ## 注意 -- 無料のトレースは OpenAI Traces ダッシュボードで表示できます。 +- 無料のトレースは Openai Traces ダッシュボードで確認できます。 ## 外部トレーシング プロセッサー一覧 diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 438b1d896..ee75f9df5 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,7 +4,7 @@ search: --- # エージェントの可視化 -エージェントの可視化では、 ** Graphviz ** を使用してエージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を用いてエージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: +`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- ** エージェント ** は黄色のボックスで表されます。 -- ** MCP サーバー ** は灰色のボックスで表されます。 -- ** ツール ** は緑色の楕円で表されます。 -- ** ハンドオフ ** はエージェント間の有向エッジです。 +- **エージェント** は黄色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 +- **ツール** は緑の楕円で表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -67,36 +67,36 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェントのグラフ](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -これは、 ** トリアージ エージェント ** の構造と、そのサブエージェントやツールとの接続を視覚的に表現するグラフを生成します。 +これは、 **トリアージ エージェント** と、そのサブエージェントやツールへの接続構造を視覚的に表すグラフを生成します。 ## 可視化の理解 生成されるグラフには次が含まれます: -- エントリポイントを示す ** スタートノード **（`__start__`）。 -- 黄色で塗りつぶされた ** 長方形 ** で表されるエージェント。 -- 緑色で塗りつぶされた ** 楕円 ** で表されるツール。 -- 灰色で塗りつぶされた ** 長方形 ** で表される MCP サーバー。 +- エントリポイントを示す **開始ノード**（`__start__`）。 +- 黄色で塗りつぶされた **長方形** で表されるエージェント。 +- 緑で塗りつぶされた **楕円** で表されるツール。 +- 灰色で塗りつぶされた **長方形** で表される MCP サーバー。 - 相互作用を示す有向エッジ: - - エージェント間のハンドオフには ** 実線の矢印 **。 - - ツール呼び出しには ** 点線の矢印 **。 - - MCP サーバー呼び出しには ** 破線の矢印 **。 -- 実行が終了する場所を示す ** エンドノード **（`__end__`）。 + - エージェント間のハンドオフには **実線の矢印**。 + - ツール呼び出しには **点線の矢印**。 + - MCP サーバー呼び出しには **破線の矢印**。 +- 実行が終了する場所を示す **終了ノード**（`__end__`）。 ## グラフのカスタマイズ ### グラフの表示 -既定では、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: +デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -既定では、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: +デフォルトでは、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 86a9129ed..940d24c25 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント型のワークフローを音声アプリに変換しやすくするクラスです。実行するワークフローを渡すと、入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声化までをパイプラインが処理します。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントのワークフローを音声アプリに容易に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフローの出力を音声に戻す処理を行います。 ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## パイプラインの設定 -パイプライン作成時に、次の設定が可能です: +パイプラインを作成する際に、次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]: 新しい音声が文字起こしされるたびに実行されるコード -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 次のような設定が可能です - - モデルプロバイダー: モデル名をモデルにマッピング - - トレーシング: トレーシングの無効化、音声ファイルのアップロード可否、ワークフロー名、トレース ID など - - TTS と STT モデルの設定: プロンプト、言語、使用するデータ型など +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]：新しい音声が文字起こしされるたびに実行されるコード +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] のモデル +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]：次のような項目を設定できます + - モデル名をモデルにマッピングできるモデ​​ルプロバイダー + - トレーシング（トレーシングを無効にするか、音声ファイルをアップロードするか、ワークフロー名、トレース ID など） + - プロンプト、言語、使用するデータ型など、TTS と STT モデルの設定 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます: +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力は次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput]: 全体の音声文字起こしがあり、その結果に対する出力だけを生成したい場合に使用します。話者が話し終えるタイミングの検知が不要なケース、たとえば事前録音の音声や、ユーザーの発話終了が明確なプッシュ・トゥ・トークのアプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]: ユーザーの発話終了を検知する必要がある場合に使用します。検知された音声チャンクを逐次プッシュでき、パイプラインは「アクティビティ検出」により適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完結した音声区間があり、その結果だけを生成したい場合に使用します。たとえば、事前録音の音声や、話し終わりが明確なプッシュトゥトークのアプリなど、話者の発話終了を検出する必要がないケースに有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの話し終わりを検出する必要がある場合に使用します。検出された音声チャンクを順次プッシュでき、パイプラインは「アクティビティ検知」によって適切なタイミングで自動的にエージェントのワークフローを実行します。 ## 結果 -音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは発生したイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます: +音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングで受け取れるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] にはいくつかの種類があり、次のようなものがあります。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]: 音声チャンクを含みます。 -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]: ターンの開始や終了などのライフサイクルイベントを通知します。 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]: エラーイベントです。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]：音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]：ターンの開始や終了などのライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]：エラーイベントです。 ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現時点で、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み処理をサポートしていません。検知された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを購読してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンの音声がすべて送出された後にトリガーされます。モデルがターンを開始したときに話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にアンミュートする、といった制御にこれらのイベントを利用できます。 \ No newline at end of file +Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとに、ワークフローの個別の実行をトリガーします。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントをリッスンしてください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当するターンの音声がすべてディスパッチされた後に発火します。これらのイベントを用いて、モデルがターンを開始したときに話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュし終えた後にミュートを解除する、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 25056db64..f04e90b59 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従って仮想環境をセットアップしてください。その後、SDK のオプションの音声関連の依存関係をインストールします。 +Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、次の 3 段階のプロセスです。 +理解すべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 段階のプロセスです: -1. 音声をテキストに変換する音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。 -3. その結果テキストを音声に戻すために音声合成モデルを実行します。 +1. 音声をテキストに変換するために音声認識モデルを実行します。 +2. 通常はエージェント的なワークフローであるあなたのコードを実行して結果を生成します。 +3. テキスト読み上げモデルを実行して、結果のテキストを音声に戻します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかの エージェント を設定します。これは、この SDK でエージェントを作成したことがある方には馴染みがあるはずです。ここでは、複数の エージェント、ハンドオフ、そして ツール を用意します。 +まず、いくつかのエージェントを設定します。この SDK でエージェントを作成したことがあるなら、馴染みがあるはずです。ここでは 2 つのエージェント、ハンドオフ、そしてツールを用意します。 ```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 0a4e93504..41a327aa3 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレーシングされます。 +[エージェントのトレーシング](../tracing.md) の方法と同様に、音声パイプラインも自動でトレーシングされます。 -基本的なトレーシング情報は上記ドキュメントをご参照ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを構成できます。 +基本的なトレーシング情報については上記のドキュメントをご確認ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] でパイプラインのトレーシングを設定できます。 -トレーシングに関する主なフィールドは次のとおりです。 +トレーシング関連の主なフィールドは次のとおりです: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。既定ではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: オーディオの書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、 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` です。 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかを制御します。既定ではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしなど、機微なデータをトレースに含めるかを制御します。これは音声パイプラインに特有であり、ワークフロー (Workflow) 内で行われる処理には適用されません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための、このトレースの `group_id` です。 - [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file