diff --git a/docs/ja/agents.md b/docs/ja/agents.md index ddd70e236..86c962451 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリのコアとなる構成要素です。エージェントは、大規模言語モデル ( LLM ) に instructions と tools を設定したものです。 +エージェントはアプリのコアとなる構成要素です。エージェントは instructions とツールで設定された大規模言語モデル(LLM)です。 ## 基本設定 -エージェントで最もよく設定するプロパティは次のとおりです: +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer メッセージ、または system prompt とも呼ばれます。 -- `model`: 使用する LLM と、temperature や top_p などのチューニングパラメーターを設定する `model_settings` (任意)。 -- `tools`: エージェントがタスクを遂行するために使用できる tools。 +- `name`: エージェントを識別する必須の文字列。 +- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 +- `model`: 使用する LLM、および temperature や top_p などのモデルチューニングパラメーターを設定する任意の `model_settings`。 +- `tools`: エージェントがタスクを達成するために使用できるツール。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、tool、handoff などに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の 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、list、TypedDict など—であれば何でもサポートされています。 ```python from pydantic import BaseModel @@ -73,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは必要に応じてそれらに委任できます。これは、単一タスクに特化したモジュール型エージェントをオーケストレーションする強力なパターンです。詳細は [handoffs](handoffs.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡しておくと、エージェントは適切な場合にそれらへ委任できます。これは、単一タスクに特化したモジュール式エージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントを参照してください。 ```python from agents import Agent @@ -98,7 +98,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を渡せますが、関数を使って動的に生成することも可能です。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方に対応しています。 +多くの場合、エージェント作成時に instructions を指定しますが、関数を介して動的に instructions を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返さなければなりません。同期関数・`async` 関数のどちらも使用できます。 ```python def dynamic_instructions( @@ -113,17 +113,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクルイベント(フック) -エージェントのライフサイクルを観察したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりするケースです。`hooks` プロパティを使用してエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスを継承し、必要なメソッドをオーバーライドしてください。 +エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティを利用してエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] を継承し、必要なメソッドをオーバーライドしてください。 ## ガードレール -ガードレールを使用すると、エージェント実行と並行してユーザー入力のチェック / バリデーションを行えます。たとえば、ユーザー入力の関連性を確認することができます。詳細は [guardrails](guardrails.md) のドキュメントをご覧ください。 +ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェック/バリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 -## エージェントのクローン / 複製 +## エージェントの複製/コピー -エージェントの `clone()` メソッドを使うと、エージェントを複製し、任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -tool のリストを指定しても、 LLM が必ずしも tool を使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、tool 使用を強制できます。有効な値は次のとおりです: +ツールのリストを指定しても、LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は次のとおりです。 -1. `auto` : LLM が tool を使うかどうかを判断します。 -2. `required` : LLM に tool の使用を必須とさせます ( どの tool を使うかは判断できます )。 -3. `none` : LLM に tool を使用しないことを要求します。 -4. 文字列を指定 ( 例: `my_tool` ) : 指定した tool の使用を要求します。 +1. `auto`: LLM がツールを使うかどうかを判断します。 +2. `required`: LLM にツール使用を必須とします(使用するツールは自動選択されます)。 +3. `none`: LLM にツールを使用しないことを要求します。 +4. 具体的な文字列(例: `my_tool`)を設定すると、その特定のツールの使用を要求します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -163,11 +163,11 @@ agent = Agent( ) ``` -## ツール使用時の動作 +## ツール使用動作 -`Agent` の `tool_use_behavior` パラメーターは、tool の出力をどのように扱うかを制御します: -- `"run_llm_again"` : デフォルト。tool を実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"` : 最初の 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=[...])` : 指定した tool が呼び出された時点で停止し、その出力を最終応答として使用します。 +- `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` : tool の結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 +- `ToolsToFinalOutputFunction`: ツールの結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -245,4 +245,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークは tool 呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、tool の結果が LLM に渡され、`tool_choice` の指定により再び tool 呼び出しが生成される、というサイクルが続くことが原因です。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に自動で `tool_choice` を "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定可能です。ツール結果が LLM に送られ、`tool_choice` により再度ツール呼び出しが生成される…というループを防ぐためです。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 0059a7d2c..36969a7f6 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を参照します。アプリの起動前にこの環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 +デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストと トレーシング のために `OPENAI_API_KEY` 環境変数を探します。アプリが起動する前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は `AsyncOpenAI` インスタンスを作成し、環境変数または上記で設定したデフォルトキーから API キーを取得します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用してください。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は `AsyncOpenAI` インスタンスを作成し、環境変数または前述のデフォルトキーに設定された API キーを使用します。これを変更するには、[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 をカスタマイズすることも可能です。デフォルトでは、 Responses API を使用しています。これを Chat Completions API に切り替えるには、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使用してください。 +最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは、 OpenAI Responses API を使用します。[set_default_openai_api()][agents.set_default_openai_api] 関数を使用して Chat Completions API を使用するように上書きできます。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効になっています。デフォルトでは、前述の OpenAI API キー(環境変数または設定したデフォルトキー)が使用されます。トレーシングに使用する API キーを個別に設定するには、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。デフォルトでは、前述の OpenAI API キー(環境変数または設定したデフォルトキー)が使用されます。[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用して、トレーシングに使用される API キーを個別に設定できます。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化するには、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用すると、トレーシングを完全に無効化できます。 ```python from agents import set_tracing_disabled @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## デバッグログ -SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に出力されますが、それ以外のログは抑制されます。 +SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。そのため、デフォルトでは警告とエラーは `stdout` に送られますが、それ以外のログは抑制されます。 -詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 +詳細ログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -85,13 +85,13 @@ 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 091755b89..a64cdcc42 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. そのオブジェクトをさまざまな run メソッド (例: `Runner.run(..., **context=whatever**)`) に渡します。 -3. すべてのツール呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使用します。 +2. そのオブジェクトを各種 run メソッド(例: `Runner.run(..., **context=whatever**)`)に渡します。 +3. すべてのツール呼び出しやライフサイクルフックには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -**最も重要** な点は、特定のエージェント実行において、エージェント、ツール関数、ライフサイクルフックなどはすべて同じコンテキストの _型_ を使用しなければならないということです。 +最も重要なポイント: あるエージェントの 1 回の実行において、エージェント、ツール関数、ライフサイクルフックなどはすべて同じ _型_ のコンテキストを使用する必要があります。 -コンテキストは次のような用途で利用できます。 +コンテキストは次のような用途に利用できます。 -- 実行時のコンテキストデータ (例: ユーザー名 / uid やその他の user に関する情報) -- 依存関係 (例: ロガーオブジェクト、データフェッチャーなど) -- ヘルパー関数 +- 実行に関するデータ(例: ユーザー名 / uid やその他ユーザー情報) +- 依存関係(例: ロガーオブジェクト、データフェッチャーなど) +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは **LLM に送信されません**。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは **LLM に送信されません**。純粋にローカルで読み書きやメソッド呼び出しを行うためのオブジェクトです。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから値を読み取ります。 -3. ジェネリック型として `UserInfo` をエージェントに指定することで、型チェッカーがエラーを検出できます (たとえば、異なるコンテキスト型を取るツールを渡そうとした場合など)。 -4. コンテキストは `run` 関数に渡されます。 -5. エージェントはツールを正しく呼び出し、年齢を取得します。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 +3. エージェントにジェネリック型 `UserInfo` を指定しているため、型チェッカーがエラーを検出できます(例: 異なるコンテキスト型を受け取るツールを渡した場合など)。 +4. `run` 関数にコンテキストを渡しています。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント / LLM コンテキスト - LLM が呼び出される際に参照できるデータは、会話履歴の内容だけです。そのため、新しいデータを LLM に渡したい場合は、そのデータを会話履歴に含める形で提供しなければなりません。これを実現する方法はいくつかあります。 +LLM が呼び出される際、LLM が参照できるデータは会話履歴のみです。したがって、新しいデータを LLM に提供したい場合は、そのデータが履歴に含まれるようにする必要があります。主な方法は次のとおりです。 -1. エージェントの `instructions` に追加する。これは「システムプロンプト」または「デベロッパーメッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的な関数でもかまいません。ユーザー名や現在の日付など、常に役立つ情報を渡す際によく使われる手法です。 -2. `Runner.run` 関数を呼び出す際に `input` に追加する。この方法は `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 内でより下位のメッセージとして渡せます。 -3. 関数ツールを通じて公開する。これはオンデマンドのコンテキストに便利です ― LLM が必要だと判断したときにツールを呼び出してデータを取得できます。 -4. retrieval や Web 検索を使用する。retrieval はファイルやデータベースから関連データを取得し、Web 検索は Web から取得します。関連するコンテキストデータで応答をグラウンディングするのに役立ちます。 \ No newline at end of file +1. エージェントの `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。system prompt は静的な文字列でも、コンテキストを受け取って文字列を返す動的な関数でもかまいません。ユーザー名や現在の日付など、常に有用な情報を渡す場合によく使われます。 +2. `Runner.run` を呼び出すときの `input` に追加する。`instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより下位のメッセージとして扱われます。 +3. 関数ツール経由で公開する。これはオンデマンドのコンテキストに便利です。LLM が必要に応じてツールを呼び出し、そのデータを取得できます。 +4. リトリーバルや Web 検索を使う。これらはファイルやデータベースから関連データを取得する(リトリーバル)、あるいは Web から取得する(Web 検索)特殊なツールです。回答を適切なコンテキストデータに「基づかせる」ために有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 5c075e77d..cbccb7519 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -2,46 +2,47 @@ search: exclude: true --- -# コード例 +# サンプルコード + +さまざまな実装例は、[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでご覧いただけます。これらのサンプルコードは、異なるパターンや機能を示すいくつかのカテゴリーに整理されています。 -SDK の examples セクションでは、さまざまな実装サンプルを確認できます。[repo](https://github.com/openai/openai-agents-python/tree/main/examples) をご覧ください。これらの code examples は、異なるパターンと機能を示す複数の カテゴリー に整理されています。 ## カテゴリー -- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - この カテゴリー では、一般的な エージェント 設計パターンを示します。 +- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** + このカテゴリーでは、代表的なエージェント設計パターンを示しています。 - - 決定的なワークフロー - - エージェント をツールとして使用 - - エージェント の並列実行 + - 決定論的ワークフロー + - エージェントをツールとして扱うパターン + - エージェントの並列実行 -- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - ここでは、以下のような SDK の基礎的な機能を紹介します。 +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + ここでは、 SDK の基礎的な機能を紹介しています。 - - 動的な system prompt - - ストリーミング 出力 - - ライフサイクル イベント + - 動的な system prompt + - ストリーミング出力 + - ライフサイクルイベント -- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツールの実装方法と、それらを エージェント に統合する方法を学べます。 +- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + Web 検索やファイル検索といった OpenAI がホストするツールを実装し、エージェントに統合する方法を学べます。 -- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを SDK と組み合わせて使用する方法を紹介します。 +- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK で利用する方法を確認できます。 -- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェント ハンドオフの実用的な例をご覧いただけます。 +- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + エージェントのハンドオフを実践的に示すサンプルです。 -- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP を使った エージェント 構築方法を学べます。 +- **[mcp](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 つの code examples +- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** + 実用的なアプリケーションを示す、より完成度の高い 2 つの例です。 - - **customer_service**: 航空会社向けカスタマーサービス システムの例。 - - **research_bot**: シンプルな ディープリサーチ クローン。 + - **customer_service**: 航空会社向けカスタマーサービスシステムの例 + - **research_bot**: シンプルなディープリサーチ クローン -- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを使用した音声 エージェント の例をご覧いただけます。 +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + TTS と STT モデルを用いた音声エージェントの例をご覧いただけます。 -- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を利用してリアルタイム体験を構築する方法を示す例。 \ No newline at end of file +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使ってリアルタイム体験を構築する方法を示す例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index 672682606..1339652c1 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` を生成し、それが `InputGuardrailResult` でラップされます。 -3. 最後に `.tripwire_triggered` が true かどうかを確認します。true の場合、`InputGuardrailTripwireTriggered` 例外が送出され、ユーザーへの応答や例外処理を適切に行えます。 +1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成します。その結果は [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。 true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの応答や例外処理を適切に行えます。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントが *最初の* エージェントである場合にのみ実行されます。「`guardrails` プロパティがエージェント上にあるのはなぜで、`Runner.run` に渡さないのか?」と疑問に思うかもしれません。ガードレールは実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行することになるので、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントである場合にのみ実行されます。「なぜ `guardrails` プロパティが `Runner.run` への引数ではなくエージェントにあるのか?」と疑問に思うかもしれません。ガードレールは実際の エージェント に密接に関連する傾向があり、エージェントごとに異なるガードレールを走らせることになるので、コードを同じ場所に置くほうが可読性に優れるためです。 ## 出力ガードレール -出力ガードレールは次の 3 段階で実行されます: +出力ガードレールは次の 3 ステップで実行されます: 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され `GuardrailFunctionOutput` を生成し、それが `OutputGuardrailResult` でラップされます。 -3. 最後に `.tripwire_triggered` が true かどうかを確認します。true の場合、`OutputGuardrailTripwireTriggered` 例外が送出され、ユーザーへの応答や例外処理を適切に行えます。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成します。その結果は [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。 true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの応答や例外処理を適切に行えます。 !!! Note - 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントが *最後の* エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連しているため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終出力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最後* のエージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際の エージェント に関連しているため、エージェントごとに異なるガードレールを設定できるようコードを同じ場所に置いておくと可読性が向上します。 -## トリップワイヤ +## トリップワイヤー -入力または出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤでこれを通知できます。トリップワイヤが発動したガードレールを検知すると、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーが発動したガードレールを検出するとただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、`GuardrailFunctionOutput` を返す関数を用意する必要があります。以下の例では、内部でエージェントを実行してこれを行います。 +入力を受け取り [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部で エージェント を実行して実現します。 ```python from pydantic import BaseModel @@ -95,9 +95,9 @@ async def main(): ``` 1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果に追加情報を含めることができます。 -4. これがワークフローを定義する実際のエージェントです。 +2. これがエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレールの結果に追加情報を含めることもできます。 +4. こちらがワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. これは実際のエージェントの出力型です。 -2. これはガードレールの出力型です。 -3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. これがワークフローを定義する実際のエージェントです。 \ No newline at end of file +1. こちらが実際のエージェントの出力型です。 +2. こちらがガードレールの出力型です。 +3. これがエージェントの出力を受け取り、結果を返すガードレール関数です。 +4. こちらがワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index e83f56fc9..794f1ac3e 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# ハンドオフ +# Handoffs -ハンドオフを使用すると、ある エージェント がタスクを別の エージェント に委任できます。これは、異なる エージェント がそれぞれ特定の分野を専門とするシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、 FAQ など各タスクを担当する エージェント を用意することがあります。 +Handoffs により、あるエージェントがタスクを別のエージェントに委譲できます。これは、異なるエージェントがそれぞれ特定分野を専門とするシナリオで特に便利です。たとえばカスタマーサポートアプリでは、注文状況、払い戻し、FAQ などを個別に処理するエージェントがいる場合があります。 -ハンドオフは LLM から見るとツールとして表現されます。そのため、`Refund Agent` へのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 +Handoffs は LLM からはツールとして表現されます。たとえば `Refund Agent` への handoff がある場合、ツール名は `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] 関数を使って handoff を作成できます。この関数では、委譲先のエージェントの指定に加えて、各種オーバーライドや入力フィルターを設定できます。 ### 基本的な使い方 -シンプルなハンドオフを作成する方法は次のとおりです: +シンプルな handoff を作成する方法は次のとおりです。 ```python from agents import Agent, handoff @@ -28,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のように エージェント を直接渡す方法と、 `handoff()` 関数を使用する方法があります。 +1. `billing_agent` のようにエージェントを直接指定することも、`handoff()` 関数を使用することもできます。 -### `handoff()` 関数によるハンドオフのカスタマイズ +### `handoff()` 関数による handoff のカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数では以下の項目をカスタマイズできます。 -- `agent` : ハンドオフ先となる エージェント です。 -- `tool_name_override` : 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` となります。これを上書きできます。 -- `tool_description_override` : `Handoff.default_tool_description()` で生成されるデフォルトのツール説明を上書きします。 -- `on_handoff` : ハンドオフが呼び出された際に実行されるコールバック関数です。ハンドオフが行われた瞬間にデータ取得を開始するなどの用途に便利です。この関数は エージェント のコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データの有無は `input_type` パラメーターで制御します。 -- `input_type` : ハンドオフが受け取る入力の型(任意)。 -- `input_filter` : 次の エージェント が受け取る入力をフィルタリングできます。詳細は後述します。 +- `agent`: 委譲先となるエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` という形式になります。ここを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 +- `on_handoff`: handoff が呼び出された際に実行されるコールバック関数です。handoff が行われた時点でデータ取得を開始したい場合などに便利です。この関数はエージェントコンテキストを受け取り、必要であれば LLM が生成した入力も受け取れます。どの入力データが渡されるかは `input_type` パラメーターで制御します。 +- `input_type`: handoff が想定する入力の型です (任意)。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。 ```python from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフ入力 +## Handoff の入力 -状況によっては、ハンドオフを呼び出す際に LLM からデータを受け取りたいことがあります。たとえば「Escalation agent」へのハンドオフでは、ログ用に理由を渡してもらいたいかもしれません。 +状況によっては、LLM が handoff を呼び出す際に何らかのデータを渡してほしい場合があります。たとえば「Escalation agent」への handoff では、ログ用に理由も渡したいといったケースです。 ```python from pydantic import BaseModel @@ -81,11 +81,11 @@ handoff_obj = handoff( ) ``` -## 入力フィルター +## Input filters -ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できる状態になります。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定してください。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +Handoff が発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を閲覧できる状態になります。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。Input filter は、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 -履歴からすべてのツール呼び出しを削除するなど、よくあるパターンは [`agents.extensions.handoff_filters`][] に実装済みです。 +よくあるパターン (たとえば履歴からすべてのツール呼び出しを取り除くなど) は [`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. `FAQ agent` が呼び出されると、履歴からすべてのツールが自動的に削除されます。 +1. これにより `FAQ agent` が呼び出されたとき、履歴から自動で全ツールが削除されます。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるよう、 エージェント のプロンプトにハンドオフに関する情報を含めることを推奨します。推奨されるプレフィックスは [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] にあります。また、 [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨情報を自動追加することもできます。 +LLM が handoffs を正しく理解するように、エージェント内に handoff に関する情報を含めることを推奨します。[`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 d678a92e3..ab22a3fa1 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 アプリを構築できる SDK です。これは、以前のエージェント向け実験プロジェクト [Swarm](https://github.com/openai/swarm/tree/main) を、本番利用向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 -- **Agents**: instructions と tools を備えた LLM -- **Handoffs**: 特定のタスクを他のエージェントに委任できる機能 -- **Guardrails**: エージェントへの入力を検証する仕組み -- **Sessions**: エージェント実行間で会話履歴を自動管理する機能 +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントへ委任する仕組み +- **ガードレール**: エージェントへの入力を検証する仕組み +- **セッション**: エージェント実行間で会話履歴を自動的に保持 -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなく実用的なアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェント フローの可視化・デバッグ・評価、さらにはモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらのコンポーネントは tools と エージェント 間の複雑な関係を表現でき、学習コストを抑えつつ実用的なアプリケーションを構築できます。さらに SDK には、エージェントフローの可視化・デバッグを可能にする **トレーシング** が組み込まれており、評価やファインチューニングまで行えます。 -## Agents SDK を利用する理由 +## Agents SDK を使用する理由 -SDK には次の 2 つの設計原則があります。 +SDK の設計原則は次の 2 点です。 -1. 使う価値のある十分な機能を備えつつ、学習が早いように基本コンポーネントを最小限にする。 -2. デフォルトで快適に動作しつつ、挙動を細かくカスタマイズできる。 +1. 利用価値のある十分な機能を持ちつつ、学習が速いようにコンポーネントを最小限に抑える。 +2. デフォルト設定で優れた動作をしつつ、挙動を細部までカスタマイズできる。 -主な機能は以下のとおりです。 +主な機能は次のとおりです。 -- Agent loop: tools の呼び出し、LLM への結果送信、LLM が完了するまでのループ処理を担う組み込みエージェント ループ。 -- Python ファースト: 新しい抽象化を学ばずに、言語そのものの機能でエージェントを編成・連結可能。 -- Handoffs: 複数エージェント間で調整・委任を行う強力な機能。 -- Guardrails: エージェントと並行して入力検証を実行し、失敗時には早期に処理を打ち切り。 -- Sessions: エージェント実行間の会話履歴を自動管理し、手動での状態管理を不要に。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic での検証を提供。 -- トレーシング: ワークフローの可視化・デバッグ・モニタリングに加え、OpenAI の評価・ファインチューニング・蒸留ツールを活用可能。 +- エージェントループ: tools の呼び出し、結果を LLM へ送信、LLM が完了するまでのループを自動処理。 +- Python ファースト: 新しい抽象を学ばずに、組み込み言語機能で エージェント をオーケストレーション・連鎖。 +- ハンドオフ: 複数のエージェント間で調整・委任を行う強力な機能。 +- ガードレール: エージェントと並行して入力検証を実行し、失敗時は早期停止。 +- セッション: エージェント実行間の会話履歴を自動管理し、手動での状態管理を不要に。 +- 関数ツール: 任意の Python 関数を tool 化し、スキーマ生成と Pydantic ベースの検証を自動化。 +- トレーシング: フローを可視化・デバッグ・監視でき、OpenAI の評価、ファインチューニング、蒸留ツールも利用可能。 ## インストール @@ -36,7 +36,7 @@ SDK には次の 2 つの設計原則があります。 pip install openai-agents ``` -## Hello World の例 +## Hello World 例 ```python from agents import Agent, Runner @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +(_実行する際は、環境変数 `OPENAI_API_KEY` を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 1a12f1029..b97f11735 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 (別名 MCP) は、 LLM にツールとコンテキストを提供するための方法です。 MCP のドキュメントから引用します: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。 USB-C がデバイスを周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、 MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを利用してエージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、 MCP 仕様では使用するトランスポートメカニズムに基づき、次の 3 種類のサーバーが定義されています。 +現在、 MCP 仕様では使用するトランスポートメカニズムに基づいて次の 3 種類のサーバーを定義しています: -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。いわば「ローカル」で動作します。 -2. **HTTP over SSE** サーバー: リモートで実行され、 URL 経由で接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 +1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。ローカルで動作するイメージです。 +2. **HTTP over SSE** サーバーはリモートで実行され、 URL 経由で接続します。 +3. **Streamable HTTP** サーバーは、 MCP 仕様で定義されている Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらのサーバーへは `MCPServerStdio` 、 `MCPServerSse` 、 `MCPServerStreamableHttp` クラスを使用して接続できます。 -以下は、[公式 MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する例です。 +たとえば、公式 MCP ファイルシステムサーバーを使用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびにその MCP サーバーの `list_tools()` を呼び出します。これにより、 LLM は MCP サーバーのツールを認識します。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。 Agents SDK はエージェント実行時に毎回 MCP サーバーの `list_tools()` を呼び出し、 LLM に MCP サーバーのツールを認識させます。 LLM が MCP サーバーのツールを呼び出すと、 SDK はそのサーバーの `call_tool()` を実行します。 ```python @@ -54,11 +54,11 @@ agent=Agent( ## ツールフィルタリング -MCP サーバーにツールフィルターを設定して、エージェントが利用できるツールを制限できます。SDK は静的および動的フィルタリングの両方をサポートしています。 +MCP サーバーでツールフィルターを設定することで、エージェントが利用できるツールを制限できます。 SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 ### 静的ツールフィルタリング -単純な許可/ブロックリストの場合は静的フィルタリングを使用します。 +単純な許可 / ブロックリストには静的フィルタリングを使用します: ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方を設定した場合の処理順序は次のとおりです。** -1. まず `allowed_tool_names`(許可リスト)を適用し、指定されたツールのみに絞り込みます。 -2. 次に `blocked_tool_names`(ブロックリスト)を適用し、残ったツールから指定されたツールを除外します。 +**`allowed_tool_names` と `blocked_tool_names` の両方を設定した場合の処理順序は次のとおりです:** +1. まず `allowed_tool_names` (許可リスト)を適用し、指定したツールのみを残します +2. 次に `blocked_tool_names` (ブロックリスト)を適用し、残ったツールから指定したツールを除外します -たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、利用可能なのは `read_file` と `write_file` だけになります。 +たとえば `allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、利用可能なのは `read_file` と `write_file` のみになります。 ### 動的ツールフィルタリング -より複雑なフィルタリングロジックが必要な場合は、関数を用いた動的フィルターを使用できます。 +より複雑なロジックが必要な場合は、関数を使った動的フィルタリングが利用できます: ```python from agents.mcp import ToolFilterContext @@ -134,10 +134,10 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次の情報にアクセスできます。 -- `run_context`: 現在の実行コンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +`ToolFilterContext` では次の情報にアクセスできます: +- `run_context`: 現在のランコンテキスト +- `agent`: ツールを要求しているエージェント +- `server_name`: MCP サーバー名 ## プロンプト @@ -145,10 +145,10 @@ MCP サーバーは、エージェントの instructions を動的に生成す ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します。 +プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します: -- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示 -- `get_prompt(name, arguments)`: 任意のパラメーターを付与して特定のプロンプトを取得 +- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示します +- `get_prompt(name, arguments)`: オプションのパラメーター付きで特定のプロンプトを取得します ```python # List available prompts @@ -173,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、`list_tools()` が MCP サーバーに呼び出されます。特にリモートサーバーの場合、これはレイテンシーの原因になります。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変化しないことが確実な場合にのみ使用してください。 +エージェントが実行されるたびに、 `list_tools()` が MCP サーバーへ呼ばれます。リモートサーバーの場合はこれがレイテンシの原因になることがあります。リストを自動でキャッシュするには、 `MCPServerStdio` 、 `MCPServerSse` 、 `MCPServerStreamableHttp` に `cache_tools_list=True` を渡します。ツールリストが変更されないと確信できる場合にのみ設定してください。 -キャッシュを無効化したい場合は、各サーバーの `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 ## エンドツーエンドのコード例 -[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で完全な動作例をご覧いただけます。 +完全な動作例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 ## トレーシング -[トレーシング](./tracing.md) では、次の MCP 操作が自動的にキャプチャされます。 +[トレーシング](./tracing.md) では、 MCP の操作を自動でキャプチャします。対象は次のとおりです: -1. ツール一覧取得のための MCP サーバーへの呼び出し -2. 関数呼び出しに関する MCP 関連情報 +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 9346eabfb..a59447851 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,54 +4,54 @@ search: --- # モデル -Agents SDK には、すぐに使える OpenAI モデルのサポートが 2 種類用意されています。 + Agents SDK には、 OpenAI モデルをすぐに利用できる 2 種類のサポートが用意されています: - **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、[Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 -## 非 OpenAI モデル +## Non-OpenAI モデル -[LiteLLM 連携](./litellm.md) を利用すれば、多くの非 OpenAI モデルを利用できます。まずは litellm の依存関係グループをインストールしてください。 + ほとんどの Non-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 モデルを使用する方法 +### Non-OpenAI モデルを使用するその他の方法 -他の LLM プロバイダーを統合する方法は、さらに 3 つあります([こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にコード例があります)。 + 他の LLM プロバイダーを統合する方法はさらに 3 つあります ( [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) のコード例を参照): 1. [`set_default_openai_client`][agents.set_default_openai_client] - `AsyncOpenAI` のインスタンスをグローバルに LLM クライアントとして使用したい場合に便利です。OpenAI 互換のエンドポイントを持つプロバイダーで `base_url` と `api_key` を設定できるケースに該当します。設定例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 + OpenAI 互換の API エンドポイントを持つ LLM プロバイダーで、 `base_url` と `api_key` を設定できる場合に、 `AsyncOpenAI` インスタンスをアプリ全体で使用する際に便利です。設定例は [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` レベルで設定します。これにより、「この run 内のすべてのエージェントでカスタムモデルプロバイダーを使用する」と指定できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 + `Runner.run` レベルで使用します。「この run 内のすべてのエージェントでカスタムモデルプロバイダーを使う」と宣言できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 3. [`Agent.model`][agents.agent.Agent.model] - 特定の `Agent` インスタンス単位でモデルを指定できます。エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどのモデルを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) が便利です。 + 特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使えます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) をご覧ください。ほとんどのモデルを簡単に利用する方法として [LiteLLM 連携](./litellm.md) があります。 -`platform.openai.com` の API キーを持たない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 + `platform.openai.com` の API キーをお持ちでない場合は、 `set_tracing_disabled()` で tracing を無効化するか、 [別の tracing プロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの例では Chat Completions API/モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、Responses の利用を推奨します。 + これらの例では、ほとんどの LLM プロバイダーが Responses API をまだサポートしていないため、 Chat Completions API/モデルを使用しています。ご利用の LLM プロバイダーが Responses API をサポートしている場合は、 Responses の利用を推奨します。 -## モデルを組み合わせて使用する +## モデルの組み合わせ -1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、仕分けには小さく高速なモデルを、複雑なタスクには大きく高性能なモデルを使うイメージです。[`Agent`][agents.Agent] を設定する際、以下のいずれかでモデルを指定できます。 + 1 つのワークフロー内でエージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分け (triage) には小型で高速なモデルを、複雑なタスクには大型で高性能なモデルを使用するといった具合です。 [`Agent`][agents.Agent] を設定する際、以下のいずれかでモデルを選択できます: -1. モデル名を直接渡す。 -2. 任意のモデル名 + その名前をモデルインスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +1. モデル名を直接指定する。 +2. 任意のモデル名と、それをモデルインスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとに 1 つのモデル形状に統一することを推奨します。両モデルは利用できる機能やツールが異なるためです。モデル形状を混在させる必要がある場合は、使用したい機能が両形状でサポートされていることを確認してください。 + SDK では [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとに 1 種類のモデル形状に統一することを推奨します。両モデル形状は利用できる機能や tools が異なるためです。どうしても混在させる場合は、使用する機能が両形状で利用可能かを必ず確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -84,10 +84,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデル名を直接指定しています。 -2. [`Model`][agents.models.interface.Model] 実装を提供しています。 +1. OpenAI モデル名を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに細かく設定したい場合は、`temperature` などを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡してください。 + エージェントで使用するモデルをさらに設定したい場合は、 [`ModelSettings`][agents.models.interface.ModelSettings] を渡して `temperature` などのオプションパラメーターを指定できます。 ```python from agents import Agent, ModelSettings @@ -100,7 +100,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使う場合は、`user` や `service_tier` などの[その他のオプション](https://platform.openai.com/docs/api-reference/responses/create)も利用できます。トップレベルで指定できない場合は、`extra_args` で渡してください。 + OpenAI の Responses API を使用する場合には、 `user` や `service_tier` など [追加のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、 `extra_args` で渡してください。 ```python from agents import Agent, ModelSettings @@ -118,26 +118,26 @@ english_agent = Agent( ## 他の LLM プロバイダーを使用する際の一般的な問題 -### トレーシングクライアントでの 401 エラー +### Tracing クライアントの 401 エラー -トレーシングに関連するエラーが出る場合、トレースが OpenAI サーバーにアップロードされる設計のため、OpenAI API キーがないことが原因です。解決策は次の 3 通りです。 + tracing 関連のエラーが発生する場合、トレースが OpenAI サーバーにアップロードされるのに OpenAI API キーを持っていないことが原因です。解決策は次の 3 つです: -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] - この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. OpenAI 以外のトレーシングプロセッサーを使用する。詳しくは [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. tracing を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. tracing 用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] + この API キーはトレースのアップロードのみに使用され、 [platform.openai.com](https://platform.openai.com/) から取得したものである必要があります。 +3. 非 OpenAI の trace プロセッサーを使用する。詳しくは [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだ対応していません。そのため 404 などのエラーが発生する場合があります。対処方法は以下の 2 つです。 + SDK はデフォルトで Responses API を使用しますが、ほとんどの LLM プロバイダーはまだ対応していません。その結果、 404 などのエラーが発生することがあります。解決策は次の 2 つです: 1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。 - これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。コード例は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 + これは `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](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 + 一部のモデルプロバイダーは、 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーが発生することがあります: ``` @@ -145,12 +145,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダーの制限で、JSON 出力には対応していても `json_schema` を指定できないために起こります。現在修正に取り組んでいますが、JSON スキーマ出力をサポートしているプロバイダーを選ぶことを推奨します。そうしないと、不正な JSON が返りアプリが頻繁に壊れる可能性があります。 + これは一部プロバイダーの制限で、 JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないためです。現在この問題の解決に取り組んでいますが、 JSON schema 出力をサポートするプロバイダーを利用することを推奨します。そうでない場合、 JSON が不正な形式で返され、アプリが頻繁に壊れる可能性があります。 ## プロバイダーをまたいだモデルの混在 -モデルプロバイダーごとの機能差に注意しないと、エラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search や web search をサポートしていますが、多くの他プロバイダーはこれらをサポートしていません。以下の制限事項にご注意ください。 + モデルプロバイダーごとの機能差を理解していないと、エラーに遭遇することがあります。たとえば、 OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search や web search をサポートしていますが、多くの他社プロバイダーはこれらをサポートしていません。以下の制限に注意してください: -- サポートしていない `tools` を理解しないプロバイダーに送らない +- サポートしていない `tools` を理解できないプロバイダーに送信しない - テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしていないプロバイダーでは、無効な JSON が返ることがあります \ No newline at end of file +- structured JSON outputs をサポートしないプロバイダーでは、無効な JSON が返されることがある点を理解する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index f2a892e15..4f4f0ae41 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM を利用したモデルの使用 +# LiteLLM 経由でのモデル利用 !!! note - LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題を発見された場合は、[GitHub Issues](https://github.com/openai/openai-agents-python/issues) でご報告ください。迅速に対応いたします。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題を見つけた場合は [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応いたします。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK では LiteLLM との連携機能を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ モデルを利用できるライブラリです。Agents SDK では LiteLLM 統合により、任意の AI モデルを使用できます。 ## セットアップ -`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで準備できます。 +`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存グループをインストールすることで導入できます。 ```bash pip install "openai-agents[litellm]" ``` -準備ができたら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +インストール後は、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 ## 例 -以下は動作する完全な例です。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます。 +以下は完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます。 -- `openai/gpt-4.1` をモデルとして指定し、OpenAI API キーを入力 -- `anthropic/claude-3-5-sonnet-20240620` をモデルとして指定し、Anthropic API キーを入力 -- など +- `openai/gpt-4.1` をモデルに指定し、OpenAI API キーを入力 +- `anthropic/claude-3-5-sonnet-20240620` をモデルに指定し、Anthropic API キーを入力 +- そのほか -LiteLLM がサポートするモデルの一覧は、[LiteLLM プロバイダーのドキュメント](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM でサポートされているモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 2167ab880..647102724 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内でエージェントがどのように流れるかを指します。どのエージェントを実行するか、どの順序で実行するか、次に何を行うかをどのように決定するかということです。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でエージェントがどのように流れるかを指します。どのエージェントを、どの順番で実行し、その後の処理をどのように決定するかということです。エージェントをオーケストレーションする方法は大きく 2 つあります。 -1. LLM に意思決定を任せる方法: LLM の知能を使って計画し、推論し、それに基づいて次のステップを決定します。 -2. コードでオーケストレーションする方法: コードによってエージェントのフローを決定します。 +1. LLM に意思決定させる: LLM の知性を利用して計画・推論し、次に取るべきステップを決定します。 +2. コードでオーケストレーションする: コード側でエージェントのフローを決定します。 -これらのパターンを組み合わせることもできます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使うこともできます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はタスクに取り組む方法を自律的に計画し、ツールを使ってアクションを実行してデータを取得し、ハンドオフを使ってサブエージェントにタスクを委任できます。たとえば、リサーチエージェントは次のようなツールを備えることができます。 +エージェントとは、 instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、 LLM は自律的にタスクへの取り組み方を計画し、tools を用いてアクションを実行してデータを取得し、handoffs でサブエージェントへタスクを委譲できます。例えば、リサーチ用エージェントには次のような tools を持たせられます。 -- Web 検索でオンライン情報を取得 -- ファイル検索とリトリーバルで社内データや接続先を検索 +- Web 検索でオンラインの情報を取得 +- ファイル検索および取得で専有データや接続を検索 - コンピュータ操作でコンピュータ上のアクションを実行 - コード実行でデータ分析を行う -- 計画立案やレポート作成などが得意な専門エージェントへのハンドオフ +- 計画やレポート作成に優れた専門エージェントへの handoffs -このパターンはタスクがオープンエンドで、LLM の知能に依存したい場合に最適です。ここで重要なポイントは次のとおりです。 +このパターンはタスクがオープンエンドで、 LLM の知性に頼りたい場合に最適です。ここで重要となる戦略は次のとおりです。 -1. 良いプロンプトに投資すること。利用可能なツール、使用方法、守るべきパラメーターを明確に伝えます。 -2. アプリをモニタリングして改善を重ねること。問題が起こる箇所を確認し、プロンプトを改善します。 -3. エージェントに内省と改善を許可すること。たとえばループで実行し、自己批評させる、あるいはエラーメッセージを提示して改善させるなどです。 -4. 何でもこなす汎用エージェントではなく、単一タスクに長けた専門エージェントを用意すること。 -5. [evals](https://platform.openai.com/docs/guides/evals) へ投資すること。これによりエージェントをトレーニングし、タスク性能を向上させられます。 +1. 良質なプロンプトに投資すること。利用可能な tools、その使い方、および動作すべきパラメーターの範囲を明確に示します。 +2. アプリを監視して継続的に改善すること。不具合が発生した箇所を確認し、プロンプトを繰り返し改善します。 +3. エージェントが自己分析して改善できるようにすること。たとえばループで実行して自己評価させる、あるいはエラーメッセージを提示して改善させます。 +4. 何でもこなす汎用エージェントではなく、 1 つのタスクに特化したエキスパートエージェントを用意すること。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資すること。これによりエージェントを訓練してタスク遂行能力を向上させられます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定論的かつ予測可能になります。一般的なパターンは次のとおりです。 + LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を利用して、コードで検査可能な適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶといった方法です。 -- あるエージェントの出力を次のエージェントの入力に変換して複数のエージェントをチェーンする。ブログ記事作成をリサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善といった一連のステップに分解できます。 -- タスクを実行するエージェントを `while` ループで回し、別のエージェントが評価とフィードバックを行い、評価者が基準を満たしたと判定するまで繰り返す。 -- Python の基本コンポーネントである `asyncio.gather` などを使い、複数のエージェントを並列で実行する。相互依存しない複数タスクがある場合、速度向上に有効です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査できる適切な形式のデータを生成する。たとえばエージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択します。 +- あるエージェントの出力を次のエージェントの入力に変換して、複数のエージェントをチェーンする。ブログ記事の執筆であれば、リサーチ → アウトライン作成 → 本文執筆 → 批評 → 改善といった一連のステップに分解できます。 +- タスクを実行するエージェントを `while` ループで回し、評価とフィードバックを行うエージェントと組み合わせ、評価者が基準を満たしたと判断するまでループを続ける。 +- Python の基本コンポーネントである `asyncio.gather` などを使って複数のエージェントを並列に実行する。互いに依存しない複数タスクがある場合に高速化できます。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数のコード例があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には多くのコード例があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index e3c1d896c..9f64383a4 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -この作業は一度だけでかまいません。 +この操作は 1 回だけでかまいません。 ```bash mkdir my_project @@ -22,23 +22,23 @@ python -m venv .venv source .venv/bin/activate ``` -### Agents SDK のインストール +### Agents SDK のインストール ```bash pip install openai-agents # or `uv add openai-agents`, etc ``` -### OpenAI API キーの設定 +### OpenAI API キーの設定 -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初のエージェントの作成 +## 最初のエージェントを作成する -エージェントは instructions、名前、そして `model_config` などのオプションの config で定義します。 +エージェントは `instructions`、名前、`model_config` などのオプション設定で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## エージェントの追加 +## エージェントをさらに追加する -同じ方法で追加のエージェントを定義できます。`handoff_descriptions` はハンドオフ経路を判断するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## ハンドオフの定義 +## ハンドオフを定義する -各エージェントでは、タスクを進める方法を決定するために選択できる送信先ハンドオフオプションの一覧を定義できます。 +各エージェントに対して、タスクを進める方法を選択できるよう、アウトゴーイングハンドオフの選択肢を一覧として定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ triage_agent = Agent( ) ``` -## エージェントオーケストレーションの実行 +## エージェントオーケストレーションを実行する -ワークフローが実行され、トリアージエージェントが 2 つの専門エージェント間を正しくルーティングするかを確認しましょう。 +ワークフローが実行され、トリアージエージェントが 2 つの専門エージェント間で正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -93,9 +93,9 @@ async def main(): print(result.final_output) ``` -## ガードレールの追加 +## ガードレールを追加する -入力または出力に対して実行するカスタムガードレールを定義できます。 +入力または出力に対して実行されるカスタムガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてをまとめて実行 +## すべてを組み合わせる -ハンドオフと入力ガードレールを使用しながら、ワークフロー全体をまとめて実行してみましょう。 +ハンドオフと入力ガードレールを使用して、ワークフロー全体をまとめて実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの表示 +## トレースを確認する -エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してエージェント実行のトレースを表示します。 +エージェント実行中に何が起こったかを確認するには、OpenAI ダッシュボードの [Trace viewer](https://platform.openai.com/traces) に移動してエージェント実行のトレースを閲覧してください。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう。 +より複雑なエージェントフローの構築方法を学びましょう: -- [エージェント](agents.md) の設定方法 -- [エージェントの実行](running_agents.md) -- [tools](tools.md)、[guardrails](guardrails.md) および [models](models/index.md) について学ぶ \ No newline at end of file +- [Agents](agents.md) の設定方法を学ぶ。 +- [running agents](running_agents.md) について学ぶ。 +- [tools](tools.md)、[guardrails](guardrails.md)、[models](models/index.md) について学ぶ。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index 4360ba39e..d1a7a90ab 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 "Beta feature" -Realtime エージェントはベータ版です。実装改善に伴い、互換性が失われる可能性があります。 +Realtime エージェントはベータ版です。実装を改善する過程で破壊的変更が入る可能性があります。 ## 概要 -Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する会話フローを実現します。OpenAI の Realtime API との永続接続を維持し、低遅延かつ自然な音声対話を可能にし、割り込みにもスムーズに対応します。 +Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、リアルタイム音声で応答できる会話フローを実現します。OpenAI の Realtime API との永続接続を維持し、低レイテンシで自然な音声対話と、割り込みへのスムーズな対応が可能です。 ## アーキテクチャ ### 主要コンポーネント -Realtime システムは次の主要コンポーネントで構成されます。 +realtime システムは次の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得します。 -- **RealtimeSession**: 1 回の対話セッション。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデル インターフェース (通常は OpenAI の WebSocket 実装)。 +- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出すことでセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッションです。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース(通常は OpenAI の WebSocket 実装)です。 ### セッションフロー -典型的な realtime セッションは次の流れで進行します。 +一般的な realtime セッションの流れは次のとおりです。 -1. **RealtimeAgent** を instructions、tools、handoffs と共に作成する -2. エージェントと設定オプションを用いて **RealtimeRunner** を準備する -3. `await runner.run()` で **セッションを開始** し、RealtimeSession を取得する -4. `send_audio()` または `send_message()` で **音声またはテキストを送信** する -5. セッションをイテレートして **イベントを監視** する — 音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーなど -6. ユーザーが話し始めたら **割り込みを処理** し、現在の音声生成を自動で停止させる +1. instructions、tools、handoffs を設定して **RealtimeAgent** を作成します。 +2. そのエージェントと設定オプションを使って **RealtimeRunner** をセットアップします。 +3. `await runner.run()` で **セッションを開始** し、`RealtimeSession` を取得します。 +4. `send_audio()` または `send_message()` で **音声またはテキストメッセージを送信** します。 +5. セッションをイテレートして **イベントをリッスン** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザーがエージェントの発話を遮った場合に **割り込みを処理** します。割り込みが発生すると現在の音声生成は自動的に停止します。 セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は通常の Agent クラスと似ていますが、いくつかの重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスとほぼ同じですが、いくつかの重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] をご覧ください。 -主な違い: +通常のエージェントとの主な違い: -- モデル選択はエージェントではなくセッションレベルで設定します。 -- structured outputs (`outputType`) はサポートされません。 -- 音声はエージェント単位で設定できますが、最初のエージェントが発話した後は変更できません。 -- tools、handoffs、instructions などその他の機能は同じ方法で動作します。 +- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 +- structured outputs (`outputType`) はサポートされていません。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、handoffs、instructions などのその他の機能は同じ方法で機能します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの挙動を制御できます。モデル名 (例: `gpt-4o-realtime-preview`)、音声 (alloy、echo、fable、onyx、nova、shimmer)、対応モダリティ (text/audio) を指定可能です。入出力の音声フォーマットは両方とも設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名(例: `gpt-4o-realtime-preview`)、音声選択(alloy、echo、fable、onyx、nova、shimmer)、対応モダリティ(text と/または audio)を指定できます。入出力の音声フォーマットはどちらも PCM16 がデフォルトです。 -### オーディオ設定 +### 音声設定 -オーディオ設定では、音声入力と出力の扱いを制御します。Whisper などのモデルで入力音声を文字起こししたり、言語を指定したり、専門用語の認識精度を高める transcription prompt を提供できます。ターン検出では、音声アクティビティ検出のしきい値、無音時間、前後のパディングなどを調整し、エージェントが発話を開始・終了すべきタイミングを制御します。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使用した入力音声の文字起こし、言語の指定、ドメイン固有用語の精度を高めるための文字起こしプロンプトが設定可能です。ターン検出設定では、音声検出閾値、無音時間、検出された音声周辺のパディングなどを調整し、エージェントがいつ応答を開始・終了すべきかを決定します。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様、realtime エージェントでも会話中に実行される function tools を利用できます。 +通常のエージェントと同様に、realtime エージェントは会話中に実行される function tools をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフを使用すると、会話を専門化されたエージェント間で引き継げます。 +ハンドオフを使用すると、会話を専門エージェント間で引き継ぐことができます。 ```python from agents.realtime import realtime_handoff @@ -119,40 +119,40 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーミングします。セッションオブジェクトをイテレートしてイベントを受け取ります。主なイベントは以下のとおりです。 +セッションはイベントをストリーミングします。セッションオブジェクトをイテレートしてイベントをリッスンしてください。イベントには音声出力チャンク、文字起こし結果、ツール実行開始と終了、エージェントのハンドオフ、エラーが含まれます。主に処理すべきイベントは次のとおりです。 -- **audio**: エージェントの応答としての raw 音声データ -- **audio_end**: エージェントの発話が終了 -- **audio_interrupted**: ユーザーがエージェントを割り込み -- **tool_start/tool_end**: ツール実行の開始・終了 -- **handoff**: エージェント間のハンドオフ発生 -- **error**: 処理中にエラー発生 +- **audio**: エージェントの応答からの raw 音声データ +- **audio_end**: エージェントが発話を完了 +- **audio_interrupted**: ユーザーがエージェントを割り込み +- **tool_start/tool_end**: ツール実行ライフサイクル +- **handoff**: エージェントハンドオフが発生 +- **error**: 処理中にエラーが発生 -詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +完全なイベント詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -Realtime エージェントでは出力ガードレールのみがサポートされています。パフォーマンス低下を防ぐため、ガードレールはデバウンスされ、一定間隔 (デフォルトは 100 文字) ごとに評価されます。 +realtime エージェントでは出力ガードレールのみサポートされています。ガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために定期的(全単語ではなく)に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレールが発動すると `guardrail_tripped` イベントが生成され、エージェントの現在の返答を中断する場合があります。デバウンスにより、安全性とリアルタイム性能のバランスを取っています。テキストエージェントと異なり、ガードレール発動時に Exception はスローされません。 +ガードレールがトリガーされると `guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。このデバウンス動作により、安全性とリアルタイム性能のバランスが取れます。テキストエージェントとは異なり、realtime エージェントはガードレールがトリップしても Exception を送出しません。 -## オーディオ処理 +## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] で音声を、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] でテキストを送信できます。 +音声を送信するには [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio]、テキストを送信するには [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。 -音声出力を処理するには `audio` イベントを受信し、お好みのオーディオライブラリで再生してください。ユーザーが割り込んだ際には `audio_interrupted` イベントを監視し、即座に再生を停止してキューに残る音声をクリアしてください。 +音声出力を再生するには `audio` イベントをリッスンし、好みの音声ライブラリで音声データを再生してください。ユーザーがエージェントを割り込んだ際には `audio_interrupted` イベントをリッスンしてすぐに再生を停止し、キューにある音声をクリアするようにしてください。 -## モデルへの直接アクセス +## 直接モデルアクセス -カスタムリスナーの追加や高度な操作を行うため、基盤モデルに直接アクセスできます。 +基盤となるモデルにアクセスしてカスタムリスナーを追加したり、高度な操作を行うことができます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、低レベルで接続を制御したい高度なユースケース向けに [`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースを直接利用できます。 +これにより、より低レベルで接続を制御する必要がある高度なユースケース向けに [`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 ## コード例 -完全な動作例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI あり・なしのデモが含まれています。 \ No newline at end of file +完全な動作例は [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI コンポーネントの有無にかかわらずデモを確認できます。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 490dd41d0..41b1ce511 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,27 +4,26 @@ search: --- # クイックスタート -OpenAI の Realtime API を使用すると、リアルタイム エージェントを通じて AI エージェントとの音声会話が可能になります。 -本ガイドでは、初めてのリアルタイム音声 エージェントを作成する手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を実現します。本ガイドでは、初めての Realtime 音声エージェントを作成する手順を説明します。 !!! warning "ベータ機能" -リアルタイム エージェントは現在ベータ版です。実装の改善に伴い破壊的変更が発生する可能性がありますのでご注意ください。 +Realtime エージェントは現在ベータ版です。実装の改善に伴い、非互換の変更が発生する可能性があります。 ## 前提条件 - Python 3.9 以上 - OpenAI API キー -- OpenAI Agents SDK の基本的な操作経験 +- OpenAI Agents SDK の基本的な知識 ## インストール -まだインストールしていない場合は、OpenAI Agents SDK をインストールします: +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## 最初のリアルタイム エージェントの作成 +## 初めての Realtime エージェントの作成 ### 1. 必要なコンポーネントをインポートする @@ -33,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. リアルタイム エージェントを作成する +### 2. Realtime エージェントを作成する ```python agent = RealtimeAgent( @@ -42,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. ランナーを設定する +### 3. Runner をセットアップする ```python runner = RealtimeRunner( @@ -82,7 +81,7 @@ asyncio.run(main()) ## 完全なコード例 -こちらが動作する完全なコード例です: +以下は動作する完全なコード例です: ```python import asyncio @@ -140,7 +139,7 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイム モデルから選択します (例: `gpt-4o-realtime-preview`) +- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-4o-realtime-preview`) - `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) - `modalities`: テキストおよび / またはオーディオを有効にします (`["text", "audio"]`) @@ -148,32 +147,32 @@ if __name__ == "__main__": - `input_audio_format`: 入力オーディオの形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) - `output_audio_format`: 出力オーディオの形式 -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_transcription`: 音声文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声アクティビティのしきい値 (0.0-1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前に付与するオーディオのパディング +- `type`: 検出方式 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動しきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了と判断する無音時間 +- `prefix_padding_ms`: 発話前のオーディオパディング ## 次のステップ -- [リアルタイム エージェントについて詳しく学ぶ](guide.md) -- リポジトリの [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作するコード例を参照してください -- エージェントにツールを追加する +- [Realtime エージェントについてさらに学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダにある実動作する code examples をご覧ください +- エージェントに tools を追加する - エージェント間のハンドオフを実装する -- セーフティ用のガードレールを設定する +- 安全のためのガードレールを設定する ## 認証 -環境変数に OpenAI API キーが設定されていることを確認してください: +OpenAI API キーが環境変数に設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -また、セッション作成時に直接渡すこともできます: +または、セッション作成時に直接渡すこともできます: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index b0ce16ff5..13905d471 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` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承しているクラスでは、これらのパラメーターを実装に追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承しているクラスには、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 13e7cd0bd..0644dc462 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -SDK は対話型テストをすばやく行うために `run_demo_loop` を提供します。 +SDK は、ターミナル上でエージェントの挙動を素早くインタラクティブにテストできる `run_demo_loop` を提供しています。 ```python import asyncio @@ -18,4 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループ内でユーザー入力を促し、各ターン間で会話履歴を保持します。デフォルトでは生成されたモデル出力をストリーミングします。ループを終了するには `quit` または `exit` と入力するか、`Ctrl-D` を押してください。 \ No newline at end of file +`run_demo_loop` はループでユーザー入力を促し、ターン間の会話履歴を保持します。デフォルトでは、生成されたとおりにモデルの出力をストリーミングします。上記の例を実行すると、 run_demo_loop がインタラクティブなチャット セッションを開始します。このセッションではユーザー入力を継続的に受け取り、ターン間の全会話履歴を記憶するため、エージェントはすでに話題に上がった内容を理解できます。また、エージェントの応答を生成と同時にリアルタイムで自動ストリーミングします。 + +チャット セッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボード ショートカットを使用してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index afd86642d..36f67c2cb 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` を呼び出した場合 +- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] +- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] -これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報のほとんどはそこに格納されています。 +どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されます。内容は次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行された エージェント の最終出力が入ります。これは次のいずれかです: -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト +- 最後の エージェント に `output_type` が定義されていない場合は `str` +- エージェント に `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフが発生すると、どの Agent でも最後のエージェントになり得るため、静的に型を決定できません。その結果、取り得る出力型の集合を静的に判定することができないのです。 + `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` を保存しておけば、次回ユーザーがメッセージを送ったときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行された エージェント が格納されます。アプリケーションによっては、これは次回の ユーザー 入力時に非常に便利です。たとえば、一次受付の振り分け エージェント が言語別の エージェント にハンドオフ する場合、最後の エージェント を保存しておき、次回 ユーザー からメッセージが来た際に再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] であり、raw アイテムをラップしています。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。各アイテムは [`RunItem`][agents.items.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 が handoff ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフ が発生したことを示します。raw アイテムは handoff ツール呼び出しへのツール応答です。このアイテムからソース / ターゲット エージェント も取得できます。 +- [`ToolCallItem`][agents.items.ToolCallItem]: LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]: ツールが呼び出されたことを示します。raw アイテムはツールの応答です。また、このアイテムからツール出力にアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem]: LLM からの reasoning アイテムを示します。raw アイテムは生成された reasoning です。 ## その他の情報 ### ガードレール結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] には、ガードレールの結果が含まれます (存在する場合)。ログや保存に役立つ情報が含まれることがあるため、これらを参照できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレール の結果が格納されます (存在する場合)。ガードレール結果には記録や保存を行いたい有用な情報が含まれることがあるため、これらを参照できるようにしています。 ### raw レスポンス -[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が格納されています。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が入ります。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が格納されています。通常は不要ですが、必要に応じて参照できます。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が格納されています。多くの場合は不要ですが、必要に応じて参照できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 8a919eda1..f88ede3f7 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,14 +4,14 @@ search: --- # エージェントの実行 -`Runner` クラスを使って エージェント を実行できます。方法は 3 つあります: +エージェントは [`Runner`][agents.run.Runner] クラスを介して実行できます。方法は次の 3 つです。 1. [`Runner.run()`][agents.run.Runner.run] - 非同期で実行され、`RunResult` を返します。 + 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync] - 同期メソッドで、内部的には `.run()` を呼び出します。 + 同期メソッドで、内部的には `.run()` を呼び出します。 3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] - 非同期で実行され、`RunResultStreaming` を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのまま ストリーミング します。 + 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。ストリーミング モードで LLM を呼び出し、受信イベントを逐次ストリームします。 ```python from agents import Agent, Runner @@ -26,55 +26,58 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) を参照してください。 +詳細は [results ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の `run` メソッドを使用するときは、開始 エージェント と入力を渡します。入力は文字列(ユーザーメッセージと見なされます)か、OpenAI Responses API のアイテムのリストのいずれかです。 +`Runner` の run メソッドを使う際、開始エージェントと入力を渡します。入力は文字列(ユーザー メッセージと見なされます)または入力アイテムのリスト(OpenAI Responses API のアイテム)です。 -ランナーは次のループを実行します: +Runner は次のループを実行します。 -1. 現在の エージェント と入力で LLM を呼び出します。 +1. 現在のエージェントと入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 - 2. LLM が ハンドオフ を行った場合、現在の エージェント と入力を更新し、ループを再実行します。 - 3. LLM が ツール呼び出し を生成した場合、それらを実行し結果を追加して、ループを再実行します。 -3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 1. `final_output` が返された場合、ループを終了し結果を返します。 + 2. ハンドオフが行われた場合、現在のエージェントと入力を更新してループを再実行します。 + 3. ツール呼び出しが生成された場合、それらを実行し結果を追加してループを再実行します。 +3. 渡した `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - 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]: 各 エージェント の `model` 設定に関係なく、グローバルで使用する LLM モデルを指定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決する モデルプロバイダー で、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルで `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力/出力 ガードレール のリスト。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフ に入力フィルターが指定されていない場合に適用されるグローバル入力フィルター。新しい エージェント に送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] を参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にします。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` を設定することを推奨します。`group_id` は複数の実行にわたるトレースをリンクするための任意フィールドです。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 +- [`model`][agents.run.RunConfig.model]: 各エージェントの `model` 設定に関係なく、グローバルで使用する LLM モデルを指定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデル プロバイダー。デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。例として、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力/出力ガードレールのリスト。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 既に設定されていない場合にすべてのハンドオフへ適用されるグローバル入力フィルター。新しいエージェントへ渡される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] を参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体で [トレーシング](tracing.md) を無効化します。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに LLM やツール呼び出しの入出力など、機微情報を含めるかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: トレーシング用のワークフロー名、トレース ID、グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は複数実行に跨るトレースを関連付ける任意フィールドです。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 ## 会話/チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上の エージェント が実行され(つまり 1 回以上の LLM 呼び出しが発生し)、チャット会話上の 1 つの論理ターンを表します。例: +いずれの run メソッドを呼び出しても、1 つ以上のエージェント(ひいては 1 つ以上の LLM 呼び出し)が実行されますが、チャット会話における 1 つの論理的ターンを表します。例: -1. ユーザーターン: ユーザーがテキストを入力 -2. Runner 実行: 最初の エージェント が LLM を呼び出し、ツールを実行し、別の エージェント にハンドオフ。2 番目の エージェント がさらにツールを実行し、最終出力を生成。 +1. ユーザー ターン: ユーザーがテキストを入力 +2. Runner 実行: + - 第 1 エージェントが LLM を呼び出し、ツールを実行 + - 第 2 エージェントへハンドオフ + - 第 2 エージェントがさらにツールを実行し、出力を生成 -エージェント実行の終了時に、ユーザーへ何を表示するかを選択できます。たとえば、エージェント が生成したすべての新しいアイテムを表示するか、最終出力のみを表示するかです。どちらの場合も、ユーザーがフォローアップ質問を行えば、再度 run メソッドを呼び出せます。 +エージェント実行の最後にユーザーへ何を表示するかは自由です。すべての新しいアイテムを表示しても、最終出力だけを表示しても構いません。ユーザーがフォローアップ質問をしたら、再度 run メソッドを呼び出します。 ### 手動での会話管理 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して、次のターンの入力を取得し、会話履歴を手動で管理できます: +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドで、次のターン用の入力を取得し会話履歴を手動管理できます。 ```python async def main(): @@ -96,7 +99,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使用すると `.to_input_list()` を手動で呼び出さずに会話履歴を自動管理できます: +より簡単な方法として、[Sessions](sessions.md) を使用して `.to_input_list()` を呼び出すことなく会話履歴を自動処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -119,26 +122,31 @@ async def main(): # California ``` -Sessions は自動で以下を行います: +Sessions は自動で以下を行います。 -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- 異なる session ID ごとに個別の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- セッション ID ごとに個別の会話を維持 -詳細は [Sessions のドキュメント](sessions.md) を参照してください。 +詳細は [Sessions ドキュメント](sessions.md) を参照してください。 -## 長時間実行エージェント & 人間介在 +## 長時間実行エージェントと Human-in-the-Loop -Agents SDK は [Temporal](https://temporal.io/) と統合して、耐久性のある長時間実行ワークフロー(人間介在タスクを含む)を実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [こちらの動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を、ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) をご覧ください。 +Agents SDK は [Temporal](https://temporal.io/) との連携により、Human-in-the-Loop を含む耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で視聴でき、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)にあります。 ## 例外 -SDK は特定の状況で例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです: - -- [`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 形式が不正: ツール呼び出しや直接出力で JSON が壊れている場合(特に `output_type` が指定されているとき)。 - - 予期しないツール関連エラー: モデルがツールを想定どおりに使用しなかった場合。 -- [`UserError`][agents.exceptions.UserError]: SDK を使用する際に、あなた(SDK を利用する開発者)が誤った実装や不正な設定を行った場合に送出されます。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力ガードレール、出力ガードレールの条件を満たしたときに送出されます。入力ガードレールは処理前のメッセージを、出力ガードレールは最終応答をチェックします。 \ No newline at end of file +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 を使用する際の実装ミス、無効な設定、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 efa6b1ef8..6da492e05 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()` を手動で扱う必要がありません。 -セッションは特定のセッションに対して会話履歴を保存し、エージェントが明示的なメモリー管理なしでコンテキストを維持できるようにします。これはチャットアプリケーションやマルチターン会話で、エージェントに以前のやり取りを覚えさせたい場合に特に便利です。 +セッションは特定のセッションに対して会話履歴を保存し、明示的なメモリー管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに前回のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話を構築する際に特に便利です。 ## クイックスタート @@ -47,21 +47,21 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 動作概要 +## 仕組み -セッションメモリーが有効な場合: +セッションメモリーを有効にすると、以下のように動作します。 -1. **各実行前**: ランナーがそのセッションの会話履歴を自動で取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成された新しいアイテム (ユーザー入力、アシスタントのレスポンス、ツール呼び出しなど) が自動でセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションで後続の実行を行うたびに、完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 +1. **各実行前**: ランナーがセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **各実行後**: 実行中に生成されたすべての新しいアイテム(ユーザー入力、アシスタントの応答、ツール呼び出しなど)が自動的にセッションに保存されます。 +3. **コンテキスト保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出して会話状態を管理する必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 ## メモリー操作 ### 基本操作 -セッションは会話履歴を管理するための複数の操作をサポートしています: +Sessions では、会話履歴を管理するための複数の操作がサポートされています。 ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### pop_item を使った修正 +### 修正のための pop_item の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたい場合に特に便利です: +`pop_item` メソッドは、会話内の最後のアイテムを取り消したり修正したりしたい場合に特に便利です。 ```python from agents import Agent, Runner, SQLiteSession @@ -170,7 +170,7 @@ result2 = await Runner.run( ## カスタムメモリー実装 -[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリーを実装できます: +独自のセッションメモリーを実装する場合は、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します。 ```python from agents.memory import Session @@ -216,17 +216,17 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすい意味のあるセッション ID を使用してください: +会話を整理しやすい意味のあるセッション ID を使用してください。 -- ユーザー単位: `"user_12345"` -- スレッド単位: `"thread_abc123"` -- コンテキスト単位: `"support_ticket_456"` +- User-based: `"user_12345"` +- Thread-based: `"thread_abc123"` +- Context-based: `"support_ticket_456"` ### メモリー永続化 -- 一時的な会話にはインメモリー SQLite (`SQLiteSession("session_id")`) を使用します -- 永続的な会話にはファイルベース SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用します -- 本番環境ではカスタムセッションバックエンド (Redis、PostgreSQL など) の実装を検討してください +- 一時的な会話にはインメモリー SQLite (`SQLiteSession("session_id")`) を使用 +- 永続的な会話にはファイルベース SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用 +- 本番環境では独自のセッションバックエンド(Redis、PostgreSQL など)の実装を検討してください ### セッション管理 @@ -254,7 +254,7 @@ result2 = await Runner.run( ## 完全なコード例 -以下はセッションメモリーが動作する完全なコード例です: +以下は、セッションメモリーが実際に動作する完全なコード例です。 ```python import asyncio @@ -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 +- [`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 fdff7ce31..548ba1662 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,13 +4,13 @@ search: --- # ストリーミング -ストリーミングを使用すると、エージェントの実行が進行するにつれて発生する更新を購読できます。これにより、エンドユーザーに進捗状況や途中の応答を表示する際に役立ちます。 +ストリーミングを使用すると、エージェントの実行が進行するにつれて更新を購読できます。これはエンドユーザーに進行状況の更新や部分的なレスポンスを表示する際に便利です。 -ストリーミングを行うには、 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、非同期ストリームとして [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトを取得できます。これらのオブジェクトについては後述します。 +ストリーミングを行うには、 `Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。続いて `result.stream_events()` を呼び出すと、下記で説明する `StreamEvent` オブジェクトの非同期ストリームを取得できます。 ## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、 LLM から直接渡される raw イベントです。これらは OpenAI Responses API のフォーマットであり、各イベントには type( `response.created`、 `response.output_text.delta` など)と data が含まれます。レスポンスメッセージを生成と同時にユーザーへストリーム配信したい場合に便利です。 +`RawResponsesStreamEvent` は、LLM から直接渡される raw イベントです。OpenAI Responses API 形式で提供されるため、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。生成されたレスポンスメッセージを即座にユーザーへストリーミングしたい場合に便利です。 例えば、以下のコードは LLM が生成したテキストをトークンごとに出力します。 @@ -37,9 +37,9 @@ if __name__ == "__main__": ## Run item イベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせてくれます。これにより、トークン単位ではなく 「メッセージが生成された」「ツールが実行された」 といった粒度で進捗を通知できます。同様に、 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] はハンドオフの結果などで現在のエージェントが変化した際に更新を受け取れます。 +`RunItemStreamEvent` は、より高レベルのイベントで、アイテムが完全に生成されたことを通知します。これにより、トークン単位ではなく「メッセージ生成完了」や「ツール実行完了」といった粒度で進行状況をプッシュできます。同様に、`AgentUpdatedStreamEvent` はハンドオフなどの結果として現在のエージェントが変更された際に更新を送ります。 -例えば、以下のコードは raw イベントを無視し、ユーザーへ更新のみをストリーム配信します。 +例えば、次のコードは raw イベントを無視し、ユーザーへ更新をストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 686e56ebf..5ac3a43ae 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールを利用することで、エージェントはデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作などのアクションを実行できます。Agents SDK には 3 つのツール クラスがあります: +ツールを使用すると、エージェントはデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作などのアクションを実行できます。Agents SDK には 3 種類のツールがあります。 -- Hosted ツール: これらは LLM サーバー上で AI モデルと並行して実行されます。OpenAI は retrieval、Web 検索、および コンピュータ操作 を Hosted ツールとして提供しています。 -- Function calling: 任意の Python 関数をツールとして利用できます。 -- Agents as tools: エージェントをツールとして扱うことで、ハンドオフせずに他のエージェントを呼び出せます。 +- ホスト型ツール: これらは LLM サーバー上で AI モデルと一緒に実行されます。OpenAI は retrieval、Web 検索、コンピュータ操作をホスト型ツールとして提供しています。 +- 関数ツール: 任意の Python 関数をツールとして利用できます。 +- ツールとしてのエージェント: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せます。 -## ホステッドツール +## ホスト型ツール -[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合、OpenAI はいくつかの組み込みツールを提供しています: +[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合、OpenAI はいくつかの組み込みツールを提供しています。 -- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントが Web 検索 を行えるようにします。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI Vector Stores から情報を取得できます。 +- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 - [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 +- [`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` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、`pydantic` でスキーマを生成しています。 +Python の `inspect` モジュールで関数シグネチャを抽出し、docstring 解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ生成には `pydantic` を使用しています。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、同期・非同期いずれの関数も利用可能です。 -2. Docstring が存在する場合、ツール全体と各引数の説明に利用されます。 -3. 関数はオプションで `context`(先頭の引数である必要があります)を受け取れます。また、ツール名や説明、docstring スタイルなどを上書き設定できます。 -4. デコレートした関数を tools のリストに渡せば使用できます。 +1. 関数の引数には任意の Python 型を使用でき、同期関数・非同期関数のどちらでも構いません。 +2. docstring が存在する場合、ツールおよび引数の説明として利用されます。 +3. 関数は任意で `context`(先頭の引数)を受け取れます。また、ツール名や説明、docstring スタイルなどの上書き設定も可能です。 +4. デコレート済みの関数をツール一覧に渡すだけで使用できます。 -??? 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 関数 +- `params_json_schema`: 引数の JSON スキーマ +- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列形式の引数を受け取り、ツール出力を文字列で返す非同期関数 ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを自動解析してツールのスキーマを生成し、docstring からツールおよび個々の引数の説明を抽出します。注意点は次のとおりです: +前述のとおり、ツール用スキーマを関数シグネチャから自動で抽出し、docstring からツールや各引数の説明を取得します。ポイントは次のとおりです。 -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数型を判定し、Pydantic モデルを動的に生成してスキーマを構築します。Python の基本型、Pydantic モデル、TypedDict など大半の型をサポートしています。 -2. Docstring の解析には `griffe` を使用します。対応フォーマットは `google`、`sphinx`、`numpy` です。フォーマット判定はベストエフォートで行いますが、`function_tool` 呼び出し時に明示的に指定することも可能です。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 +1. `inspect` モジュールでシグネチャを解析し、型アノテーションから引数の型を判定して Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など大半の型をサポートします。 +2. docstring 解析には `griffe` を使用します。対応フォーマットは `google`、`sphinx`、`numpy` です。フォーマットは自動推定しますが、`function_tool` 呼び出し時に明示的に指定もできます。`use_docstring_info` を `False` に設定すれば解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## エージェントをツールとして使用 +## ツールとしてのエージェント -ワークフローによっては、ハンドオフせずに中央エージェントが複数の専門エージェントをオーケストレートしたい場合があります。そのようなときは、エージェントをツールとしてモデル化できます。 +ワークフローによっては、ハンドオフせずに中央のエージェントが複数の専門エージェントをオーケストレーションしたい場合があります。その際、エージェントをツールとしてモデル化できます。 ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツールエージェントのカスタマイズ +### ツール化エージェントのカスタマイズ -`agent.as_tool` 関数はエージェントを簡単にツール化するための便利メソッドです。ただし、すべての設定をサポートしているわけではなく、たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください: +`agent.as_tool` はエージェントを簡単にツール化するためのヘルパーです。ただしすべての設定をサポートするわけではなく、たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください。 ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、ツールエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば次のようなケースです: +場合によっては、ツール化したエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば以下のようなケースです。 -- サブエージェントのチャット履歴から特定の情報(例: JSON ペイロード)を抽出したい -- エージェントの最終回答を別形式に変換したい(例: Markdown をプレーンテキストや CSV に変換) -- 出力を検証し、不足や不正な場合にフォールバック値を返したい +- サブエージェントのチャット履歴から特定情報(例: JSON ペイロード)のみを抽出する +- エージェントの最終回答を変換・再フォーマットする(例: Markdown をプレーンテキストや CSV に変換) +- 出力を検証し、不足または不正な場合にフォールバック値を返す -これを行うには、`as_tool` メソッドに `custom_output_extractor` 引数を指定します: +これを行うには、`as_tool` メソッドに `custom_output_extractor` 引数を渡します。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,10 +317,10 @@ json_tool = data_agent.as_tool( ## 関数ツールでのエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡すことができます。これはツール呼び出しがクラッシュした際に LLM へエラー応答を返す関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これはツール呼び出しがクラッシュした場合に LLM へ返されるエラー応答を生成する関数です。 -- 何も渡さない場合、デフォルトで `default_tool_error_function` が実行され、エラーが発生したことを LLM に通知します。 -- 独自のエラー関数を渡すと、それが実行されて LLM へ返されます。 -- 明示的に `None` を渡すと、ツール呼び出しエラーが再スローされ、呼び出し側で処理できます。このとき、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などが発生し得ます。 +- 何も渡さなかった場合は、`default_tool_error_function` が実行され、LLM にエラーが発生したことを通知します。 +- 独自のエラー関数を渡すと、それが実行され、その応答が LLM へ送信されます。 +- 明示的に `None` を渡すと、ツール呼び出し時のエラーは再スローされます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などになります。 -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 8726eaa61..f958494df 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生する LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで、イベントの詳細な記録を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を利用すると、開発時および本番環境でワークフローをデバッグ、可視化、モニタリングできます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで、イベントの包括的な記録を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note トレーシングはデフォルトで有効になっています。無効にする方法は 2 つあります。 - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する - 2. 1 回の実行に対してのみ、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化する + 2. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行でトレーシングを無効化する -***OpenAI の API を ZDR (Zero Data Retention) ポリシーで利用している組織では、トレーシングを利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングを利用できません。*** -## Traces と Spans +## トレースとスパン -- **Trace** は 1 つの「ワークフロー」のエンドツーエンド操作を表します。Trace は次のプロパティを持ちます。 - - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」。 - - `trace_id`: Trace の一意 ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 任意のグループ ID。同じ会話からの複数 Trace を関連付けるために使用します。たとえばチャットスレッド ID など。 - - `disabled`: `True` の場合、その Trace は記録されません。 - - `metadata`: Trace に付与する任意のメタデータ。 -- **Span** は開始時刻と終了時刻を持つ操作を表します。Span には次があります。 +- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成されます。トレースには以下のプロパティがあります。 + - `workflow_name`:論理的なワークフローまたはアプリ名。例: "Code generation" や "Customer service" + - `trace_id`:トレースの一意 ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`:任意のグループ ID。同じ会話からの複数トレースを関連付けるために使用します。例としてチャットスレッド ID など。 + - `disabled`:`True` の場合、トレースは記録されません。 + - `metadata`:トレースの任意メタデータ。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには以下があります。 - `started_at` と `ended_at` タイムスタンプ - - 所属する Trace を示す `trace_id` - - 親 Span を指す `parent_id` (存在する場合) - - Span の情報を含む `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など。 + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id`(存在する場合) + - スパンに関する情報を持つ `span_data`。例えば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など。 ## デフォルトのトレーシング デフォルトでは、SDK は以下をトレースします。 -- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます -- エージェントが実行されるたびに `agent_span()` でラップ -- LLM 生成は `generation_span()` でラップ -- 関数ツール呼び出しは `function_span()` でラップ -- ガードレールは `guardrail_span()` でラップ -- ハンドオフは `handoff_span()` でラップ -- 音声入力 (speech-to-text) は `transcription_span()` でラップ -- 音声出力 (text-to-speech) は `speech_span()` でラップ -- 関連音声 Span は `speech_group_span()` の下に入る場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。 +- エージェントが実行されるたびに `agent_span()` でラップされます。 +- LLM 生成は `generation_span()` でラップされます。 +- 関数ツール呼び出しはそれぞれ `function_span()` でラップされます。 +- ガードレールは `guardrail_span()` でラップされます。 +- ハンドオフは `handoff_span()` でラップされます。 +- 音声入力 (speech-to-text) は `transcription_span()` でラップされます。 +- 音声出力 (text-to-speech) は `speech_span()` でラップされます。 +- 関連する音声スパンは `speech_group_span()` の下に配置される場合があります。 -Trace 名はデフォルトで「Agent workflow」です。`trace` を使用してこの名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを構成できます。 +トレース名はデフォルトで "Agent workflow" です。`trace` を使用して名前を設定するか、 [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、別の宛先へ Trace を送信することもできます (置き換えや追加送信)。 +さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定して、別の送信先にトレースをプッシュする(置き換えまたは追加送信先として)ことも可能です。 -## 高レベル Trace +## 高レベルのトレース -複数回の `run()` 呼び出しを 1 つの Trace にまとめたい場合は、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,48 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` の 2 回の呼び出しが `with trace()` に包まれているため、個々の実行は 2 つの Trace を作成するのではなく、1 つの大きな Trace の一部になります。 +1. `with trace()` で 2 回の `Runner.run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成せず、全体トレースの一部になります。 -## Trace の作成 +## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使って Trace を作成できます。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] を手動で呼び出す。 -現在の Trace は Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されています。これにより自動的に並行処理に対応します。Trace を手動で開始・終了する場合は、`start()`/`finish()` に `mark_as_current` と `reset_current` を渡して現在の Trace を更新してください。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。これにより並行処理でも自動的に機能します。トレースを手動で開始・終了する場合は、`start()` と `finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新する必要があります。 -## Span の作成 +## スパンの作成 -各種 [`*_span()`][agents.tracing.create] メソッドで Span を作成できます。通常、Span を手動で作成する必要はありません。カスタム情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も利用できます。 +各種 [`*_span()`][agents.tracing.create] メソッドでスパンを作成できますが、通常は手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] が用意されています。 -Span は自動的に現在の Trace の一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されている最も近い現在の Span の下にネストされます。 +スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される最も近い現在のスパンの下にネストされます。 ## 機微データ -一部の Span では機微データが記録される可能性があります。 +一部のスパンは機微データを取得する可能性があります。 -`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] でデータ取得を無効化できます。 -同様に、Audio Span にはデフォルトで入出力音声の 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] を生成し、Trace を作成します。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を構成し、これが Span と Trace をバッチ送信で [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に渡し、OpenAI バックエンドへエクスポートします。 +- 初期化時にグローバル [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレース生成を担当します。 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。エクスポーターはバッチで OpenAI バックエンドへスパンとトレースをエクスポートします。 -デフォルト設定をカスタマイズして別のバックエンドへ送信したり、エクスポーターの動作を変更したりするには次の 2 つの方法があります。 +デフォルト設定をカスタマイズし、別のバックエンドへ送信したり、エクスポーター動作を変更したりするには 2 つの方法があります。 -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] - 既存の送信に **追加** する形で Trace プロセッサーを登録できます。これにより、OpenAI バックエンドへの送信に加えて独自処理を実行可能です。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] - デフォルトのプロセッサーを **置き換え** ます。OpenAI バックエンドに送信したい場合は、その処理を行う `TracingProcessor` を含める必要があります。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使用して **追加** のトレースプロセッサーを登録し、トレース/スパンを受け取らせる。これにより、OpenAI バックエンドへの送信に加えて独自処理を行えます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使用してデフォルトプロセッサーを **置き換え** ます。この場合、OpenAI バックエンドへトレースを送信するには、その機能を持つ `TracingProcessor` を含める必要があります。 ## 非 OpenAI モデルでのトレーシング -非 OpenAI モデルでも、OpenAI API キーを使用することで Traces ダッシュボードでの無償トレーシングが可能です。トレーシングを無効化する必要はありません。 +OpenAI API キーを使用して非 OpenAI モデルでもトレーシングを有効にでき、トレーシングを無効化する必要なく OpenAI Traces ダッシュボードで無料トレースを利用できます。 ```python import os @@ -126,27 +124,27 @@ agent = Agent( ) ``` -## Notes -- OpenAI Traces ダッシュボードで無償トレースを閲覧できます。 +## 備考 +- 無料トレースは OpenAI Traces ダッシュボードで確認できます。 ## 外部トレーシングプロセッサー一覧 -- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) -- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) -- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) - [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index f1b4e2de2..71f13c745 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,27 +2,27 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェント可視化を使用すると、 **Graphviz** を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、 ** Graphviz ** を用いてエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存グループをインストールします: +省略可能な `viz` 依存グループをインストールします: ```bash pip install "openai-agents[viz]" ``` -## グラフ生成 +## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は、次のような有向グラフを作成します: -- **エージェント** は黄色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **ハンドオフ** はエージェント間の有向エッジで表されます。 +- **エージェント** は黄色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** はエージェント間の有向エッジで表されます。 -### 使用例 +### 使い方の例 ```python from agents import Agent, function_tool @@ -52,33 +52,35 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェント グラフ](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -これにより、 **triage agent** の構造とサブエージェントおよびツールとの接続を視覚的に示すグラフが生成されます。 +これにより、 **triage agent** の構造とサブエージェントやツールとの接続を視覚的に表したグラフが生成されます。 -## 可視化の概要 +## 可視化の理解 -生成されたグラフには次が含まれます: +生成されたグラフには次の要素が含まれます: -- エントリーポイントを示す **start node** (`__start__`) -- 黄色で塗られた **rectangles** として表されるエージェント -- 緑色で塗られた **ellipses** として表されるツール -- 相互作用を示す有向エッジ - - エージェント間ハンドオフを示す **Solid arrows** - - ツール呼び出しを示す **Dotted arrows** -- 実行終了位置を示す **end node** (`__end__`) +- エントリーポイントを示す **start node** (`__start__`)。 +- エージェントは黄色で塗りつぶされた **長方形** として表されます。 +- ツールは緑色で塗りつぶされた **楕円** で表されます。 +- 相互作用を示す有向エッジ: + - エージェント間のハンドオフには **実線の矢印**。 + - ツール呼び出しには **点線の矢印**。 +- 実行の終了地点を示す **end node** (`__end__`)。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。別ウィンドウで表示するには、次のように記述します: + +デフォルトでは、 `draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のようにします: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します: + +デフォルトでは、 `draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 007fc0f4f..78eb392e8 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 @@ -32,38 +32,34 @@ graph LR ``` -## パイプラインの設定 +## パイプラインの構成 -パイプラインを作成するとき、以下の項目を設定できます: +パイプラインを作成する際には、次の項目を設定できます。 1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] - 新しい音声が文字起こしされるたびに実行されるコードです。 -2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] モデル + 新しい音声が書き起こされるたびに実行されるコードです。 +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 モデルの設定: プロンプト、言語、データ型 など + - モデル名をモデルにマッピングするモデルプロバイダー + - トレーシング(トレーシングを無効にするか、音声ファイルをアップロードするか、ワークフロー名、トレース ID など) + - プロンプト、言語、使用するデータ型など、TTS と STT モデルに関する設定 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 つの形式で渡せます: +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は次の 2 つの形式で渡せます。 1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声トランスクリプトがある場合に使用し、そのトランスクリプトに対する結果だけを生成します。あらかじめ録音された音声や push-to-talk アプリのように話し終わりが明確なケースで便利です。 + 完全な音声の書き起こしがあり、その結果だけが必要な場合に使用します。話者がいつ話し終えたかを検出する必要がない、事前録音の音声やプッシュ・トゥ・トーク形式のアプリなどで便利です。 2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] - ユーザーが話し終えたかどうかを検知する必要がある場合に使用します。音声チャンクを検出次第プッシュでき、パイプラインが「アクティビティ検知」により適切なタイミングでワークフローを実行します。 + ユーザーが話し終えたタイミングを検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、パイプラインが「アクティビティ検出」と呼ばれる処理で適切なタイミングにワークフローを自動実行します。 ## 結果 -音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。このオブジェクトを通じてイベントをストリーミングで受け取れます。主な [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] は次のとおりです: +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これはイベントを逐次ストリーミングできるオブジェクトで、いくつかの [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] が含まれます。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] - 音声チャンクを含みます。 -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] - ターンの開始や終了など、ライフサイクルイベントを通知します。 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] - エラーイベントです。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] — 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] — ターン開始・終了などのライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] — エラーイベントです。 ```python @@ -83,4 +79,5 @@ 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 a61284452..3ea6de139 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,19 +6,19 @@ search: ## 前提条件 -まず、Agents SDK のベースとなる [quickstart instructions](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。その後、SDK からオプションの音声依存関係をインストールします: + Agents SDK の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。その後、 SDK から音声オプションの依存関係をインストールします: ```bash pip install 'openai-agents[voice]' ``` -## コンセプト +## 概念 -ここで理解しておくべき主要なコンセプトは [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスになっています: +理解しておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスになっています: -1. 音声をテキストに変換する Speech-to-Text モデルを実行します。 -2. 通常はエージェント的なワークフローであるご自身のコードを実行し、結果を生成します。 -3. その結果テキストを音声に戻す Text-to-Speech モデルを実行します。 +1. 音声をテキストに変換する speech-to-text モデルを実行する +2. 通常はエージェント的なワークフローであるご自身のコードを実行して、結果を生成する +3. 結果のテキストを再び音声に変換する text-to-speech モデルを実行する ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントをセットアップしましょう。すでに本 SDK でエージェントを構築したことがある場合は、馴染みのある手順のはずです。ここでは複数のエージェントとハンドオフ、ツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。この SDK でエージェントを構築したことがあれば、見覚えがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインをセットアップします。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインを構築します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## 統合 +## まとめ ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -このサンプルを実行すると、エージェントがあなたに話しかけてくれます。自分でエージェントと会話できるデモは [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) にあるので、ぜひご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話しかけます!実際にエージェントと会話できるデモについては、[examples/voice/static ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のサンプルコードをご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 7bdefa827..d670a4ad3 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -エージェントが [トレーシングされる](../tracing.md) のと同様に、音声パイプラインも自動的にトレーシングされます。 +[エージェントがトレーシングされる方法](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシングの情報については上記のドキュメントをご覧いただけますが、` 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` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]:トレースに追加するメタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機密となり得るデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用で、 Workflow 内部の処理には影響しません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース ワークフロー の名前です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースをリンクするために使用できる `group_id` です。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに追加するメタデータです。 \ No newline at end of file