diff --git a/docs/ja/agents.md b/docs/ja/agents.md index ea6fed3a9..467f61a52 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となるビルディングブロックです。エージェントとは、指示とツールで構成された大規模言語モデル ( LLM ) です。 +エージェントはアプリの中心的な構成要素です。エージェントとは、instructions と tools で設定された大規模言語モデル (LLM) です。 ## 基本設定 -エージェントで最もよく設定するプロパティは次のとおりです。 +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 -- `model`: 使用する LLM、および temperature や top_p などのチューニングパラメーターを設定する `model_settings` (オプション)。 -- `tools`: エージェントがタスク達成のために使用できるツール。 +- `name`：エージェントを識別する必須の文字列。 +- `instructions`：開発者メッセージ、または system prompt とも呼ばれます。 +- `model`：使用する LLM。さらに `model_settings` で temperature や top_p などのモデル調整パラメーターを設定できます。 +- `tools`：エージェントがタスクを達成するために使用できるツール群。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型に対して汎用的です。コンテキストは依存性注入ツールであり、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行の依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを渡せます。 +エージェントは `context` 型についてジェネリックです。Context は依存性注入のための道具で、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、tool、handoff などに渡され、実行中の依存関係や状態をまとめて保持します。任意の Python オブジェクトを context として渡せます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) を出力します。特定の型で出力させたい場合は、`output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使いますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型―dataclass、list、TypedDict など―であれば利用できます。 +デフォルトでは、エージェントはプレーンテキスト (つまり `str`) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使います。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型 ― dataclass、list、TypedDict など ― であれば利用可能です。 ```python from pydantic import BaseModel @@ -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](handoffs.md) ドキュメントを参照してください。 ```python from agents import Agent @@ -98,7 +98,7 @@ triage_agent = Agent( ## 動的 instructions -通常はエージェント作成時に instructions を渡しますが、関数を通じて動的に渡すこともできます。この関数はエージェントと context を受け取り、プロンプトを返さなければなりません。同期関数と `async` 関数の両方を使用できます。 +多くの場合、エージェント作成時に instructions を指定しますが、関数経由で動的に渡すこともできます。この関数は agent と context を受け取り、プロンプトを返さなければなりません。同期関数と `async` 関数の両方を使用できます。 ```python def dynamic_instructions( @@ -113,13 +113,13 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (フック) +## ライフサイクルイベント (hooks) -エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータをプリフェッチしたりするケースです。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] をサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに残したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティでライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、必要なメソッドをオーバーライドしてください。 ## ガードレール -ガードレールを使うと、エージェント実行と並行してユーザー入力に対するチェックやバリデーションを実行できます。たとえば、ユーザー入力の関連性をスクリーニングすることが可能です。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。 +ガードレールを使用すると、エージェントの実行と並行してユーザー入力のチェックやバリデーションを実行できます。たとえば、ユーザー入力の関連性をフィルタリングできます。詳細は [guardrails](guardrails.md) ドキュメントを参照してください。 ## エージェントのクローン／コピー @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、必ずしも LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定するとツール使用を強制できます。有効な値は次のとおりです。 +ツールのリストを渡しても、必ずしも LLM がツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです。 -1. `auto` : LLM がツールを使用するかどうかを自動で判断します。 -2. `required` : LLM にツール使用を必須とします (使用するツールはインテリジェントに決定)。 -3. `none` : LLM にツールを使用しないことを要求します。 -4. 具体的な文字列 (例: `my_tool`) を設定すると、そのツールを必ず使用させます。 +1. `auto`：LLM がツールを使うかどうかを判断します。 +2. `required`：LLM にツール使用を必須とします (どのツールを使うかは LLM が判断)。 +3. `none`：LLM にツールを使用しないことを要求します。 +4. 特定の文字列 (例: `my_tool`) を設定すると、そのツールを必ず使用させます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -163,12 +163,11 @@ agent = Agent( ) ``` -## ツール使用の挙動 +## ツール使用時の挙動 -`Agent` の `tool_use_behavior` パラメーターはツール出力の扱い方を制御します。 - -- `"run_llm_again"`: デフォルト設定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初に呼び出されたツールの出力をそのまま最終応答として使用し、追加の LLM 処理を行いません。 +`Agent` の `tool_use_behavior` パラメーターは、ツールの出力をどのように処理するかを制御します。 +- `"run_llm_again"`：デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 +- `"stop_on_first_tool"`：最初のツール呼び出しの出力を最終応答として使用し、追加の LLM 処理を行いません。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -186,7 +185,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールのいずれかが呼び出されると停止し、その出力を最終応答とします。 +- `StopAtTools(stop_at_tool_names=[...])`：指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool from agents.agent import StopAtTools @@ -207,8 +206,8 @@ agent = Agent( tools=[get_weather, sum_numbers], tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) ) -``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを決定するカスタム関数。 +``` +- `ToolsToFinalOutputFunction`：ツール結果を処理し、停止するか LLM を続行するかを決定するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -246,4 +245,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。ツール結果が LLM に送られ、その後 `tool_choice` により再度ツール呼び出しが生成され…という無限ループを防止するためです。 \ 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 d2559eab4..1fab3bc45 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK をインポートした直後から、LLM リクエストとトレーシングに使用する環境変数 `OPENAI_API_KEY` を参照します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 +デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にこの環境変数を設定できない場合は、 [`set_default_openai_key()`][agents.set_default_openai_key] 関数でキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを個別に設定することも可能です。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。[set_default_openai_client()][agents.set_default_openai_client] 関数を使うことで、この設定を変更できます。 +また、使用する OpenAI クライアントを設定することも可能です。デフォルトでは、 SDK は環境変数もしくは前述のデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更したい場合は、 [`set_default_openai_client()`][agents.set_default_openai_client] 関数を使用してください。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -さらに、使用する OpenAI API もカスタマイズできます。デフォルトでは OpenAI Responses API を利用しますが、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用して Chat Completions API に切り替えられます。 +さらに、利用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用しますが、 [`set_default_openai_api()`][agents.set_default_openai_api] 関数を用いれば Chat Completions API を利用するように上書きできます。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効です。上記セクションで説明した OpenAI API キー（環境変数または設定したデフォルトキー）が使用されます。トレーシング専用の API キーを指定したい場合は、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。前節の OpenAI API キー（環境変数または設定したデフォルトキー）をそのまま使用します。トレーシングに使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key()`][agents.set_tracing_export_api_key] 関数をご利用ください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効にする場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 +トレーシングを完全に無効化したい場合は、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を呼び出してください。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグ ロギング +## デバッグログ -SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られますが、それ以外のログは抑制されます。 +SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは warning と error が `stdout` に送られ、それ以外のログは抑制されます。 -詳細なロギングを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -ログを独自にカスタマイズしたい場合は、ハンドラー、フィルター、フォーマッターなどを追加できます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +ログをカスタマイズしたい場合は、ハンドラー・フィルター・フォーマッターなどを追加できます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) をご覧ください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機密データ +### ログにおける機密データ -一部のログには機密データ（例：ユーザーデータ）が含まれる場合があります。こうしたデータの出力を無効にしたい場合は、以下の環境変数を設定してください。 +一部のログには機密データ（たとえばユーザーデータ）が含まれる場合があります。これらを記録しないようにするには、以下の環境変数を設定してください。 -LLM の入力と出力のロギングを無効にする: +LLM への入力および出力の記録を無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のロギングを無効にする: +ツールへの入力および出力の記録を無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 17c7c897d..71969563c 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語は多義的です。ここでは、気に掛けるべきコンテキストには大きく 2 つのクラスがあります。 +コンテキストという語には複数の意味があります。ここでは、意識するべきコンテキストの主なクラスは 2 つあります。 -1. コードでローカルに利用できるコンテキスト: これは、tool 関数の実行時や `on_handoff` のようなコールバック、ライフサイクルフック内などで必要になるデータや依存関係です。 -2. LLM が利用できるコンテキスト: これは、LLM が応答を生成する際に参照できるデータです。 +1. コード内でローカルに利用できるコンテキスト: ツール関数の実行時や `on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLMs が利用できるコンテキスト: 応答を生成するときに 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. すべての tool 呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` が渡されます。ここで `T` は作成したコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使うパターンがよく見られます。 +2. そのオブジェクトを各種 run メソッド（例: `Runner.run(..., context=whatever)`）に渡します。 +3. すべてのツール呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 - **最も重要なのは**、同一のエージェント実行内では、エージェント・tool 関数・ライフサイクルフックなどがすべて同じ _型_ のコンテキストを使う必要があるという点です。 +**最も重要** なのは、1 回のエージェント実行においては、すべてのエージェント、ツール関数、ライフサイクルフックが同じ _型_ のコンテキストを使用しなければならない点です。 -コンテキストは次のような用途に利用できます。 +コンテキストは次のような用途で利用できます。 -- 実行のためのコンテキストデータ（例: username/uid などユーザーに関する情報） -- 依存関係（例: logger オブジェクトやデータフェッチャーなど） -- ヘルパー関数 +- 実行に関するコンテキストデータ（例: ユーザー名や UID などのユーザー情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 -!!! danger "Note" +!!! danger "注意" - コンテキストオブジェクトは **送信されません** LLM へ。これは純粋にローカルオブジェクトで、読み書きやメソッド呼び出しを自由に行えます。 + コンテキストオブジェクトは **LLM には送信されません**。あくまでローカルオブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,21 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を利用できます。 -2. これは tool です。`RunContextWrapper[UserInfo]` を受け取り、その実装でコンテキストを読み取ります。 -3. ジェネリック型 `UserInfo` でエージェントをマークすることで、型チェッカーがエラーを検出できます（例えば、異なるコンテキスト型を受け取る tool を渡そうとした場合）。 -4. `run` 関数にコンテキストが渡されます。 -5. エージェントは tool を正しく呼び出し、年齢を取得します。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを読み取ります。 +3. 型チェッカーでエラーを捕捉できるよう、エージェントにジェネリック型 `UserInfo` を指定しています（例として、異なるコンテキスト型を期待するツールを渡した場合など）。 +4. `run` 関数にコンテキストを渡しています。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント／LLM コンテキスト +## エージェント／ LLM コンテキスト -LLM が呼び出されたとき、LLM が参照できる **唯一の** データは会話履歴に含まれるものだけです。そのため、新しいデータを LLM に利用させたい場合は、そのデータを履歴に含める形で提供する必要があります。主な方法は次のとおりです。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴に含まれるもの **のみ** です。そのため、新しいデータを LLM に提供したい場合は、そのデータが履歴に含まれるようにする必要があります。代表的な方法は次のとおりです。 -1. Agent の `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。system prompt は静的な文字列でも、コンテキストを受け取って文字列を返す動的な関数でもかまいません。たとえばユーザー名や現在の日付など、常に有用な情報を渡す一般的な方法です。 -2. `Runner.run` を呼び出す際の `input` に追加する。`instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位メッセージとして渡せる点が異なります。 -3. function tools を介して公開する。これは *オンデマンド* のコンテキストに便利です。LLM が必要になったタイミングで tool を呼び出し、データを取得できます。 -4. retrieval や Web 検索を利用する。これらはファイルやデータベースから関連データを取得する retrieval、あるいは Web から取得する Web 検索といった特別なツールです。関連コンテキストデータで応答を「グラウンディング」するのに役立ちます。 \ No newline at end of file +1. Agent の `instructions` に追加する + - これは「system prompt」や「developer message」とも呼ばれます。system prompt は静的な文字列にも、コンテキストを受け取って文字列を返す動的な関数にもできます。たとえばユーザー名や現在の日付など、常に有用な情報を渡す際によく使われます。 +2. `Runner.run` を呼び出す際に `input` に追加する + - `instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより低いレベルのメッセージを渡したい場合に便利です。 +3. function tools を介して公開する + - これはオンデマンドコンテキストに適しています。LLM が必要に応じてツールを呼び出し、データを取得できます。 +4. retrieval や Web 検索を利用する + - retrieval はファイルやデータベースから、Web 検索はウェブ上から関連データを取得できる特殊なツールです。応答を適切なコンテキストに基づいて「グラウンディング」するのに役立ちます。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 8f7d21689..4700e494d 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,44 +4,44 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでは、 SDK のさまざまなサンプル実装をご覧いただけます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでは、SDK の多彩なサンプル実装をご覧いただけます。これらのコード例は、さまざまなパターンや機能を示すいくつかのカテゴリーに整理されています。 ## カテゴリー -- **[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 つの例 +- **[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 モデルを使用した voice エージェントのコード例をご覧ください。 -- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)** : - SDK を使って Realtime API の体験を構築する方法を示す例。 \ 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 4e9434e17..c8d7f2954 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並列_ に実行され、ユーザー入力のチェックとバリデーションを行えます。たとえば、とても賢い (そのため遅く / 高価な) モデルを使用してカスタマーリクエストを処理するエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせようとした場合は避けたいでしょう。そこで、速く / 低コストなモデルで動くガードレールを実行できます。ガードレールが悪意ある利用を検知したら、直ちにエラーを発生させることで高価なモデルの実行を止め、時間とお金を節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックと検証を行えます。たとえば、非常に賢い（ゆえに遅く／高価な）モデルを使って顧客対応を支援するエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を解かせようとするのは避けたいでしょう。この場合は高速／低コストのモデルでガードレールを走らせます。ガードレールが不正利用を検出すると直ちにエラーを発生させ、高価なモデルの実行を止めて時間と費用を節約できます。 -ガードレールには 2 つの種類があります: +ガードレールには 2 種類あります。 -1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールはエージェントの最終出力に対して実行されます +1. 入力ガードレール: 最初のユーザー入力に対して実行 +2. 出力ガードレール: 最終的なエージェント出力に対して実行 ## 入力ガードレール -入力ガードレールは 3 ステップで実行されます: +入力ガードレールは 3 ステップで実行されます。 -1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップします。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理を行えます。 +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` プロパティがエージェント側にあるのは、ガードレールがそれぞれのエージェントに深く関係しており、エージェントごとに異なるガードレールを走らせるため、同じ場所にコードを置くほうが読みやすいからです。 ## 出力ガードレール -出力ガードレールは 3 ステップで実行されます: +出力ガードレールも 3 ステップで実行されます。 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップします。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理を行えます。 +2. 次にガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップします。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外を送出し、ユーザーへの応答や例外処理を行えます。 !!! Note - 出力ガードレールはエージェントの最終出力に対して実行されることを想定しているため、エージェントが *最後の* エージェントである場合にのみガードレールが実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに関連する傾向があるため、コードを同じ場所に置くことで読みやすさが向上します。 + 出力ガードレールは最終的なエージェント出力に対して実行するため、エージェントが *最後* のエージェントである場合にのみ実行されます。入力ガードレールと同様、ガードレールはエージェントに深く関係しており、エージェントごとに異なるガードレールを走らせるため、同じ場所にコードを置くほうが読みやすいという理由からです。 ## トリップワイヤ -入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤを用いてそれを示します。トリップワイヤが作動したガードレールを検知するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェントの実行を停止します。 +入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤを発動してそれを知らせます。トリップワイヤが発動した時点でただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。以下の例では、その処理を内部でエージェントを実行することで行っています。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。以下の例では、その内部でエージェントを実行しています。 ```python from pydantic import BaseModel @@ -95,8 +95,8 @@ async def main(): ``` 1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果に追加情報を含めることができます。 +2. これはエージェントの入力／コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレール結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index d58ba00d1..3cbedfeae 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,15 +4,15 @@ search: --- # ハンドオフ -ハンドオフを利用すると、エージェントがタスクを別のエージェントに委任できます。これは、複数のエージェントがそれぞれ異なる分野を専門としている場合に特に便利です。たとえば、カスタマーサポート アプリでは、注文状況、返金、FAQ などのタスクを個別に担当するエージェントを用意できます。 +ハンドオフを使用すると、あるエージェントがタスクを別のエージェントに委任できます。これは、異なるエージェントがそれぞれ特定分野を専門とするシナリオで特に便利です。たとえばカスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ担当するエージェントが存在する場合があります。 -ハンドオフは LLM からはツールとして扱われます。たとえば `Refund Agent` というエージェントへのハンドオフなら、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してツールとして表現されます。そのため `Refund Agent` という名前のエージェントへハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すことも、ハンドオフをカスタマイズした `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] というパラメーターがあり、直接 `Agent` を渡すことも、ハンドオフをカスタマイズした `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、さらにオーバーライドや入力フィルターをオプションで設定できます。 + Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、さらにオーバーライドや入力フィルターをオプションで設定できます。 ### 基本的な使い方 @@ -28,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のようにエージェントを直接渡すことも、`handoff()` 関数を使うこともできます。 +1. エージェントを直接指定する方法（ `billing_agent` など）と、 `handoff()` 関数を使用する方法のどちらも利用できます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 + [`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが行えます。 -- `agent`: ハンドオフ先となるエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` という形式になります。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出された際に実行されるコールバック関数です。ハンドオフが発生した直後にデータ取得を開始したい場合などに便利です。この関数はエージェント コンテキストを受け取り、必要に応じて LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフで受け取る入力の型（オプション）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。 +- `agent`: ハンドオフ先となるエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` という名前になります。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` から生成される既定のツール説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが発生した時点でデータ取得を開始するなどの用途に便利です。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで想定される入力の型（オプション）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングします。詳細は後述します。 ```python from agents import Agent, handoff, RunContextWrapper @@ -59,7 +59,7 @@ handoff_obj = handoff( ## ハンドオフ入力 -状況によっては、ハンドオフ呼び出し時に LLM からいくつかのデータを受け取りたい場合があります。たとえば「 Escalation agent 」へのハンドオフでは、記録用に理由を提供させたいことがあります。 +状況によっては、ハンドオフを呼び出すときに LLM から追加データを渡したい場合があります。たとえば「 Escalation agent 」へのハンドオフを考えてみましょう。ログに記録できるよう、理由を渡してほしいことがあります。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴をすべて閲覧できます。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定してください。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴をすべて閲覧できる状態になります。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、 [`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -履歴からすべてのツール呼び出しを削除するなど、よく使われるパターンは [`agents.extensions.handoff_filters`][] に実装されています。 +履歴からすべてのツール呼び出しを削除するといった一般的なパターンは、 [`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. `FAQ agent` が呼び出されたときに履歴からすべてのツールを自動的に削除します。 +1. `FAQ agent` が呼び出されたときに、履歴からすべてのツール呼び出しが自動的に削除されます。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるよう、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスが用意されているほか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに自動で推奨データを追加することもできます。 +LLM がハンドオフを正しく理解できるよう、エージェントのプロンプトにハンドオフに関する情報を含めることを推奨します。推奨されるプレフィックスは [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に用意されています。または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出すことで、推奨データを自動的にプロンプトへ追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 840375488..57a3f952d 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 にはごく少数の基本コンポーネントがあります。 -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任できます -- **ガードレール**: エージェントの入力・出力を検証できます -- **セッション**: エージェント実行間の会話履歴を自動的に保持します +- **エージェント**：instructions と tools を備えた LLM +- **ハンドオフ**：特定のタスクを他のエージェントに委任できる機構 +- **ガードレール**：エージェントの入力と出力を検証する仕組み +- **セッション**：エージェント実行間で会話履歴を自動的に保持 -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェント フローを可視化・デバッグし、評価やモデルのファインチューニングにも活用できます。 +これらの基本コンポーネントは Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現し、急な学習コストなしに実際のアプリケーションを構築できます。さらに、SDK にはワークフローを可視化・デバッグできる組み込みの **トレーシング** が含まれており、評価やファインチューニングにも活用できます。 ## Agents SDK を使う理由 -SDK は次の 2 点を設計原則としています。 +SDK の設計原則は次の 2 つです。 -1. 機能は十分だが、学習するべきコンポーネントは少ない。 -2. デフォルト設定で高い実用性を実現しつつ、動作を細かくカスタマイズできる。 +1. 使う価値のある十分な機能を提供しつつ、学習が早いように基本コンポーネントを絞る。 +2. デフォルト設定で高いパフォーマンスを発揮しながら、挙動を細かくカスタマイズできる。 -主な機能は以下のとおりです。 +主な機能は次のとおりです。 -- エージェント ループ: tools の呼び出し、結果の LLM への送信、LLM が終了するまでのループ処理を自動で行います。 -- Python ファースト: 新たな抽象を学ばなくても、組み込み言語機能でエージェントをオーケストレーションおよびチェーンできます。 -- ハンドオフ: 複数のエージェント間で調整と委任を行う強力な機能です。 -- ガードレール: エージェントと並行して入力検証を行い、失敗時には早期に中断します。 -- セッション: エージェント実行間で会話履歴を自動管理し、手動での状態管理を不要にします。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic による検証を提供します。 -- トレーシング: ワークフローを可視化・デバッグ・モニタリングでき、 OpenAI の評価・ファインチューニング・蒸留ツールも利用できます。 +- エージェントループ：ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを自動で処理。 +- Python ファースト：新しい抽象概念を学ぶことなく、Python の言語機能でエージェントを編成・連携。 +- ハンドオフ：複数エージェント間の協調と委任を可能にする強力な機能。 +- ガードレール：エージェントと並行して入力検証を実行し、失敗時は早期に停止。 +- セッション：エージェント実行間の会話履歴を自動管理し、手動の状態管理を不要に。 +- 関数ツール：任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 +- トレーシング：ワークフローの可視化・デバッグ・モニタリングを行い、OpenAI の評価・ファインチューニング・蒸留ツールも利用可能。 ## インストール @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -（これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください） +(_このコードを実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index ef5e48d9e..67db86528 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -2,25 +2,25 @@ search: exclude: true --- -# モデルコンテキストプロトコル ( MCP ) +# Model context protocol (MCP) -[モデルコンテキストプロトコル](https://modelcontextprotocol.io/introduction)（別名 MCP ）は、 LLM にツールとコンテキストを提供する方法です。 MCP のドキュメントから引用します。 +[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP ドキュメントより: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。 MCP を AI アプリケーションにおける USB-C ポートのようなものと考えてください。 USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、 MCP は AI モデルを異なるデータソースやツールに接続するための標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション用の USB-C ポートのようなものだと考えてください。USB-C がデバイスと周辺機器・アクセサリを接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 -Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用してエージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、多種多様な MCP サーバーを利用してエージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、 MCP 仕様では、使用するトランスポートメカニズムに基づいて次の 3 種類のサーバーを定義しています。 +現在、MCP 仕様では使用するトランスポートメカニズムに基づいて 3 種類のサーバーが定義されています。 -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで実行されるイメージです。 -2. **HTTP over SSE** サーバー: リモートで実行され、 URL 経由で接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 +1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動作していると考えることができます。 +2. **HTTP over SSE** サーバー: リモートで動作し、URL を介して接続します。 +3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで動作します。 -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使って接続できます。 +これらのサーバーには [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 -例として、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する方法を示します。 +以下は、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を利用する例です。 ```python from agents.run_context import RunContextWrapper @@ -39,9 +39,9 @@ async with MCPServerStdio( tools = await server.list_tools(run_context, agent) ``` -## MCP サーバーの利用 +## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。 Agents SDK はエージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出し、 LLM に MCP サーバーのツールを認識させます。 LLM が MCP サーバーのツールを呼び出すと、 SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出し、LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 ```python @@ -54,11 +54,11 @@ agent=Agent( ## ツールフィルタリング -MCP サーバーでツールフィルターを設定することで、エージェントが利用できるツールを制限できます。 SDK は静的および動的ツールフィルタリングの両方をサポートしています。 +MCP サーバーにツールフィルターを設定することで、エージェントが利用できるツールを制限できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 ### 静的ツールフィルタリング -単純な許可 / ブロックリストには静的フィルタリングを使用できます。 +単純な許可／ブロックリストには静的フィルタリングを使用できます。 ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,17 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合、処理順序は以下のとおりです。** -1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールだけを残します。 -2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定したものを除外します。 +**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合の処理順序:** -たとえば `allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、`read_file` と `write_file` だけが利用可能になります。 +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` だけになります。 ### 動的ツールフィルタリング -より複雑なロジックが必要な場合は、関数を用いた動的フィルタリングを使用できます。 +より複雑なフィルタリングロジックには、関数を用いた動的フィルターを使用できます。 ```python from agents.mcp import ToolFilterContext @@ -135,20 +137,20 @@ server = MCPServerStdio( ``` `ToolFilterContext` では次の情報にアクセスできます。 -- `run_context`: 現在の実行コンテキスト +- `run_context`: 現在のランコンテキスト - `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバーの名前 +- `server_name`: MCP サーバー名 ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成するためのプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能なインストラクションテンプレートを作成できます。 +MCP サーバーは、エージェントの instructions を動的に生成するためのプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instruction テンプレートを作成できます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します。 +プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを持ちます。 -- `list_prompts()`: サーバー上の利用可能なプロンプトを一覧表示します -- `get_prompt(name, arguments)`: オプションのパラメーター付きで特定のプロンプトを取得します +- `list_prompts()`: サーバー上で利用可能なプロンプトを一覧表示 +- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得 ```python # List available prompts @@ -173,19 +175,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、 MCP サーバーの `list_tools()` が呼び出されます。サーバーがリモートにある場合、これはレイテンシの原因になります。ツールリストを自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツールリストが変更されないことが確実な場合にのみ使用してください。 +エージェントが実行されるたびに、MCP サーバーの `list_tools()` が呼び出されます。サーバーがリモートの場合、これはレイテンシの原因となることがあります。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡してください。ツール一覧が変更されないことが確実な場合にのみ使用してください。 キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 ## エンドツーエンドのコード例 -完全な動作例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 ## トレーシング -[トレーシング](./tracing.md) では MCP の操作を自動的に取得します。対象は次のとおりです。 +[トレーシング](./tracing.md) は MCP の操作を自動で記録します。内容は次のとおりです。 1. MCP サーバーへのツール一覧取得呼び出し -2. 関数呼び出しにおける MCP 関連情報 +2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 8238c6e44..29b4c466f 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,52 +4,52 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに利用できる 2 つの方式が用意されています。 +Agents SDK には、 OpenAI モデルをすぐに利用できる 2 つの方式が用意されています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 -## 非 OpenAI モデル +## OpenAI 以外のモデル -多くの非 OpenAI モデルは [LiteLLM 連携](./litellm.md)を通じて利用できます。まず、litellm の依存グループをインストールします。 +ほとんどの OpenAI 以外のモデルは、 [LiteLLM 連携](./litellm.md) を介して利用できます。まずは litellm の依存関係グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて任意の [対応モデル](https://docs.litellm.ai/docs/providers) を使用します。 +その後、 `litellm/` プレフィックスを付けて、 [対応モデル](https://docs.litellm.ai/docs/providers) を利用できます。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使用するその他の方法 +### OpenAI 以外のモデルを使うその他の方法 -他の LLM プロバイダーは、以下の 3 つの方法でも統合できます（[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にコード例があります）。 +他の LLM プロバイダーを統合する方法はさらに 3 つあります（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) を参照）。 1. [`set_default_openai_client`][agents.set_default_openai_client] - グローバルに `AsyncOpenAI` インスタンスを LLM クライアントとして使用したい場合に便利です。API エンドポイントが 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) を参照してください。 + `AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。 LLM プロバイダーが OpenAI 互換エンドポイントを持っており、 `base_url` と `api_key` を設定できるケースで使用します。設定例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 2. [`ModelProvider`][agents.models.interface.ModelProvider] - `Runner.run` レベルで使用します。この方法では、「この実行の全エージェントに対してカスタムモデルプロバイダーを使用する」と指定できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 + `Runner.run` レベルで指定します。「この実行内のすべての エージェント でカスタムモデルプロバイダーを使う」と宣言できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 3. [`Agent.model`][agents.agent.Agent.model] - 特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどのモデルを簡単に利用するには [LiteLLM 連携](./litellm.md) を使うのが便利です。 + 特定の 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 連携が便利です。 -`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API キーをお持ちでない場合は、 `set_tracing_disabled()` でトレーシングを無効にするか、 [別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 !!! note - これらの例では Chat Completions API／モデルを使用しています。これは、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、Responses の利用を推奨します。 + これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、 Chat Completions API／モデルを使用しています。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、 Responses を利用することを推奨します。 ## モデルの組み合わせ -ひとつのワークフロー内で、エージェントごとに異なるモデルを使いたいことがあります。たとえば、トリアージには小さく高速なモデルを使用し、複雑なタスクには大規模で高性能なモデルを使用する、といったケースです。[`Agent`][agents.Agent] を設定する際、以下のいずれかでモデルを選択できます。 +1 つのワークフロー内で、 エージェント ごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小規模で高速なモデルを、複雑なタスクには大規模で高性能なモデルを使う、といったケースです。 [`Agent`][agents.Agent] を設定する際、次のいずれかでモデルを選択できます。 1. モデル名を直接渡す。 -2. 任意のモデル名と、それを [`ModelProvider`][agents.models.interface.ModelProvider] が Model インスタンスへマッピングできるようにする。 +2. 任意のモデル名と、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとにモデル形状を 1 つに統一することを推奨します。両モデル形状は対応機能やツールが異なるためです。もし混在させる場合は、利用する機能が両方で利用可能か必ず確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、ワークフローごとに 1 つのモデル形状を使うことを推奨します。両モデル形状は対応する機能・ツールが異なるため、混在させる場合は使用する機能が両方で利用可能か確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -83,9 +83,9 @@ async def main(): ``` 1. OpenAI モデル名を直接指定しています。 -2. [`Model`][agents.models.interface.Model] の実装を提供しています。 +2. [`Model`][agents.models.interface.Model] 実装を提供しています。 -エージェントで使用するモデルをさらに設定したい場合は、`temperature` などのオプションパラメーターを含む [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェントで使用するモデルをさらに詳細に設定したい場合は、 `temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -98,7 +98,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合は、`user` や `service_tier` など [他にもオプションのパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、`extra_args` を利用して渡してください。 +また、 OpenAI の Responses API を使用する場合、 `user` や `service_tier` など [いくつかの追加オプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、 `extra_args` を使って渡してください。 ```python from agents import Agent, ModelSettings @@ -116,25 +116,26 @@ english_agent = Agent( ## 他の LLM プロバイダー利用時によくある問題 -### Tracing クライアントエラー 401 +### Tracing client error 401 -トレースは OpenAI サーバーへアップロードされるため、OpenAI API キーがない場合にエラーになることがあります。以下のいずれかで解決できます。 +トレーシングに関するエラーが発生する場合、トレースが OpenAI サーバーにアップロードされるため、 OpenAI API キーがないことが原因です。解決策は 3 つあります。 1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] 2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] - この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. 非 OpenAI トレースプロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 + この API キーはトレースのアップロードのみに使用され、 [platform.openai.com](https://platform.openai.com/) のキーである必要があります。 +3. 非 OpenAI のトレース プロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、ほとんどの LLM プロバイダーはまだ対応していません。そのため 404 エラーなどが発生することがあります。次のいずれかで解決できます。 +SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーはまだ対応していません。そのため 404 エラーなどが発生する場合があります。解決策は 2 つです。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数 `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に有効です。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。 + これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 ### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは、 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 ``` @@ -142,12 +143,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダーの制限で、JSON 出力には対応していても `json_schema` を指定できないために起こります。現在修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーを利用することを推奨します。サポートがない場合、JSON が不正形式になりアプリが頻繁に壊れる可能性があります。 +これは一部プロバイダーの制限で、 JSON 出力はサポートしているものの、出力に使用する `json_schema` を指定できないためです。現在修正に取り組んでいますが、 JSON スキーマ出力をサポートしているプロバイダーを利用することを推奨します。そうでない場合、 JSON が不正な形式で返され、アプリが頻繁に壊れる可能性があります。 -## プロバイダー間でのモデル混在 +## プロバイダーをまたぐモデルの混在 -モデルプロバイダーごとの機能差に注意しないと、エラーになる場合があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索や Web 検索をサポートしていますが、多くのプロバイダーはこれらをサポートしていません。以下の点に注意してください。 +モデル プロバイダー間の機能差に注意しないと、エラーが発生する場合があります。たとえば、 OpenAI は structured outputs、マルチモーダル入力、ホストされたファイル検索・ Web 検索をサポートしていますが、多くの他社プロバイダーはこれらをサポートしていません。次の点に注意してください。 -- 対応していない `tools` を理解しないプロバイダーには送らない -- テキスト専用モデルを呼び出す前にマルチモーダル入力を除去する -- structured JSON outputs をサポートしないプロバイダーでは、無効な JSON が返されることがありますので注意する \ No newline at end of file +- 対応していないプロバイダーに `tools` を送らない +- テキスト専用モデルを呼び出す前にマルチモーダル入力を除外する +- structured JSON 出力をサポートしないプロバイダーでは、無効な JSON が返ることがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index f632316b5..78591f5d8 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM 経由での任意モデル利用 +# LiteLLM 経由で任意のモデルを利用する !!! note - LiteLLM 統合はベータ版です。特に規模の小さいモデルプロバイダーでは問題が発生する可能性があります。問題を見つけた場合は [Github issues](https://github.com/openai/openai-agents-python/issues) でご報告ください。迅速に対応いたします。 + LiteLLM インテグレーションはベータ版です。特に小規模なプロバイダーでは問題が発生する場合があります。問題を見つけた場合は [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、任意の AI モデルを使用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、1 つのインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM インテグレーションを追加したことで、どの AI モデルでも利用できるようになりました。 ## セットアップ -`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで対応できます。 +`litellm` が利用可能であることを確認する必要があります。これは、オプションの `litellm` 依存関係グループをインストールすることで行えます。 ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -以下は完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば以下のように指定できます。 +以下は完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます。 -- `openai/gpt-4.1` をモデルに指定し、OpenAI API キーを入力 -- `anthropic/claude-3-5-sonnet-20240620` をモデルに指定し、Anthropic API キーを入力 -- その他 +- モデルに `openai/gpt-4.1`、API キーに OpenAI API キー +- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic API キー +- など -LiteLLM でサポートされているモデルの一覧は [litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM でサポートされているモデルの一覧については、[litellm providers docs](https://docs.litellm.ai/docs/providers) をご覧ください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 82e6bab2b..8027e6fd0 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,47 +4,47 @@ search: --- # 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントのフローを指します。どのエージェントが実行されるのか、どの順序で実行されるのか、そして次に何が起こるかをどのように決定するのかということです。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でエージェントがどのように実行されるか、その順序、そして次に何を行うかを決定するフローを指します。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定させる - LLM の知能を利用して計画・推論し、その結果に基づいて次に取るステップを決めます。 -2. コードでオーケストレーションする - コードによってエージェントのフローを決定します。 +1. LLM に意思決定を任せる + これは LLM の知能を利用して計画や推論を行い、次に取るべきステップを決定します。 +2. コードによるオーケストレーション + コード側でエージェントのフローを制御します。 -これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使用できます。それぞれに以下のようなトレードオフがあります。 -## LLM によるオーケストレーション +## LLM を用いたオーケストレーション -エージェントとは、 LLM が instructions、tools、handoffs を装備したものです。これにより、 LLM は自由形式のタスクに対して自律的に計画を立て、tools を使ってアクションを実行してデータを取得し、handoffs を活用してサブエージェントへタスクを委任できます。たとえば、リサーチエージェントには次のような tools を装備できます。 +エージェントとは、instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はタスクを達成するための計画を自律的に立て、tools を使ってアクションを実行・データを取得し、handoffs を通じてサブエージェントにタスクを委任できます。たとえば、リサーチエージェントには次のような tools を持たせることができます。 -- オンラインで情報を見つけるための Web 検索 -- 独自データや接続を検索するための File 検索および取得 -- アクションを実行するための Computer 操作 -- データ分析を行うための Code 実行 -- 計画立案やレポート作成などに優れた専門エージェントへの handoffs +- Web 検索でオンライン情報を収集 +- ファイル検索と取得で独自データや接続先を検索 +- コンピュータ操作で PC 上のアクションを実行 +- コード実行でデータ分析を実施 +- 計画立案やレポート作成などを得意とする専門エージェントへの handoffs -このパターンはタスクが自由形式であり、 LLM の知能に頼りたい場合に最適です。重要なポイントは次のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知能に依存したい場合に最適です。重要なポイントは次のとおりです。 1. 良いプロンプトに投資する - 利用可能な tools、使用方法、遵守すべきパラメーターを明確にします。 -2. アプリを監視し、改善を繰り返す - 問題が発生した箇所を確認し、プロンプトを改善します。 + 利用可能な tools、使用方法、動作パラメーターを明示します。 +2. アプリを監視して改善する + 問題が発生した箇所を確認し、プロンプトを繰り返し改善します。 3. エージェントに内省と改善を許可する - 例として、ループで実行して自己批評させる、エラーメッセージを提供して改善させるなどがあります。 -4. 何でもこなす汎用エージェントではなく、特定タスクに特化したエージェントを用意する + 例としてループで実行し、自己批評させたり、エラーメッセージを渡して改善させたりします。 +4. 何でもこなせる汎用エージェントより、特定タスクに特化したエージェントを用意する 5. [evals](https://platform.openai.com/docs/guides/evals) に投資する - これによりエージェントを訓練し、タスク遂行能力を向上させられます。 + これによりエージェントを学習・改善し、タスク遂行能力を高められます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションでは速度・コスト・性能の面でタスクをより決定論的かつ予測可能にできます。よく使われるパターンは以下のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を利用して、コードで検査できる適切な形式のデータを生成する - たとえば、タスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づき次のエージェントを選択できます。 -- あるエージェントの出力を次のエージェントの入力に変換して複数エージェントを連鎖させる - ブログ記事執筆を「リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善」という連続ステップに分解できます。 -- タスクを実行するエージェントを `while` ループで回し、別のエージェントが評価・フィードバックを行い、評価者が基準を満たしたと判断するまで繰り返す -- `asyncio.gather` のような Python の基本コンポーネントで複数エージェントを並列実行する - 互いに依存しないタスクが複数ある場合、速度向上に有効です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使い、コードで検査できる適切な形式のデータを生成する + 例として、エージェントにタスクを複数のカテゴリーに分類させ、カテゴリーに応じて次のエージェントを選択します。 +- あるエージェントの出力を次のエージェントの入力に変換して複数エージェントを連鎖させる + ブログ記事作成のタスクを、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善といった一連のステップに分解できます。 +- タスクを実行するエージェントを `while` ループで回し、別のエージェントが評価とフィードバックを行い、評価者が基準を満たしたと判断するまで繰り返す +- `asyncio.gather` など Python の基本コンポーネントを用いて複数エージェントを並列実行する + 互いに依存しない複数タスクを高速に処理する際に有効です。 -`examples/agent_patterns` ディレクトリに多数の code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 098312706..ed423b693 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -一度だけ実行すれば大丈夫です。 +これは一度だけ行えば問題ありません。 ```bash mkdir my_project @@ -14,7 +14,7 @@ cd my_project python -m venv .venv ``` -### 仮想環境の有効化 +### 仮想環境のアクティベート 新しいターミナルセッションを開始するたびに実行してください。 @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだ持っていない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 +OpenAI API キーをお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## はじめてのエージェントを作成する +## 最初のエージェントの作成 -エージェントは instructions、name、そして `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,7 +93,7 @@ async def main(): print(result.final_output) ``` -## ガードレールを追加する +## ガードレールの追加 入力または出力に対して実行するカスタムガードレールを定義できます。 @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてをまとめる +## 全体ワークフローの統合 -ハンドオフと入力ガードレールを使用して、ワークフロー全体をまとめて実行してみましょう。 +ハンドオフと入力ガードレールを使用し、すべてをまとめてワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースを確認する +## トレースの確認 -エージェントの実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動し、エージェント実行のトレースを確認してください。 +エージェント実行中に何が起こったかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動し、トレースを閲覧してください。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう: +より複雑なエージェントフローの構築方法を学びましょう。 -- [エージェント](agents.md) の設定方法について学ぶ -- [エージェントの実行](running_agents.md) について学ぶ +- [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 7629a8578..ac5d130b0 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の リアルタイム 機能を利用して、音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK の realtime 機能を使用して音声対応 AI エージェントを構築する方法を詳細に説明します。 -!!! warning "ベータ機能" -リアルタイム エージェントはベータ版です。実装を改善する過程で、破壊的変更が入る可能性があります。 +!!! warning "Beta 機能" +Realtime エージェントは Beta 版です。実装改善に伴い、破壊的変更が入る可能性があります。 ## 概要 -リアルタイム エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答できる会話フローを実現します。OpenAI の Realtime API と持続的に接続し、低レイテンシで自然な音声対話を行い、割り込みにもスムーズに対応します。 +Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する会話フローを実現します。OpenAI の Realtime API と持続的に接続し、低レイテンシで自然な音声対話を提供し、割り込みにもスムーズに対応できます。 ## アーキテクチャ -### コアコンポーネント +### 主要コンポーネント -リアルタイム システムは、次の主要コンポーネントで構成されます。 +realtime システムは、次の重要なコンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs で設定されたエージェントです。 -- **RealtimeRunner**: 設定の管理を行います。`runner.run()` を呼び出してセッションを取得します。 -- **RealtimeSession**: 1 回の対話セッションを表します。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデル インターフェース（通常は OpenAI の WebSocket 実装）です。 +- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得します。 +- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話終了まで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） ### セッションフロー -一般的なリアルタイム セッションの流れは次のとおりです。 +典型的な realtime セッションは次の流れで進みます。 -1. **RealtimeAgent** を instructions、tools、handoffs で作成します。 -2. **RealtimeRunner** をエージェントと設定オプションで準備します。 -3. `await runner.run()` を実行して **セッションを開始** し、RealtimeSession を取得します。 -4. `send_audio()` または `send_message()` で **音声またはテキストメッセージを送信** します。 -5. セッションをイテレートして **イベントを受信** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. ユーザーがエージェントの発話に割り込んだ場合は **割り込みを処理** します。現在の音声生成が自動で停止します。 +1. **RealtimeAgent を作成**: instructions、tools、handoffs を設定します。 +2. **RealtimeRunner をセットアップ**: エージェントと構成オプションを渡します。 +3. **セッション開始**: `await runner.run()` を実行して `RealtimeSession` を取得します。 +4. **音声またはテキスト送信**: `send_audio()` または `send_message()` でセッションに送信します。 +5. **イベント受信**: セッションをイテレートしてイベントを受信します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどがあります。 +6. **割り込み処理**: ユーザーがエージェントの発話を遮った場合、自動的に音声生成を停止します。 -セッションは会話履歴を保持し、リアルタイム モデルとの持続的接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの持続的接続を管理します。 ## エージェント設定 -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`) はサポートされていません。 +- Voice はエージェント単位で設定できますが、最初のエージェントが発話した後に変更できません。 +- tools、handoffs、instructions などその他の機能は同じように動作します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となるリアルタイム モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text / audio）の指定が可能です。入出力の音声フォーマットは PCM16 がデフォルトですが変更できます。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、Voice 選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキスト／音声）を設定できます。音声の入出力フォーマットは PCM16 がデフォルトですが変更可能です。 -### オーディオ設定 +### 音声設定 -オーディオ設定では音声入力と出力の扱いを制御します。Whisper などのモデルで入力音声を文字起こしし、言語設定やドメイン固有用語の精度向上のための transcription prompts を指定できます。ターン検出の設定により、エージェントが応答を開始・終了するタイミングを制御できます（音声活動検出のしきい値、無音時間、検出前後のパディングなど）。 +音声設定では、音声入力と出力の取り扱いを指定します。Whisper などのモデルで入力音声を文字起こしし、言語や専門用語向けの transcription prompt を設定できます。ターン検出設定では、音声アクティビティ検出の閾値、無音時間、検出された音声前後のパディングなど、エージェントが応答を開始・停止する条件を制御します。 -## ツールと関数 +## Tools と Functions -### ツールの追加 +### Tools の追加 -通常のエージェントと同様、リアルタイム エージェントでは会話中に実行される function tools をサポートします。 +通常のエージェントと同様に、realtime エージェントでも会話中に実行する function tools をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、会話を専門エージェント間で転送できます。 +handoffs により、会話を専門化されたエージェント間で引き継ぐことができます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはストリーミングでイベントを生成し、セッションオブジェクトをイテレートすることで受信できます。主なイベントは次のとおりです。 +セッションはイベントをストリーム配信し、セッションオブジェクトをイテレートして受信できます。主なイベントは以下のとおりです。 -- **audio**: エージェントの応答の raw 音声データ -- **audio_end**: エージェントの発話が終了 +- **audio**: エージェント応答の raw 音声データ +- **audio_end**: エージェントの発話終了 - **audio_interrupted**: ユーザーがエージェントを割り込み -- **tool_start / tool_end**: ツール実行の開始・終了 -- **handoff**: エージェントのハンドオフ発生 +- **tool_start/tool_end**: tool 実行ライフサイクル +- **handoff**: エージェント間の handoff - **error**: 処理中にエラー発生 -完全なイベント一覧は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] をご参照ください。 +完全なイベント定義は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -リアルタイム エージェントでは出力ガードレールのみサポートされます。パフォーマンスを保つため、ガードレールはデバウンスされて定期的（毎文字ではなく）に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでは output ガードレールのみサポートします。パフォーマンスへの影響を抑えるため、単語ごとではなくデバウンスして定期的に実行されます。デフォルトのデバウンス長は 100 文字で、設定可能です。 -ガードレールは `RealtimeAgent` に直接、またはセッションの `run_config` を通じて追加できます。両方から指定した場合は一緒に実行されます。 +ガードレールは `RealtimeAgent` に直接付与するか、セッションの `run_config` で指定できます。両方に設定した場合は併せて実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレールが発動すると `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] インターフェースへ直接アクセスでき、低レベルの接続制御が必要な高度なユースケースに対応できます。 -## コード例 +## 例 -動作する完全なコード例は、UI 付き・無しデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ 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 f48589de2..3c18bc3cc 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,27 +4,26 @@ search: --- # クイックスタート -Realtime エージェントを使用すると、OpenAI の Realtime API を介して AI エージェントとの音声会話が可能になります。このガイドでは、初めての Realtime 音声エージェントを作成する手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を実現します。このガイドでは、初めてのリアルタイム音声エージェントを作成する手順を説明します。 !!! warning "Beta feature" -Beta 機能 -Realtime エージェントはベータ版です。実装を改善する過程で非互換の変更が入る可能性があります。 +Realtime エージェントは β 版です。実装の改善に伴い、互換性が壊れる変更が入る可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK に関する基本的な知識 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK に関する基本的な知識 ## インストール -まだインストールしていない場合は、OpenAI Agents SDK をインストールします: +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## 最初の Realtime エージェントの作成 +## 初めてのリアルタイム エージェントを作成する ### 1. 必要なコンポーネントをインポート @@ -33,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. Realtime エージェントを作成 +### 2. リアルタイム エージェントを作成 ```python agent = RealtimeAgent( @@ -80,9 +79,9 @@ async def main(): asyncio.run(main()) ``` -## 完全なコード例 +## 完全な例 -以下は動作する完全なコード例です: +以下は動作する完全な例です: ```python import asyncio @@ -140,30 +139,30 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-4o-realtime-preview`) -- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストおよび／またはオーディオを有効化します (`["text", "audio"]`) +- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-4o-realtime-preview`) +- `voice`: 音声を選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストおよび/またはオーディオを有効化 (`["text", "audio"]`) ### オーディオ設定 - `input_audio_format`: 入力オーディオのフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) - `output_audio_format`: 出力オーディオのフォーマット -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_transcription`: 文字起こし設定 ### ターン検出 - `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声アクティビティのしきい値 (0.0-1.0) -- `silence_duration_ms`: ターン終了を検出するための無音時間 +- `threshold`: 音声活動のしきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 - `prefix_padding_ms`: 発話前のオーディオパディング ## 次のステップ -- [Realtime エージェントについてさらに学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作するコード例を確認してください -- エージェントにツールを追加する -- エージェント間のハンドオフを実装する -- 安全のためのガードレールを設定する +- [Realtime エージェントについて詳しく学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作する code examples を確認 +- エージェントにツールを追加 +- エージェント間のハンドオフを実装 +- 安全性のためにガードレールを設定 ## 認証 @@ -173,7 +172,7 @@ OpenAI API キーが環境変数に設定されていることを確認してく export OPENAI_API_KEY="your-api-key-here" ``` -あるいは、セッション作成時に直接渡します: +または、セッション作成時に直接渡します: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index a238ce524..ec742b905 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 が依然として急速に進化していることを示します。各コンポーネントの増分ルールは次のとおりです。 -## Minor（`Y`）バージョン +## マイナー (`Y`) バージョン -ベータではない公開インターフェースに **互換性を破壊する変更** が入る場合、Minor バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への変更には破壊的変更が含まれる可能性があります。 +ベータではない公開インターフェースに **破壊的変更 (breaking changes)** が入る場合、マイナー番号 `Y` を増やします。たとえば `0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -互換性を破壊する変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定することを推奨します。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定することをおすすめします。 -## Patch（`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` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承しているクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 1c61dc336..caac61752 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,8 @@ search: --- # REPL ユーティリティ - SDK には、ターミナルでエージェントの挙動を素早くインタラクティブにテストできる `run_demo_loop` が用意されています。 + SDK は `run_demo_loop` を提供しており、ターミナル内で エージェント の挙動を迅速かつインタラクティブにテストできます。 + ```python import asyncio @@ -18,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` - `run_demo_loop` はループ内で ユーザー からの入力を促し、ターン間の会話履歴を保持します。デフォルトでは、生成されるそばからモデルの出力を ストリーミング します。上記の例を実行すると、 run_demo_loop はインタラクティブなチャットセッションを開始します。入力を継続的に受け取り、ターンごとに会話履歴を保持することで（エージェントがこれまでのやり取りを把握できます）、生成された応答をリアルタイムで自動的に ストリーミング します。 +`run_demo_loop` はユーザー入力を促すループを実行し、各ターン間の会話履歴を保持します。デフォルトでは、生成されたモデル出力を ストリーミング します。上記の例を実行すると、 run_demo_loop がインタラクティブなチャット セッションを開始します。ツールは継続的にあなたの入力を尋ね、各ターン間の完全な会話履歴を記憶するため、エージェント は何が議論されたかを把握できます。また、生成されると同時にリアルタイムで エージェント の応答を自動的に ストリーミング します。 - このチャットセッションを終了するには、`quit` または `exit` と入力して Enter キーを押すか、 `Ctrl-D` キーボードショートカットを使用してください。 \ No newline at end of file +チャット セッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボード ショートカットを使用してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index 14e511b97..69bea56a5 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,48 +4,48 @@ search: --- # 結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返されます: +`Runner.run` メソッドを呼び出すと、以下のいずれかが返されます: -- [`RunResult`][agents.result.RunResult] — `run` または `run_sync` を呼び出した場合 -- [`RunResultStreaming`][agents.result.RunResultStreaming] — `run_streamed` を呼び出した場合 +- [`RunResult`][agents.result.RunResult] は `run` または `run_sync` を呼び出した場合 +- [`RunResultStreaming`][agents.result.RunResultStreaming] は `run_streamed` を呼び出した場合 -これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報のほとんどはここに含まれています。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報のほとんどはそこに含まれています。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されます。これは次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が格納されます。内容は次のいずれかです: -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `output_type` が設定されていない場合は `str` +- エージェントに `output_type` が設定されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフがあるため静的に型付けできません。ハンドオフが発生すると、どの 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`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されます。アプリケーションによっては、ユーザーが次に入力を送る際にこれが役立つことがよくあります。たとえば、フロントラインのトリアージエージェントが言語別エージェントへハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にメッセージを送ったときに再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] でラップされています。RunItem は LLM が生成した raw アイテムを包みます。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。各アイテムは [`RunItem`][agents.items.RunItem]s です。RunItem は LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] — LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] — LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] — ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムから送信元/送信先エージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] — LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] — ツールが呼び出されたことを示します。raw アイテムはツール応答です。アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] — LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しに対するツール応答です。source/target エージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツールの応答で、ツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 ### ガードレール結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果が格納されます (存在する場合)。ガードレール結果にはログや保存に役立つ情報が含まれることがあるため、これらを公開しています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレール（存在する場合）の結果が含まれます。ガードレールの結果にはログや保存に便利な情報が含まれることがあるため、これらを利用できるようにしています。 ### raw レスポンス @@ -53,4 +53,4 @@ search: ### 元の入力 -[`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 5dd218b09..0f01c484a 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは `Runner` クラスを通じて実行できます。選択肢は 3 つあります: +エージェントは `Runner` クラスを通じて実行できます。方法は 3 通りあります: -1. [`Runner.run()`][agents.run.Runner.run] — 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync] — 同期メソッドで、内部的には `.run()` を呼び出します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] — 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリームで提供します。 +1. `Runner.run()` — 非同期で実行し、 `RunResult` を返します。 +2. `Runner.run_sync()` — 同期メソッドで、内部的には `.run()` を呼び出します。 +3. `Runner.run_streamed()` — 非同期で実行し、 `RunResultStreaming` を返します。 LLM をストリーミングモードで呼び出し、そのイベントを受信次第ストリームします。 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) を参照してください。 +詳細は [結果ガイド](results.md) をご覧ください。 ## エージェントループ -`Runner` の run メソッドでは、開始エージェントと入力を渡します。入力は文字列 (ユーザー メッセージと見なされます) か、OpenAI Responses API のアイテムのリストのいずれかです。 +`Runner` の run メソッドでは、開始エージェントと入力を渡します。入力は文字列 (ユーザー メッセージと見なされます) か、OpenAI Responses API のアイテムを並べたリストのいずれかです。 runner は次のループを実行します: -1. 現在のエージェントに対して LLM を呼び出し、現在の入力を渡します。 +1. 現在のエージェントに対し、現在の入力を用いて LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 - 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加してループを再実行します。 -3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 1. `final_output` が返された場合、ループを終了し結果を返します。 + 2. ハンドオフが行われた場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. ツール呼び出しを生成した場合、それらを実行し結果を追加したうえでループを再実行します。 +3. 渡された `max_turns` を超えた場合、 `MaxTurnsExceeded` 例外を送出します。 !!! note - LLM 出力が「最終出力」と見なされる条件は、望ましい型でテキスト出力を生成し、かつツール呼び出しが 1 つも含まれていないことです。 + LLM の出力が「最終出力」と見なされるルールは、所定の型でテキスト出力を生成し、かつツール呼び出しが存在しない場合です。 ## ストリーミング -ストリーミングを使用すると、LLM の実行中にストリーミングイベントを受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行の全情報 (生成されたすべての新しい出力を含む) が格納されます。ストリーミングイベントを受け取るには `.stream_events()` を呼び出してください。詳細は [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングを使用すると、LLM 実行中のイベントを逐次受け取れます。ストリーム終了後、 `RunResultStreaming` には実行に関する完全な情報 (新たに生成されたすべての出力を含む) が格納されます。 ` .stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 -## run_config の設定 +## Run config -`run_config` パラメーターを使用すると、エージェント実行のグローバル設定を構成できます: +`run_config` パラメーターでは、エージェント実行に関するグローバル設定を行えます: -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関係なく、実行全体で使用する LLM モデルを設定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダー。デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力 / 出力ガードレールのリスト。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに特定の 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]: すべてのトレースに含めるメタデータ。 +- `model` — 各エージェントの `model` 設定に関わらず、使用する LLM モデルをグローバルに指定します。 +- `model_provider` — モデル名を解決するモデルプロバイダーを指定します。既定は OpenAI です。 +- `model_settings` — エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 +- `input_guardrails`, `output_guardrails` — すべての実行に適用する入力 / 出力ガードレールのリスト。 +- `handoff_input_filter` — ハンドオフ側で未設定の場合に適用されるグローバル入力フィルター。新しいエージェントに送る入力を編集できます。詳細は `Handoff.input_filter` のドキュメントをご覧ください。 +- `tracing_disabled` — 実行全体のトレーシングを無効化します。 +- `trace_include_sensitive_data` — LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 +- `workflow_name`, `trace_id`, `group_id` — 実行のトレーシング用ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。 `group_id` は複数の実行にまたがるトレースを関連付ける任意フィールドです。 +- `trace_metadata` — すべてのトレースに含めるメタデータ。 ## 会話 / チャットスレッド -どの run メソッドを呼び出しても、1 つ以上のエージェント (したがって 1 回以上の LLM 呼び出し) が実行される可能性がありますが、チャット会話における論理上は 1 ターンを表します。例: +任意の run メソッドの呼び出しは、1 つ以上のエージェント実行 (つまり 1 つ以上の LLM 呼び出し) を伴いますが、チャット会話における単一の論理ターンを表します。例: 1. ユーザーターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ。2 番目のエージェントがさらにツールを実行し、最終出力を生成。 +2. Runner 実行: 第 1 エージェントが LLM を呼び出し、ツールを実行し、第 2 エージェントへハンドオフ。第 2 エージェントがさらにツールを実行し、出力を生成。 -エージェントの実行が終了したら、ユーザーに表示する内容を選択できます。たとえば、エージェントが生成したすべての新しいアイテムを表示することも、最終出力だけを表示することも可能です。いずれの場合も、ユーザーがフォローアップ質問をしたら再度 run メソッドを呼び出してください。 +エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。たとえばエージェントが生成したすべての新規アイテムを見せるか、最終出力のみを見せるかです。いずれの場合も、ユーザーがフォローアップ質問を行ったら再度 run メソッドを呼び出します。 ### 手動での会話管理 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して、次ターンの入力を取得し、会話履歴を手動で管理できます: +`RunResultBase.to_input_list()` メソッドで次ターン用の入力を取得し、会話履歴を手動管理できます: ```python async def main(): @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使用すると、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動で扱えます: +より簡単な方法として、 [Sessions](sessions.md) を使用すれば `.to_input_list()` を手動で呼ばずに会話履歴を自動管理できます: ```python from agents import Agent, Runner, SQLiteSession @@ -116,26 +116,26 @@ async def main(): # California ``` -Sessions は次を自動で行います: +Sessions は自動的に以下を行います: -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- 異なる session ID ごとに個別の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なる session ID ごとに会話を分離して管理 -詳細は [Sessions のドキュメント](sessions.md) を参照してください。 +詳細は [Sessions ドキュメント](sessions.md) を参照してください。 -## 長時間実行エージェントと Human-in-the-Loop +## 長時間実行エージェント & Human-in-the-loop -Agents SDK の [Temporal](https://temporal.io/) インテグレーションを使用すると、Human-in-the-Loop タスクを含む耐久性のある長時間実行ワークフローを構築できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) をご覧ください。また、[こちらのドキュメント](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) も参照してください。 +Agents SDK は [Temporal](https://temporal.io/) との統合により、長時間実行ワークフローや 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`][] にあります。概要は次のとおりです: +特定の状況で SDK は例外を送出します。完全な一覧は `agents.exceptions` にあります。概要は以下のとおりです: -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で発生するすべての例外の基底クラスです。すべての特定例外はこのクラスを継承します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドで `max_turns` 制限を超えた場合に送出されます。ターン数内でエージェントがタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル (LLM) が予期しない、または無効な出力を生成した場合に発生します。例: - - 不正な JSON 形式: ツール呼び出し、または特定の `output_type` が定義されている場合の直接出力で、モデルが不正な JSON 構造を返したとき - - 予期しないツール関連の失敗: モデルがツールを期待どおりに使用しなかったとき -- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた (コードを書く人) がエラーを起こした場合に送出されます。誤ったコード実装、無効な設定、SDK の API の誤用などが原因です。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力ガードレールまたは出力ガードレールの条件が満たされた場合に送出されます。入力ガードレールは処理前の受信メッセージを、出力ガードレールはエージェントの最終応答をチェックします。 \ No newline at end of file +- `AgentsException` — SDK 内で送出されるすべての例外の基底クラスで、他の具体的な例外の共通型として機能します。 +- `MaxTurnsExceeded` — `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` に渡した `max_turns` を超えたときに送出されます。指定ターン数内にタスクを完了できなかったことを示します。 +- `ModelBehaviorError` — 基盤となるモデル ( LLM ) が予期しない、または無効な出力を生成した場合に発生します。例: + - 不正な JSON: ツール呼び出しや直接出力で JSON 構造が壊れている場合 (特に `output_type` を指定している場合)。 + - 予期しないツール関連の失敗: モデルがツールを想定どおりに使用できなかった場合。 +- `UserError` — SDK を使用する際の実装ミス、無効な設定、API の誤用など、ユーザー側のエラーで送出されます。 +- `InputGuardrailTripwireTriggered`, `OutputGuardrailTripwireTriggered` — 入力ガードレールまたは出力ガードレールの条件を満たした場合に送出されます。入力ガードレールは処理前のメッセージを、出力ガードレールはエージェントの最終応答を検査します。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 4bdcf28f4..2933901c5 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. **各実行の前**: runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）はすべて自動的にセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションで次に実行するときは、完全な会話履歴が含まれるため、エージェントがコンテキストを維持できます。 +1. **各実行前**: Runner がセッションの会話履歴を自動で取得し、入力アイテムの先頭に追加します。 +2. **各実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出し など）がすべて自動でセッションに保存されます。 +3. **コンテキスト保持**: 同じセッションで後続の実行を行うたび、完全な会話履歴が入力に含まれるため、エージェントはコンテキストを維持できます。 -これにより、実行間で `.to_input_list()` を手動で呼び出したり会話状態を管理したりする必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 -## メモリー操作 +## メモリ操作 ### 基本操作 -セッションは会話履歴を管理するために、いくつかの操作をサポートしています: +セッションでは会話履歴を管理するための複数の操作をサポートしています。 ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### pop_item を使用した修正 +### 修正のための `pop_item` 利用 -会話の最後のアイテムを取り消したり修正したりしたい場合、`pop_item` メソッドが特に便利です: +`pop_item` メソッドは、会話の最後のアイテムを取り消しまたは修正したい場合に特に便利です。 ```python from agents import Agent, Runner, SQLiteSession @@ -117,16 +117,16 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリーオプション +## メモリ オプション -### メモリーなし（デフォルト） +### メモリなし (デフォルト) ```python # Default behavior - no session memory result = await Runner.run(agent, "Hello") ``` -### SQLite メモリー +### SQLite メモリ ```python from agents import SQLiteSession @@ -168,9 +168,9 @@ result2 = await Runner.run( ) ``` -## カスタムメモリー実装 +## 独自メモリ実装 -独自のセッションメモリーを実装するには、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッション メモリを実装できます。 ```python from agents.memory import Session @@ -216,17 +216,17 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすいわかりやすいセッション ID を使用してください: +会話を整理しやすい、意味のあるセッション ID を使用してください。 -- ユーザー単位: `"user_12345"` -- スレッド単位: `"thread_abc123"` -- コンテキスト単位: `"support_ticket_456"` +- ユーザー単位: `"user_12345"` +- スレッド単位: `"thread_abc123"` +- コンテキスト単位: `"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 @@ -316,9 +316,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## API 参照 +## 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 bbda87a2e..64f00b4cf 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、エージェントの実行が進行するにつれてその更新を購読できます。これはエンドユーザーに進捗状況や部分的なレスポンスを表示するのに便利です。 +ストリーミングを使用すると、エージェントの実行が進行するにつれて発生する更新を購読できます。これにより、エンドユーザーに進行状況の更新や部分的なレスポンスを表示するのに役立ちます。 -ストリーミングを行うには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、後述する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが取得できます。 +ストリームするには、`Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。返された `result.stream_events()` を呼び出すと、非同期で `StreamEvent` オブジェクトのストリームを取得できます。各オブジェクトの詳細は後述します。 -## Raw response events +## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API フォーマットであり、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。生成されたレスポンス メッセージを即座にユーザーへストリーミングしたい場合に便利です。 +`RawResponsesStreamEvent` は LLM から直接渡される raw なイベントです。これらは OpenAI Responses API 形式で提供されるため、各イベントは type（例: `response.created`, `response.output_text.delta` など）と data を持ちます。これらのイベントは、レスポンスメッセージが生成され次第ユーザーへストリーム配信したい場合に便利です。 -たとえば、次の例は LLM が生成したテキストをトークンごとに出力します。 +例えば、以下の例では LLM が生成したテキストをトークン単位で出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Run item イベントとエージェント イベント +## Run アイテムイベントとエージェントイベント -[`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 9dec164f3..55c1387e9 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行できるようにします。たとえばデータ取得、コード実行、外部 API 呼び出し、そしてコンピュータ操作などです。Agents SDK には 3 つのツールクラスがあります。 +ツールを使うと、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。Agents SDK には次の 3 種類のツールがあります。 -- ホスト型ツール: これらは LLM サーバー 上で AI モデルと一緒に動作します。OpenAI は retrieval、Web 検索、コンピュータ操作をホスト型ツールとして提供しています。 -- Function Calling: 任意の Python 関数 をツールとして利用できます。 -- エージェントをツールとして利用: エージェント をツールとして使用し、ハンドオフなしで他の エージェント を呼び出せます。 +- Hosted tools: LLM サーバー上で AI モデルと並行して動作するツールです。OpenAI は retrieval、web search、computer use を hosted tools として提供しています。 +- Function calling: 任意の Python 関数をツールとして利用できます。 +- Agents as tools: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せます。 -## ホスト型ツール +## Hosted tools -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。 +[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用すると、OpenAI がいくつかの組み込みツールを提供します。 -- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント が Web 検索 を行えます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストア から情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できます。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバー のツールをモデルに公開します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 +- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM にサンドボックス環境でコードを実行させます。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシン上でシェルコマンドを実行します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## 関数ツール +## Function tools -任意の Python 関数 をツールとして利用できます。Agents SDK が自動的にセットアップを行います。 +任意の Python 関数をツールとして利用できます。Agents SDK が自動でセットアップします。 -- ツール名は Python 関数 の名前になります（任意で指定も可能） -- ツール説明は関数の docstring から取得されます（任意で指定も可能） -- 関数入力のスキーマは関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り docstring から取得されます +- ツール名は Python 関数名になります（別名を指定することも可能）。 +- ツールの説明は関数の docstring から取得されます（別途指定も可能）。 +- 関数引数から入力スキーマを自動生成します。 +- 各入力の説明は、無効化しない限り docstring から取得します。 -内部では Python の `inspect` モジュールでシグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、スキーマ生成に `pydantic` を使用します。 +Python の `inspect` モジュールで関数シグネチャを取得し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、`pydantic` でスキーマを生成します。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型 を使用でき、同期・非同期のどちらでも構いません。 -2. docstring が存在する場合、説明文および引数説明を抽出します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。また、ツール名・説明・docstring スタイルなどのオーバーライドを設定できます。 -4. デコレートした関数を tools のリストに渡せます。 +1. 任意の Python 型を引数に使用でき、関数は sync／async どちらでも構いません。 +2. Docstring があれば、ツールと各引数の説明を取得します。 +3. 関数は任意で `context`（先頭の引数）を受け取れます。また、ツール名や説明、docstring スタイルなどを上書き設定できます。 +4. デコレートした関数をツールのリストに渡せます。 -??? note "出力を表示するには展開" +??? note "展開して出力を表示" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### カスタム関数ツール +### カスタム function tool -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 文字列を受け取り、ツールの出力文字列を返す async 関数） ```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` にすると解析を無効化できます。 +1. シグネチャ解析は `inspect` を使用します。型アノテーションから引数型を理解し、動的に Pydantic モデルを組み立てます。Python プリミティブ型、Pydantic モデル、TypedDict など多くの型をサポートします。 +2. Docstring 解析には `griffe` を使用します。対応フォーマットは `google`、`sphinx`、`numpy` です。自動検出を試みますが、`function_tool` 呼び出し時に明示的に設定もできます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## ツールとしてのエージェント +## Agents as tools -いくつかのワークフローでは、ハンドオフせずに中心となる エージェント が専門 エージェント のネットワークをオーケストレーションしたい場合があります。エージェント をツールとしてモデル化することでこれが可能です。 +ワークフローによっては、ハンドオフせずに中央エージェントが専門エージェント群をオーケストレーションしたい場合があります。その際はエージェントをツールとしてモデル化できます。 ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツールエージェントのカスタマイズ +### ツール化したエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント を簡単にツール化するための便利メソッドです。ただしすべての設定をサポートするわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください。 +`agent.as_tool` はエージェントを簡単にツール化するための便利メソッドです。ただし全設定に対応しているわけではなく、たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接呼び出してください。 ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 出力抽出のカスタマイズ +### 出力のカスタム抽出 -場合によっては、ツールエージェント の出力を中央 エージェント に返す前に加工したいことがあります。たとえば以下のようなケースです。 +場合によっては、ツール化したエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば次のようなケースです。 -- サブエージェント のチャット履歴から特定情報（例: JSON ペイロード）を抽出したい -- エージェント の最終回答を変換・再フォーマットしたい（例: Markdown をプレーンテキストや CSV に変換） -- 出力を検証し、エージェント の応答が欠落・不正な場合にフォールバック値を提供したい +- サブエージェントのチャット履歴から特定情報（例: JSON ペイロード）のみ抽出したい。 +- エージェントの最終回答を別形式に変換したい（例: Markdown をプレーンテキストや CSV に変換）。 +- 出力を検証し、不足または不正な場合にフォールバック値を返したい。 -これらは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます。 +その場合は `as_tool` メソッドに `custom_output_extractor` 引数を渡します。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -315,12 +315,33 @@ json_tool = data_agent.as_tool( ) ``` -## 関数ツールのエラー処理 +## function tools のエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これはツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを返す関数です。 +`@function_tool` で function tool を作成するとき、`failure_error_function` を指定できます。これはツール呼び出しがクラッシュした場合に LLM へ渡すエラーレスポンスを生成する関数です。 -- 既定では何も渡さない場合、`default_tool_error_function` が実行され、LLM にエラーが発生したことを通知します。 -- 独自のエラー関数を渡した場合はそれが実行され、その結果が LLM に送信されます。 -- 明示的に `None` を渡すと、ツール呼び出しエラーが再送出されます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などになります。 +- 省略した場合は `default_tool_error_function` が実行され、LLM にエラー発生を通知します。 +- 独自のエラーファンクションを渡すと、それが実行されて LLM に返されます。 +- 明示的に `None` を渡すと、ツール呼び出しエラーは再スローされます。このとき、モデルが不正な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などが発生します。 -手動で `FunctionTool` オブジェクトを作成する場合、`on_invoke_tool` 関数内でエラー処理を行う必要があります。 \ No newline at end of file +```python +from agents import function_tool, RunContextWrapper +from typing import Any + +def my_custom_error_function(context: RunContextWrapper[Any], error: Exception) -> str: + """A custom function to provide a user-friendly error message.""" + print(f"A tool call failed with the following error: {error}") + return "An internal server error occurred. Please try again later." + +@function_tool(failure_error_function=my_custom_error_function) +def get_user_profile(user_id: str) -> str: + """Fetches a user profile from a mock API. + This function demonstrates a 'flaky' or failing API call. + """ + if user_id == "user_123": + return "User profile for user_123 successfully retrieved." + else: + raise ValueError(f"Could not retrieve profile for user_id: {user_id}. API returned an error.") + +``` + +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 907975829..9d440efad 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェント実行中に発生する LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまで、包括的なイベント履歴を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を利用すると、開発時および本番環境でワークフローをデバッグ・可視化・監視できます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントなどを包括的に記録します。開発中および本番環境で [Traces ダッシュボード](https://platform.openai.com/traces) を使ってワークフローをデバッグ・可視化・モニタリングできます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。 + トレーシングはデフォルトで有効です。無効化する方法は 2 つあります： - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してトレーシングをグローバルに無効化する - 2. 1 回の実行のみ無効化する場合は [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する + 2. 単一の実行に対しては [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する -***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシー下で利用している組織では、トレーシングは利用できません。*** -## トレースと Span +## トレースとスパン -- **トレース**: 「ワークフロー」全体のエンドツーエンドの処理を表します。複数の Span で構成され、以下のプロパティを持ちます。 - - `workflow_name`: 論理的なワークフロー／アプリ名。例:「コード生成」「カスタマーサービス」 - - `trace_id`: トレースの一意 ID。未指定の場合は自動生成されます。フォーマットは `trace_<32_alphanumeric>` - - `group_id`: オプションのグループ ID。同一会話からの複数トレースを関連付ける際に使用します（例: チャットスレッド ID） - - `disabled`: `True` の場合、このトレースは記録されません - - `metadata`: トレースに付与するオプションのメタデータ -- **Span**: 開始時刻と終了時刻を持つ処理単位を表します。 +- **トレース** は 1 つの「ワークフロー」のエンドツーエンドの操作を表します。複数のスパンで構成されます。トレースには次のプロパティがあります： + - `workflow_name`：論理的なワークフローまたはアプリ名。例：`"Code generation"` や `"Customer service"` + - `trace_id`：トレースの一意 ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` + - `group_id`：省略可。同一会話からの複数トレースを結び付けるための ID。たとえばチャットスレッド ID など + - `disabled`：`True` の場合、このトレースは記録されません + - `metadata`：省略可。トレースに付随するメタデータ +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります： - `started_at` と `ended_at` タイムスタンプ - 所属するトレースを示す `trace_id` - - 親 Span を指す `parent_id`（存在する場合） - - Span に関する情報を格納する `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など + - 親スパンを指す `parent_id`（存在する場合） + - スパンに関する情報を含む `span_data`。例：`AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など -## 既定のトレーシング +## デフォルトのトレーシング -デフォルトで SDK は以下をトレースします。 +デフォルトでは SDK が以下をトレースします： -- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ -- エージェント実行ごとに `agent_span()` でラップ -- LLM 生成を `generation_span()` でラップ -- 関数ツール呼び出しを `function_span()` でラップ -- ガードレールを `guardrail_span()` でラップ -- ハンドオフを `handoff_span()` でラップ -- 音声入力（音声→テキスト）を `transcription_span()` でラップ -- 音声出力（テキスト→音声）を `speech_span()` でラップ -- 関連する音声 Span は `speech_group_span()` の下に階層化される場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ +- エージェント実行ごとに `agent_span()` でラップ +- LLM 生成は `generation_span()` でラップ +- 関数ツール呼び出しは `function_span()` でラップ +- ガードレールは `guardrail_span()` でラップ +- ハンドオフは `handoff_span()` でラップ +- 音声入力（音声→テキスト）は `transcription_span()` でラップ +- 音声出力（テキスト→音声）は `speech_span()` でラップ +- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります -デフォルトではトレース名は「Agent workflow」です。`trace` を使用すればこの名前を設定でき、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを設定することも可能です。 +デフォルトではトレース名は `"Agent workflow"` です。`trace` を使用する際に名前を指定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを設定できます。 -さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors) を設定することで、トレースを別の送信先へ（置き換えまたは追加で）送ることができます。 +さらに、[カスタム トレーシングプロセッサー](#custom-tracing-processors) を設定して、別の送信先へトレースをプッシュする（置き換え・追加のいずれも可）ことができます。 -## 高レベルトレース +## より上位のトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `trace()` でラップしてください。 ```python from agents import Agent, Runner, trace @@ -64,48 +64,48 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` に包まれているため、それぞれが個別のトレースを生成する代わりに 1 つのトレースにまとめられます。 +1. `Runner.run` への 2 回の呼び出しは `with trace()` に包まれているため、個別のトレースを作成せず、全体トレースの一部になります。 ## トレースの作成 -トレースは [`trace()`][agents.tracing.trace] 関数で作成できます。開始と終了が必要で、方法は 2 通りあります。 +[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。開始と終了が必要で、方法は 2 通りあります： -1. **推奨**: コンテキストマネージャーとして使用する（例: `with trace(...) as my_trace`）。開始と終了が自動で行われます。 -2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出す +1. **推奨**：コンテキストマネージャとして使用し、`with trace(...) as my_trace` とする。適切なタイミングで自動的に開始・終了します。 +2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理でも自動で機能します。手動で開始／終了する場合は `start()` と `finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新する必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理でも自動的に機能します。手動で開始・終了する場合は、`start()`／`finish()` に `mark_as_current` と `reset_current` を指定して現在のトレースを更新してください。 -## Span の作成 +## スパンの作成 -各種 [`*_span()`][agents.tracing.create] メソッドで Span を作成できますが、通常は手動で作成する必要はありません。カスタム Span 情報を追跡するために [`custom_span()`][agents.tracing.custom_span] も利用できます。 +さまざまな [`*_span()`][agents.tracing.create] メソッドでスパンを作成できますが、通常は手動での作成は不要です。カスタム情報を追跡したい場合は [`custom_span()`][agents.tracing.custom_span] を利用できます。 -Span は自動的に現在のトレースに属し、最も近い現在の Span の下にネストされます。こちらも Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 +スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これも 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] を作成し、トレースの生成を担当します。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース／Span をバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] へ送信します。Exporter は OpenAI バックエンドへバッチ送信を行います。 +- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、これがトレースを生成 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、バッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] へスパン／トレースを送信して OpenAI バックエンドにエクスポート -このデフォルト構成をカスタマイズして、別の送信先へトレースを送る、または Exporter の動作を変更する場合は以下の 2 つの方法があります。 +デフォルト設定を変更して他のバックエンドへ送信したり、エクスポーターの挙動を変更したりするには次の 2 つの方法があります： 1. [`add_trace_processor()`][agents.tracing.add_trace_processor] - 既存構成に **追加** のトレースプロセッサーを登録します。OpenAI バックエンドへの送信に加えて独自処理を行えます。 + 既存の送信に **追加** でトレースプロセッサーを登録し、OpenAI バックエンドへの送信に加えて独自処理を行えます。 2. [`set_trace_processors()`][agents.tracing.set_trace_processors] - 既定のプロセッサーを置き換え、独自のトレースプロセッサーを **設定** します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります。 + デフォルトプロセッサーを **置き換え** て独自プロセッサーのみを使用します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含めてください。 ## 非 OpenAI モデルでのトレーシング -OpenAI API キーを使って非 OpenAI モデルを呼び出す場合でも、トレーシングを無効化せずに OpenAI Traces ダッシュボードで無償トレースを有効化できます。 +OpenAI API キーを使用して非 OpenAI モデルでもトレーシングを有効化できます。これによりトレーシングを無効化せずに OpenAI Traces ダッシュボードで無料トレースを確認できます。 ```python import os @@ -126,16 +126,16 @@ agent = Agent( ) ``` -## 備考 -- 無償トレースは OpenAI Traces ダッシュボードで確認できます。 +## 注意 +- 無料トレースは OpenAI Traces ダッシュボードで閲覧できます。 ## 外部トレーシングプロセッサー一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [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) +- [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) diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index d83f77a9b..c075bc645 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,11 +4,11 @@ search: --- # エージェント可視化 -エージェント可視化を使用すると、 Graphviz を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化を使用すると、 **Graphviz** を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、およびハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存関係グループをインストールします: +オプションの `viz` 依存グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェント可視化を生成できます。この関数は有向グラフを作成し、以下のように要素を表現します。 +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は以下のような有向グラフを作成します: -- **エージェント**: 黄色いボックス -- **MCP サーバー**: 灰色のボックス -- **ツール**: 緑色の楕円 -- **ハンドオフ**: エージェント間を結ぶ有向エッジ +- **エージェント** は黄色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** は一方のエージェントから別のエージェントへ向かう有向エッジで表されます。 ### 使用例 @@ -69,34 +69,33 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、 **triage agent** の構造とサブエージェントやツールへの接続を視覚的に表現したグラフが生成されます。 - +これにより、 **triage エージェント** の構造とそのサブエージェントおよびツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されたグラフには次の要素が含まれます。 +生成されたグラフには以下が含まれます: - エントリーポイントを示す **開始ノード** (`__start__`) - 黄色で塗りつぶされた **長方形** で表されるエージェント - 緑色で塗りつぶされた **楕円** で表されるツール -- 灰色で塗りつぶされた **長方形** で表される MCP サーバー +- 灰色で塗りつぶされた **長方形** で表される **MCP サーバー** - 相互作用を示す有向エッジ - - エージェント間のハンドオフには **実線矢印** - - ツール呼び出しには **点線矢印** - - MCP サーバー呼び出しには **破線矢印** -- 実行終了を示す **終了ノード** (`__end__`) + - **実線の矢印** はエージェント間のハンドオフ + - **点線の矢印** はツール呼び出し + - **破線の矢印** は MCP サーバー呼び出し +- 実行の終了地点を示す **終了ノード** (`__end__`) ## グラフのカスタマイズ ### グラフの表示 -既定では、 `draw_graph` はグラフをインラインで表示します。別ウィンドウで表示するには、次のように記述します。 +既定では、`draw_graph` はグラフをインラインで表示します。別ウィンドウで表示したい場合は、次のようにします: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -既定では、 `draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します。 +既定では、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 53bf968ed..9bb66ec07 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント ベースのワークフローを音声アプリへ簡単に変換できるクラスです。実行したいワークフローを渡すだけで、パイプラインが入力音声の書き起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を再び音声へ変換する処理を自動で行います。 +`VoicePipeline` は、エージェント的なワークフローを音声アプリへ簡単に変換するためのクラスです。ワークフローを渡すだけで、入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理を自動で行います。 ```mermaid graph LR @@ -34,36 +34,31 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際には、次の項目を設定できます。 +パイプラインを作成するとき、次の項目を設定できます: -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] - 新しい音声が書き起こされるたびに実行されるコードです。 -2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] の各モデル -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - 次のような内容を設定できます。 - - モデル名をモデルにマッピングするモデルプロバイダー - - トレーシングの有効／無効、音声ファイルのアップロード有無、ワークフロー名、トレース ID など - - TTS・STT モデルのプロンプト、言語、データ型などの設定 +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] — 新しい音声が文字起こしされるたびに実行されるコード。 +2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] の各モデル。 +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] — 以下のような設定を行えます。 + - モデルプロバイダー: モデル名をモデルにマッピングします + - トレーシング: トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など + - TTS と STT モデルの設定: プロンプト、言語、データ型など ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 通りの形式で渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 つの形式で渡せます: 1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声の書き起こしがある場合に使用します。話者がいつ話し終えたかを検出する必要がない、たとえば事前録音された音声やプッシュトゥトーク アプリなどに適しています。 + 完全な音声ファイルがあり、その文字起こしに対して結果だけを生成したい場合に使用します。話者がいつ話し終えたかを検知する必要がないケース、たとえば事前録音された音声やユーザーが話し終えるタイミングが明確なプッシュ・トゥ・トーク アプリで便利です。 2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] - 話者が話し終えたタイミングを検出する必要がある場合に使用します。検出された音声チャンクを順次プッシュでき、パイプラインが「アクティビティ検出」と呼ばれる処理を通じて適切なタイミングでエージェント ワークフローを自動実行します。 + ユーザーが話し終えたタイミングを検知する必要がある場合に使用します。音声チャンクを検知し次第プッシュでき、パイプラインが「アクティビティ検知」により適切なタイミングでエージェント ワークフローを自動実行します。 -## 実行結果 +## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] オブジェクトです。これは発生するイベントをストリーミングで受け取れるオブジェクトで、いくつかの [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] 種類があります。 +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。このオブジェクトはイベントをストリーム形式で受け取るためのものです。イベントの型 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] には以下があります。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] - 音声チャンクを含むイベント -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] - ターン開始・終了などのライフサイクル イベントを知らせるイベント -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] - エラー イベント +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] — 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] — ターン開始や終了といったライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] — エラーイベントです。 ```python @@ -81,6 +76,6 @@ 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 a61c6ce39..a654fbfc4 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -まず、Agents SDK の基本 [quickstart instructions](../quickstart.md) に従って仮想環境をセットアップしていることを確認してください。次に、SDK から音声用のオプション依存関係をインストールします。 +まず、Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。その後、SDK から追加の音声依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -ここで押さえておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、3 段階のプロセスです。 +ここで覚えておくべき主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは次の 3 ステップのプロセスになります。 -1. 音声をテキストに変換するために speech-to-text モデルを実行します。 -2. 通常はエージェント的 workflow であるあなたのコードを実行し、結果を生成します。 -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 6556a280c..e6231442f 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]：トレースワークフローの名前です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]：複数のトレースをリンクできる `group_id` です。 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：音声の文字起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプラインに限定され、ワークフロー内部には影響しません。 +- [`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