diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 467f61a52..115689b62 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中心的な構成要素です。エージェントとは、instructions と tools で設定された大規模言語モデル (LLM) です。 +エージェントはアプリの中核となる構成要素です。エージェントは、指示とツールで構成された大規模言語モデル（ LLM ）です。 ## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +エージェントでよく設定するプロパティは次のとおりです。 -- `name`：エージェントを識別する必須の文字列。 -- `instructions`：開発者メッセージ、または system prompt とも呼ばれます。 -- `model`：使用する LLM。さらに `model_settings` で temperature や top_p などのモデル調整パラメーターを設定できます。 -- `tools`：エージェントがタスクを達成するために使用できるツール群。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: 開発者メッセージまたはシステムプロンプトとも呼ばれます。 +- `model`: 使用する LLM と、任意の `model_settings` を指定します（ temperature、 top_p などのモデル調整パラメーター）。 +- `tools`: エージェントがタスクを達成するために使用できるツール。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型についてジェネリックです。Context は依存性注入のための道具で、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、tool、handoff などに渡され、実行中の依存関係や状態をまとめて保持します。任意の Python オブジェクトを context として渡せます。 +エージェントは `context` の型に対してジェネリックです。コンテキストは依存性注入のためのツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態の入れ物として機能します。コンテキストには任意の Python オブジェクトを指定できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト (つまり `str`) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使います。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型 ― dataclass、list、TypedDict など ― であれば利用可能です。 +デフォルトでは、エージェントはプレーンテキスト（すなわち `str`）を出力します。特定の型の出力が必要な場合は、`output_type` パラメーターを使用できます。一般的には [Pydantic](https://docs.pydantic.dev/) のオブジェクトを使いますが、 Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型であれば、 dataclasses、 lists、 TypedDict など、どれでもサポートします。 ```python from pydantic import BaseModel @@ -73,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキストの代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 + `output_type` を渡すと、通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようモデルに指示します。 ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは必要に応じてそこへ委譲できます。これにより、単一タスクに特化したモジュール化されたエージェントを編成できる強力なパターンが実現します。詳細は [handoffs](handoffs.md) ドキュメントを参照してください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、状況に応じてエージェントがそれらへ委譲できます。これは、単一のタスクに秀でたモジュール式の専門エージェントをオーケストレーションする強力なパターンです。詳しくは [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -96,9 +96,9 @@ triage_agent = Agent( ) ``` -## 動的 instructions +## 動的な指示 -多くの場合、エージェント作成時に instructions を指定しますが、関数経由で動的に渡すこともできます。この関数は agent と context を受け取り、プロンプトを返さなければなりません。同期関数と `async` 関数の両方を使用できます。 +多くの場合、エージェント作成時に指示を指定できます。ただし、関数経由で動的な指示を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも利用できます。 ```python def dynamic_instructions( @@ -113,17 +113,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクルイベント（フック） -エージェントのライフサイクルを観測したい場合があります。たとえば、イベントをログに残したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティでライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、必要なメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観察したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりできます。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、必要なメソッドをオーバーライドしてください。 ## ガードレール -ガードレールを使用すると、エージェントの実行と並行してユーザー入力のチェックやバリデーションを実行できます。たとえば、ユーザー入力の関連性をフィルタリングできます。詳細は [guardrails](guardrails.md) ドキュメントを参照してください。 +ガードレールは、エージェントの実行と並行して、ユーザー入力に対するチェック/バリデーションを実行できます。たとえば、ユーザーの入力が関連しているかどうかをスクリーニングできます。詳しくは [ガードレール](guardrails.md) のドキュメントをご覧ください。 -## エージェントのクローン／コピー +## エージェントのクローン/コピー -エージェントの `clone()` メソッドを使うと、エージェントを複製し、任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使うと、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -140,12 +140,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、必ずしも 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 にツール使用を必須とします (どのツールを使うかは LLM が判断)。 -3. `none`：LLM にツールを使用しないことを要求します。 -4. 特定の文字列 (例: `my_tool`) を設定すると、そのツールを必ず使用させます。 +1. `auto`、 LLM がツールを使うかどうかを判断します。 +2. `required`、 LLM にツールの使用を要求します（ただし、どのツールを使うかは賢く選べます）。 +3. `none`、 LLM にツールを _使用しない_ ように要求します。 +4. 特定の文字列（例: `my_tool`）を設定し、その特定のツールを LLM に使用させます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -163,11 +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 @@ -185,7 +185,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`：指定したいずれかのツールが呼び出された時点で停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したいずれかのツールが呼び出されたら停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool from agents.agent import StopAtTools @@ -206,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 @@ -245,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` により LLM がさらに別のツール呼び出しを生成し続けてしまうためです。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 1fab3bc45..42fb8f7ab 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 は環境変数の API キー、または上で設定したデフォルト キーを使って `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 つあります。デフォルトでは warning と error が `stdout` に送られ、それ以外のログは抑制されます。 +SDK には、ハンドラーが設定されていない Python のロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られますが、その他のログは抑制されます。 -詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 +詳細なロギングを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -ログをカスタマイズしたい場合は、ハンドラー・フィルター・フォーマッターなどを追加できます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) をご覧ください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳しくは [Python のロギングガイド](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 71969563c..ac71085a2 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語には複数の意味があります。ここでは、意識するべきコンテキストの主なクラスは 2 つあります。 +コンテキストという語は多義的です。ここで重要になるコンテキストは大きく 2 つに分けられます: -1. コード内でローカルに利用できるコンテキスト: ツール関数の実行時や `on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 -2. LLMs が利用できるコンテキスト: 応答を生成するときに LLM が参照できるデータです。 +1. あなたのコードでローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック内、ライフサイクルフック内などで必要になるデータや依存関係です。 +2. LLM から利用できるコンテキスト: 応答を生成する際に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです: -1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使うパターンがよく見られます。 -2. そのオブジェクトを各種 run メソッド（例: `Runner.run(..., context=whatever)`）に渡します。 -3. すべてのツール呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的なパターンは、 dataclass や Pydantic オブジェクトを使うことです。 +2. そのオブジェクトを各種の実行メソッドに渡します (例えば `Runner.run(..., **context=whatever**))`)。 +3. すべてのツール呼び出しやライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はあなたのコンテキストオブジェクトの型を表し、`wrapper.context` から参照できます。 -**最も重要** なのは、1 回のエージェント実行においては、すべてのエージェント、ツール関数、ライフサイクルフックが同じ _型_ のコンテキストを使用しなければならない点です。 +最も注意すべき **最も重要** な点: 特定のエージェント実行に関わるすべてのエージェント、ツール関数、ライフサイクルなどは、同じ _型_ のコンテキストを使わなければなりません。 -コンテキストは次のような用途で利用できます。 +コンテキストは次の用途に使えます: -- 実行に関するコンテキストデータ（例: ユーザー名や UID などのユーザー情報） -- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） -- ヘルパー関数 +- 実行用のコンテキストデータ (例えば、ユーザー名 / uid やユーザーに関するその他の情報) +- 依存関係 (例えば、ロガーのオブジェクト、データ取得処理など) +- ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは **LLM には送信されません**。あくまでローカルオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に **送信されません**。あくまでローカルなオブジェクトであり、読み取り・書き込みやメソッド呼び出しができます。 ```python import asyncio @@ -66,21 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを読み取ります。 -3. 型チェッカーでエラーを捕捉できるよう、エージェントにジェネリック型 `UserInfo` を指定しています（例として、異なるコンテキスト型を期待するツールを渡した場合など）。 -4. `run` 関数にコンテキストを渡しています。 -5. エージェントはツールを正しく呼び出し、年齢を取得します。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることが分かります。ツールの実装はコンテキストから読み取ります。 +3. エージェントにジェネリックな `UserInfo` を付けることで、型チェッカーが誤りを検出できます (例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など)。 +4. コンテキストは `run` 関数に渡されます。 +5. エージェントは正しくツールを呼び出し、年齢を取得します。 -## エージェント／ LLM コンテキスト +## エージェント / LLM コンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴に含まれるもの **のみ** です。そのため、新しいデータを LLM に提供したい場合は、そのデータが履歴に含まれるようにする必要があります。代表的な方法は次のとおりです。 +LLM を呼び出したとき、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 が必要に応じてツールを呼び出し、データを取得できます。 -4. retrieval や Web 検索を利用する - - retrieval はファイルやデータベースから、Web 検索はウェブ上から関連データを取得できる特殊なツールです。応答を適切なコンテキストに基づいて「グラウンディング」するのに役立ちます。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「システムプロンプト」や「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列にも、コンテキストを受け取って文字列を出力する動的な関数にもできます。常に有用な情報 (例えばユーザー名や現在の日付) に適した方法です。 +2. `Runner.run` を呼び出す際の `input` に追加します。これは `instructions` を使う方法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 上でより下位のメッセージとして配置できます。 +3. 関数ツールとして公開します。これは _オンデマンド_ コンテキストに有用です。LLM が必要なときにデータを判断し、そのデータを取得するためにツールを呼び出せます。 +4. リトリーバルや Web 検索を使います。これらは、ファイルやデータベース (リトリーバル) から、または Web (Web 検索) から関連データを取得できる特別なツールです。応答を関連するコンテキストデータで「根拠付け (grounding)」するのに役立ちます。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 4700e494d..d976d21a8 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,44 +4,45 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでは、SDK の多彩なサンプル実装をご覧いただけます。これらのコード例は、さまざまなパターンや機能を示すいくつかのカテゴリーに整理されています。 +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 + ## カテゴリー -- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーのコード例は、一般的なエージェント設計パターンを説明します。例えば、 +- **[エージェントパターン (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 + - 動的なシステムプロンプト - ストリーミング出力 - ライフサイクルイベント -- **[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 (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 エージェントのコード例をご覧ください。 +- **[音声 (voice)](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + 音声エージェントのコード例をご覧ください。TTS と STT モデルを使用しています。 -- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使用してリアルタイム体験を構築する方法を示すコード例です。 \ No newline at end of file +- **[リアルタイム (realtime)](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使ってリアルタイムな体験を構築する方法を示すコード例。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index c8d7f2954..61605a170 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` プロパティがエージェント側にあるのは、ガードレールがそれぞれのエージェントに深く関係しており、エージェントごとに異なるガードレールを走らせるため、同じ場所にコードを置くほうが読みやすいからです。 + 入力ガードレールはユーザー入力での実行を意図しているため、エージェントが *最初の* エージェントである場合にのみ、そのエージェントのガードレールが実行されます。`guardrails` プロパティがエージェント側にあり、`Runner.run` に渡されないのはなぜだろう、と思うかもしれません。これは、ガードレールが実際のエージェントに関係することが多いためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に配置すると可読性が向上します。 ## 出力ガードレール -出力ガードレールも 3 ステップで実行されます。 +出力ガードレールは 3 ステップで実行されます: -1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次にガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップします。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外を送出し、ユーザーへの応答や例外処理を行えます。 +1. まず、ガードレールはエージェントが生成した出力を受け取ります。 +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 @@ -94,10 +94,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力／コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果に追加情報を含めることができます。 -4. これはワークフローを定義する実際のエージェントです。 +1. このエージェントをガードレール関数で使用します。 +2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレールの結果に追加情報を含められます。 +4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. これは実際のエージェントの出力型です。 -2. これはガードレールの出力型です。 -3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 +1. これは実際のエージェントの出力型です。 +2. これはガードレールの出力型です。 +3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 3cbedfeae..77dce60a8 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# ハンドオフ +# Handoffs -ハンドオフを使用すると、あるエージェントがタスクを別のエージェントに委任できます。これは、異なるエージェントがそれぞれ特定分野を専門とするシナリオで特に便利です。たとえばカスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ担当するエージェントが存在する場合があります。 +Handoffs は、エージェントが別のエージェントにタスクを委譲できるようにします。これは、異なるエージェントがそれぞれ異なる領域に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、 FAQ などのタスクを個別に担当するエージェントがいるかもしれません。 -ハンドオフは LLM に対してツールとして表現されます。そのため `Refund Agent` という名前のエージェントへハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +Handoffs は LLM にはツールとして表現されます。そのため、`Refund Agent` という名前のエージェントへハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] というパラメーターがあり、直接 `Agent` を渡すことも、ハンドオフをカスタマイズした `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは直接 `Agent` を受け取るか、ハンドオフをカスタマイズする `Handoff` オブジェクトを受け取れます。 - Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、さらにオーバーライドや入力フィルターをオプションで設定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、任意のオーバーライドや入力フィルターを設定できます。 ### 基本的な使い方 -シンプルなハンドオフを作成する方法は次のとおりです。 +シンプルなハンドオフの作り方は次のとおりです。 ```python from agents import Agent, handoff @@ -28,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェントを直接指定する方法（ `billing_agent` など）と、 `handoff()` 関数を使用する方法のどちらも利用できます。 +1. エージェントを直接使う方法（`billing_agent` のように）と、`handoff()` 関数を使う方法のどちらでも構いません。 -### `handoff()` 関数によるハンドオフのカスタマイズ +### `handoff()` 関数による handoffs のカスタマイズ - [`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが行えます。 +[`handoff()`][agents.handoffs.handoff] 関数でカスタマイズできます。 -- `agent`: ハンドオフ先となるエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` という名前になります。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` から生成される既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが発生した時点でデータ取得を開始するなどの用途に便利です。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフで想定される入力の型（オプション）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングします。詳細は後述します。 +- `agent`: ハンドオフ先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使われ、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが起動されることが分かった時点でデータ取得を開始する、といった用途に便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフが受け取る想定の入力の型（任意）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。 ```python from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフ入力 +## ハンドオフの入力 -状況によっては、ハンドオフを呼び出すときに LLM から追加データを渡したい場合があります。たとえば「 Escalation agent 」へのハンドオフを考えてみましょう。ログに記録できるよう、理由を渡してほしいことがあります。 +状況によっては、ハンドオフを呼び出す際に LLM からいくつかのデータを提供してほしいことがあります。たとえば、「エスカレーション エージェント」へのハンドオフを想定してください。記録のために理由を受け取りたい、ということがあるでしょう。 ```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`][] を呼び出すことで、推奨データを自動的にプロンプトへ追加できます。 +LLMs が handoffs を正しく理解できるように、エージェントに handoffs に関する情報を含めることをおすすめします。[`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 57a3f952d..cb0e02a9a 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 アプリを構築できるようにします。本 SDK は、以前にエージェント向けに実験していた [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化が非常に少ない、軽量で使いやすいパッケージで、エージェント型 AI アプリの構築を可能にします。これは、エージェント に関する以前の実験である [Swarm](https://github.com/openai/swarm/tree/main) をプロダクション対応にアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります: -- **エージェント**：instructions と tools を備えた LLM -- **ハンドオフ**：特定のタスクを他のエージェントに委任できる機構 -- **ガードレール**：エージェントの入力と出力を検証する仕組み -- **セッション**：エージェント実行間で会話履歴を自動的に保持 +- ** エージェント **、instructions と tools を備えた LLM +- ** ハンドオフ **、エージェント が特定のタスクを他の エージェント に委譲できるようにする +- ** ガードレール **、エージェント の入力と出力の検証を可能にする +- ** セッション **、エージェント の実行全体で会話履歴を自動的に維持する -これらの基本コンポーネントは Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現し、急な学習コストなしに実際のアプリケーションを構築できます。さらに、SDK にはワークフローを可視化・デバッグできる組み込みの **トレーシング** が含まれており、評価やファインチューニングにも活用できます。 +Python と組み合わせることで、これらの基本コンポーネントはツールと エージェント 間の複雑な関係を表現できるほど強力になり、急な学習曲線なしに実運用アプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** が付属しており、エージェント フローの可視化やデバッグ、評価に加えて、アプリケーション向けにモデルをファインチューニングすることも可能です。 ## Agents SDK を使う理由 -SDK の設計原則は次の 2 つです。 +この SDK の設計原則は次の 2 つです: -1. 使う価値のある十分な機能を提供しつつ、学習が早いように基本コンポーネントを絞る。 -2. デフォルト設定で高いパフォーマンスを発揮しながら、挙動を細かくカスタマイズできる。 +1. 使う価値があるだけの機能は揃えつつ、基本コンポーネントを最小限にして素早く学べます。 +2. すぐにうまく動作しますが、実際に何が起きるかを正確にカスタマイズできます。 -主な機能は次のとおりです。 +この SDK の主な機能は次のとおりです: -- エージェントループ：ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループを自動で処理。 -- Python ファースト：新しい抽象概念を学ぶことなく、Python の言語機能でエージェントを編成・連携。 -- ハンドオフ：複数エージェント間の協調と委任を可能にする強力な機能。 -- ガードレール：エージェントと並行して入力検証を実行し、失敗時は早期に停止。 -- セッション：エージェント実行間の会話履歴を自動管理し、手動の状態管理を不要に。 -- 関数ツール：任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 -- トレーシング：ワークフローの可視化・デバッグ・モニタリングを行い、OpenAI の評価・ファインチューニング・蒸留ツールも利用可能。 +- エージェント ループ: ツールの呼び出し、結果を LLM に送る処理、そして LLM が完了するまでのループを扱う組み込みのエージェント ループ。 +- Python ファースト: 新しい抽象を学ぶ必要はなく、組み込みの言語機能で エージェント をオーケストレーションし、連鎖させられます。 +- ハンドオフ: 複数の エージェント 間の調整と委譲を可能にする強力な機能。 +- ガードレール: エージェント と並行して入力のバリデーションやチェックを実行し、失敗時は早期に中断。 +- セッション: エージェント の実行をまたいだ会話履歴を自動管理し、手動の状態管理を不要にします。 +- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と Pydantic によるバリデーションを提供。 +- トレーシング: ワークフローの可視化・デバッグ・モニタリングを可能にする組み込みのトレーシングに加え、評価、ファインチューニング、蒸留ツールを含む OpenAI のスイートを利用可能。 ## インストール @@ -36,7 +36,7 @@ SDK の設計原則は次の 2 つです。 pip install openai-agents ``` -## Hello World 例 +## Hello world の例 ```python from agents import Agent, Runner @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_このコードを実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください_) +(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定していることを確認してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 67db86528..acbf194b3 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,23 +4,23 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP ドキュメントより: +The [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 servers -現在、MCP 仕様では使用するトランスポートメカニズムに基づいて 3 種類のサーバーが定義されています。 +現在、MCP の仕様では、使用するトランスポート メカニズムに基づいて 3 種類のサーバーが定義されています: -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動作していると考えることができます。 -2. **HTTP over SSE** サーバー: リモートで動作し、URL を介して接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで動作します。 +1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。いわば「ローカル」で動作します。 +2. **HTTP over SSE** サーバーはリモートで実行されます。 URL 経由で接続します。 +3. **Streamable HTTP** サーバーは、MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーには [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の各クラスを使って接続できます。 -以下は、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を利用する例です。 +たとえば、[公式の MCP ファイルシステム サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)は次のように使います。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェントが実行されるたびに MCP サーバーの `list_tools()` を呼び出し、LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。 Agents SDK は、エージェントが実行されるたびに MCP サーバーで `list_tools()` を呼び出します。これにより、 LLM が MCP サーバーのツールを認識できるようになります。 LLM が MCP サーバーのツールを呼び出すと、 SDK はそのサーバーで `call_tool()` を呼び出します。 ```python @@ -52,13 +52,13 @@ agent=Agent( ) ``` -## ツールフィルタリング +## ツールのフィルタリング -MCP サーバーにツールフィルターを設定することで、エージェントが利用できるツールを制限できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーでツール フィルターを設定することで、エージェントで利用可能なツールを絞り込めます。 SDK は、静的および動的なツール フィルタリングの両方をサポートします。 -### 静的ツールフィルタリング +### 静的なツールのフィルタリング -単純な許可／ブロックリストには静的フィルタリングを使用できます。 +シンプルな許可/ブロック リストには、静的フィルタリングを使用できます: ```python from agents.mcp import create_static_tool_filter @@ -87,17 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合の処理順序:** +**両方の `allowed_tool_names` と `blocked_tool_names` が設定されている場合、処理順序は次のとおりです:** +1. まず `allowed_tool_names`（許可リスト）を適用 - 指定したツールのみを残します +2. 次に `blocked_tool_names`（ブロックリスト）を適用 - 残ったツールから指定したものを除外します -1. まず `allowed_tool_names`（許可リスト）を適用し、指定されたツールのみを保持 -2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定されたツールを除外 +例えば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定した場合、利用可能なのは `read_file` と `write_file` のツールだけです。 -例として、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と -`blocked_tool_names=["delete_file"]` を設定した場合、利用可能なのは `read_file` と `write_file` だけになります。 +### 動的なツールのフィルタリング -### 動的ツールフィルタリング - -より複雑なフィルタリングロジックには、関数を用いた動的フィルターを使用できます。 +より複雑なフィルタリング ロジックには、関数による動的フィルタリングを使用できます: ```python from agents.mcp import ToolFilterContext @@ -136,21 +134,21 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次の情報にアクセスできます。 -- `run_context`: 現在のランコンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +`ToolFilterContext` では次の情報にアクセスできます: +- `run_context`: 現在の実行コンテキスト +- `agent`: ツールを要求しているエージェント +- `server_name`: MCP サーバーの名前 ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成するためのプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instruction テンプレートを作成できます。 +MCP サーバーは、エージェントの指示を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な指示テンプレートを作成できます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを持ちます。 +プロンプトをサポートする MCP サーバーは、次の 2 つの主要なメソッドを提供します: -- `list_prompts()`: サーバー上で利用可能なプロンプトを一覧表示 -- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得 +- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示します +- `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得します ```python # List available prompts @@ -175,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、MCP サーバーの `list_tools()` が呼び出されます。サーバーがリモートの場合、これはレイテンシの原因となることがあります。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡してください。ツール一覧が変更されないことが確実な場合にのみ使用してください。 +エージェントが実行されるたびに、 MCP サーバーで `list_tools()` が呼び出されます。特にサーバーがリモートの場合、これはレイテンシに影響する可能性があります。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないと確信できる場合にのみこれを行ってください。 -キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出せます。 ## エンドツーエンドのコード例 -動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。 ## トレーシング -[トレーシング](./tracing.md) は MCP の操作を自動で記録します。内容は次のとおりです。 +[トレーシング](./tracing.md) は、以下を含む MCP の操作を自動的に記録します: -1. MCP サーバーへのツール一覧取得呼び出し -2. 関数呼び出しに関する MCP 関連情報 +1. ツールを一覧表示するための MCP サーバーへの呼び出し +2. 関数呼び出しに関する MCP 関連情報 -![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file +![MCP トレーシングのスクリーンショット](../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 29b4c466f..1b94eae36 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,52 +4,51 @@ 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 クライアントとしてグローバルに使用したい場合に便利です。 LLM プロバイダーが OpenAI 互換エンドポイントを持っており、 `base_url` と `api_key` を設定できるケースで使用します。設定例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] - `Runner.run` レベルで指定します。「この実行内のすべての エージェント でカスタムモデルプロバイダーを使う」と宣言できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] - 特定の Agent インスタンスに対してモデルを指定します。これにより、 エージェント ごとに異なるプロバイダーを組み合わせることができます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの既存モデルを簡単に使う方法としては、 LiteLLM 連携が便利です。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使いたい場合に便利です。LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより「この実行のすべてのエージェントでカスタムのモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] では、特定のエージェントインスタンスに対してモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使えます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) を利用するのが簡単です。 -`platform.openai.com` の API キーをお持ちでない場合は、 `set_tracing_disabled()` でトレーシングを無効にするか、 [別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 !!! note - これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、 Chat Completions API／モデルを使用しています。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、 Responses を利用することを推奨します。 + + これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions の API/モデルを使用しています。もしお使いの LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 ## モデルの組み合わせ -1 つのワークフロー内で、 エージェント ごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小規模で高速なモデルを、複雑なタスクには大規模で高性能なモデルを使う、といったケースです。 [`Agent`][agents.Agent] を設定する際、次のいずれかでモデルを選択できます。 +単一のワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえばトリアージには小さく高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使うといった形です。[`Agent`][agents.Agent] を設定する際は、次のいずれかの方法で特定のモデルを選択できます。 -1. モデル名を直接渡す。 -2. 任意のモデル名と、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 -3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 +1. モデル名を渡す。 +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 @@ -82,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデル名を直接指定しています。 -2. [`Model`][agents.models.interface.Model] 実装を提供しています。 +1. OpenAI モデルの名前を直接指定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに詳細に設定したい場合は、 `temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェントで使用するモデルをさらに詳細に設定したい場合は、`temperature` などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -98,7 +97,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` などの任意パラメーターを追加で指定できます。これらがトップレベルで指定できない場合は、`extra_args` を使って渡せます。 ```python from agents import Agent, ModelSettings @@ -114,28 +113,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー利用時によくある問題 +## 他の LLM プロバイダーを使用する際の一般的な問題 -### Tracing client error 401 +### トレーシング クライアント エラー 401 -トレーシングに関するエラーが発生する場合、トレースが OpenAI サーバーにアップロードされるため、 OpenAI API キーがないことが原因です。解決策は 3 つあります。 +トレーシング関連のエラーが出る場合、トレースは OpenAI のサーバーにアップロードされる一方で、OpenAI の API キーがないことが原因です。解決方法は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] - この API キーはトレースのアップロードのみに使用され、 [platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. 非 OpenAI のトレース プロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーはまだ対応していません。そのため 404 エラーなどが発生する場合があります。解決策は 2 つです。 +SDK は既定で Responses API を使用しますが、多くの他社 LLM プロバイダーはまだサポートしていません。その結果、404 エラーなどが発生することがあります。解決するには次のいずれかの方法を取ってください。 -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 サポート -一部のモデルプロバイダーは、 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 ``` @@ -143,12 +140,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 出力をサポートしないプロバイダーでは、無効な JSON が返ることがあります \ No newline at end of file +- サポートしていない `tools` を理解しないプロバイダーには送らない +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外する +- 構造化された JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 78591f5d8..6f0d0db53 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM 経由で任意のモデルを利用する +# LiteLLM 経由の任意モデルの利用 !!! note - LiteLLM インテグレーションはベータ版です。特に小規模なプロバイダーでは問題が発生する場合があります。問題を見つけた場合は [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応します。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生することがあります。問題があれば [Github の issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、1 つのインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM インテグレーションを追加したことで、どの AI モデルでも利用できるようになりました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK内で任意の AI モデルを利用できるように、 LiteLLM 統合を追加しました。 ## セットアップ -`litellm` が利用可能であることを確認する必要があります。これは、オプションの `litellm` 依存関係グループをインストールすることで行えます。 +`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで対応できます: ```bash pip install "openai-agents[litellm]" ``` -インストールが完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 ## 例 -以下は完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます。 +これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば、次のように入力できます: -- モデルに `openai/gpt-4.1`、API キーに OpenAI API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic API キー +- `openai/gpt-4.1` をモデルに、OpenAIの API キーを入力 +- `anthropic/claude-3-5-sonnet-20240620` をモデルに、 Anthropic の API キーを入力 - など -LiteLLM でサポートされているモデルの一覧については、[litellm providers docs](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM でサポートされているモデルの一覧は、[LiteLLM のプロバイダー ドキュメント](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 8027e6fd0..942588ef4 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -2,49 +2,40 @@ search: exclude: true --- -# 複数エージェントのオーケストレーション +# 複数の エージェント のオーケストレーション -オーケストレーションとは、アプリ内でエージェントがどのように実行されるか、その順序、そして次に何を行うかを決定するフローを指します。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内で エージェント がどのように流れるか（どの エージェント が、どの順序で実行され、次に何を行うかをどう判断するか）を指します。エージェント をオーケストレーションする主な方法は 2 つあります: -1. LLM に意思決定を任せる - これは LLM の知能を利用して計画や推論を行い、次に取るべきステップを決定します。 -2. コードによるオーケストレーション - コード側でエージェントのフローを制御します。 +1. LLM に意思決定させる: これは LLM の知能を用いて計画・推論し、それに基づいて次に取るステップを決定します。 +2. コードによるオーケストレーション: コードで エージェント の流れを決定します。 -これらのパターンは組み合わせて使用できます。それぞれに以下のようなトレードオフがあります。 +これらのパターンは組み合わせて使えます。どちらにもトレードオフがあり、以下で説明します。 -## LLM を用いたオーケストレーション +## LLM によるオーケストレーション -エージェントとは、instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はタスクを達成するための計画を自律的に立て、tools を使ってアクションを実行・データを取得し、handoffs を通じてサブエージェントにタスクを委任できます。たとえば、リサーチエージェントには次のような tools を持たせることができます。 +エージェント は、 instructions、 tools、ハンドオフ を備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的にタスクへの取り組み方を計画し、tools を使ってアクション実行やデータ取得を行い、ハンドオフ を使ってサブ エージェント にタスクを委任できることを意味します。例えば、リサーチ エージェント には次のようなツールを備えられます: -- Web 検索でオンライン情報を収集 -- ファイル検索と取得で独自データや接続先を検索 -- コンピュータ操作で PC 上のアクションを実行 -- コード実行でデータ分析を実施 -- 計画立案やレポート作成などを得意とする専門エージェントへの handoffs +- オンラインの情報を見つけるための Web 検索 +- 社内データや各種接続先を横断的に検索するための ファイル検索 と取得 +- コンピュータ上でアクションを実行するための コンピュータ操作 +- データ分析のためのコード実行 +- 計画立案、レポート作成などに長けた特化型 エージェント へのハンドオフ -このパターンはタスクがオープンエンドで、LLM の知能に依存したい場合に最適です。重要なポイントは次のとおりです。 +このパターンは、タスクがオープンエンドで、 LLM の知能に依拠したい場合に有効です。重要なポイントは次のとおりです: -1. 良いプロンプトに投資する - 利用可能な tools、使用方法、動作パラメーターを明示します。 -2. アプリを監視して改善する - 問題が発生した箇所を確認し、プロンプトを繰り返し改善します。 -3. エージェントに内省と改善を許可する - 例としてループで実行し、自己批評させたり、エラーメッセージを渡して改善させたりします。 -4. 何でもこなせる汎用エージェントより、特定タスクに特化したエージェントを用意する -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する - これによりエージェントを学習・改善し、タスク遂行能力を高められます。 +1. 良いプロンプトに投資しましょう。利用可能な tools、使い方、どのパラメーター範囲で動作すべきかを明確にします。 +2. アプリをモニタリングし、継続的に改善します。どこで問題が起きるかを観察し、プロンプトを反復改善します。 +3. エージェント に内省と改善を促します。例えば、ループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 +4. なんでもこなす汎用 エージェント を 1 つ持つのではなく、特定のタスクに秀でた特化型 エージェント を用意します。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資しましょう。これにより、エージェント を訓練して改善し、タスク遂行能力を高められます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の面でより決定論的かつ予測可能になります。代表的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・パフォーマンスの観点で、タスクをより決定的かつ予測可能にします。ここでの一般的なパターンは次のとおりです: -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使い、コードで検査できる適切な形式のデータを生成する - 例として、エージェントにタスクを複数のカテゴリーに分類させ、カテゴリーに応じて次のエージェントを選択します。 -- あるエージェントの出力を次のエージェントの入力に変換して複数エージェントを連鎖させる - ブログ記事作成のタスクを、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善といった一連のステップに分解できます。 -- タスクを実行するエージェントを `while` ループで回し、別のエージェントが評価とフィードバックを行い、評価者が基準を満たしたと判断するまで繰り返す -- `asyncio.gather` など Python の基本コンポーネントを用いて複数エージェントを並列実行する - 互いに依存しない複数タスクを高速に処理する際に有効です。 +- コードで検査できる 適切な形式のデータ を生成するために [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使う。例えば、エージェント にタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次に実行する エージェント を選ぶ、といった方法です。 +- ある エージェント の出力を次の エージェント の入力に変換して連結（チェーン）する。ブログ記事の作成のようなタスクを、調査、アウトライン作成、本文執筆、批評、改善といった一連のステップに分解できます。 +- 評価とフィードバックを行う エージェント と組み合わせ、タスクを実行する エージェント を `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで繰り返します。 +- 複数の エージェント を並列に実行する（例: Python の基本コンポーネントである `asyncio.gather` を利用）。相互に依存しない複数タスクがある場合に高速化に有用です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の コード例 があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index ed423b693..e58ee2059 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ行えば問題ありません。 +これは 1 回だけ実行すれば十分です。 ```bash mkdir my_project @@ -14,9 +14,9 @@ cd my_project python -m venv .venv ``` -### 仮想環境のアクティベート +### 仮想環境の有効化 -新しいターミナルセッションを開始するたびに実行してください。 +新しいターミナル セッションを開始するたびに実行してください。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -OpenAI API キーをお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って作成してください。 +まだお持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions、名前、および `model_config` などのオプション設定で定義します。 +エージェントは instructions、名前、および省略可能な設定（`model_config` など）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## 追加エージェントの定義 +## さらにいくつかのエージェントの追加 -追加のエージェントも同じ方法で定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各エージェントで、タスクを進めるために選択できる送信用ハンドオフオプションの一覧を定義できます。 +各エージェントで、タスクを進める方法を決定する際に選択できる、外部へのハンドオフ オプションの一覧を定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ triage_agent = Agent( ) ``` -## エージェントオーケストレーションの実行 +## エージェントのオーケストレーションの実行 -ワークフローが正しく動き、トリアージエージェントが 2 つの専門エージェント間で適切にルーティングするか確認しましょう。 +ワークフローが動作し、トリアージ エージェントが 2 つの専門エージェント間を正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -95,7 +95,7 @@ async def main(): ## ガードレールの追加 -入力または出力に対して実行するカスタムガードレールを定義できます。 +入力または出力に対して実行するカスタム ガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 全体ワークフローの統合 +## 全体の統合 -ハンドオフと入力ガードレールを使用し、すべてをまとめてワークフロー全体を実行しましょう。 +ハンドオフと入力用ガードレールを使用し、ワークフロー全体をまとめて実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの確認 +## トレースの表示 -エージェント実行中に何が起こったかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動し、トレースを閲覧してください。 +エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace ビューアー](https://platform.openai.com/traces) に移動して、エージェントの実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう。 +より複雑なエージェント フローの構築方法を学びましょう: -- [Agents](agents.md) の設定方法を学ぶ -- [running agents](running_agents.md) について学ぶ -- [tools](tools.md)、[guardrails](guardrails.md)、[models](models/index.md) について学ぶ \ No newline at end of file +- [エージェント](agents.md) の設定について学びます。 +- [エージェントの実行](running_agents.md) について学びます。 +- [ツール](tools.md)、[ガードレール](guardrails.md) および [モデル](models/index.md) について学びます。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index ac5d130b0..eedcd6d90 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の realtime 機能を使用して音声対応 AI エージェントを構築する方法を詳細に説明します。 +このガイドでは、 OpenAI Agents SDK のリアルタイム機能を用いて音声対応の AI エージェントを構築する方法を詳しく解説します。 -!!! warning "Beta 機能" -Realtime エージェントは Beta 版です。実装改善に伴い、破壊的変更が入る可能性があります。 +!!! warning "ベータ機能" +リアルタイム エージェントはベータ版です。実装の改善に伴い、後方互換性のない変更が発生する場合があります。 ## 概要 -Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する会話フローを実現します。OpenAI の Realtime API と持続的に接続し、低レイテンシで自然な音声対話を提供し、割り込みにもスムーズに対応できます。 +リアルタイム エージェントは、音声とテキストの入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを実現します。 OpenAI の Realtime API への永続的な接続を維持し、低遅延で自然な音声対話と、割り込みへの柔軟な対応を可能にします。 ## アーキテクチャ -### 主要コンポーネント +### コアコンポーネント -realtime システムは、次の重要なコンポーネントで構成されます。 +このリアルタイム システムは、いくつかの主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得します。 -- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話終了まで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: instructions、tools、ハンドオフで構成されるエージェントです。 +- **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. **イベント受信**: セッションをイテレートしてイベントを受信します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどがあります。 -6. **割り込み処理**: ユーザーがエージェントの発話を遮った場合、自動的に音声生成を停止します。 +1. **RealtimeAgent を作成** します。instructions、tools、ハンドオフを指定します。 +2. **RealtimeRunner をセットアップ** します。エージェントと構成オプションを渡します。 +3. **セッションを開始** します。`await runner.run()` を使うと RealtimeSession が返ります。 +4. **音声またはテキスト メッセージを送信** します。`send_audio()` または `send_message()` を使用します。 +5. **イベントを待ち受け** ます。セッションを反復処理して受け取り、イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. **割り込みを処理** します。ユーザーがエージェントにかぶせて話した場合、進行中の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、realtime モデルとの持続的接続を管理します。 +セッションは会話履歴を保持し、リアルタイム モデルとの永続接続を管理します。 -## エージェント設定 +## エージェント構成 -RealtimeAgent は通常の Agent クラスと似ていますが、いくつか重要な違いがあります。詳細な API は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] を参照してください。 +RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつかの重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 -主な違い: +通常のエージェントとの主な相違点: -- モデル選択はエージェントではなくセッションレベルで設定します。 -- structured outputs (`outputType`) はサポートされていません。 -- Voice はエージェント単位で設定できますが、最初のエージェントが発話した後に変更できません。 -- tools、handoffs、instructions などその他の機能は同じように動作します。 +- モデルの選択はエージェント レベルではなくセッション レベルで設定します。 +- structured outputs のサポートはありません（`outputType` は未対応）。 +- 音声（ボイス）はエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 +- それ以外の機能（tools、ハンドオフ、instructions など）は同様に動作します。 -## セッション設定 +## セッション構成 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、Voice 選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキスト／音声）を設定できます。音声の入出力フォーマットは PCM16 がデフォルトですが変更可能です。 +セッション構成では、基盤となるリアルタイム モデルの挙動を制御できます。モデル名（例：`gpt-4o-realtime-preview`）、ボイスの選択（ alloy、echo、fable、onyx、nova、shimmer ）、対応モダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の双方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定では、音声入力と出力の取り扱いを指定します。Whisper などのモデルで入力音声を文字起こしし、言語や専門用語向けの transcription prompt を設定できます。ターン検出設定では、音声アクティビティ検出の閾値、無音時間、検出された音声前後のパディングなど、エージェントが応答を開始・停止する条件を制御します。 +音声設定では、セッションが音声の入出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、専門用語の精度向上のための文字起こしプロンプトを指定できます。ターン検出設定では、エージェントがいつ応答を開始・停止すべきかを制御し、音声活動検出のしきい値、無音の長さ、検出された発話の前後のパディングなどを設定できます。 -## Tools と Functions +## ツールと関数 -### 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_interrupted**: ユーザーがエージェントを割り込み -- **tool_start/tool_end**: tool 実行ライフサイクル -- **handoff**: エージェント間の handoff -- **error**: 処理中にエラー発生 +- **audio**: エージェントの応答からの生の音声データ +- **audio_end**: エージェントの発話終了 +- **audio_interrupted**: ユーザーがエージェントに割り込み +- **tool_start/tool_end**: ツール実行ライフサイクル +- **handoff**: エージェントのハンドオフが発生 +- **error**: 処理中にエラーが発生 -完全なイベント定義は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +完全なイベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -realtime エージェントでは output ガードレールのみサポートします。パフォーマンスへの影響を抑えるため、単語ごとではなくデバウンスして定期的に実行されます。デフォルトのデバウンス長は 100 文字で、設定可能です。 +リアルタイム エージェントでサポートされるのは出力用のガードレールのみです。ガードレールはデバウンスされ、リアルタイム生成時のパフォーマンス問題を避けるために定期的（単語ごとではなく）に実行されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 -ガードレールは `RealtimeAgent` に直接付与するか、セッションの `run_config` で指定できます。両方に設定した場合は併せて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` で指定できます。両方の経路から与えたガードレールは併用されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレールが発火すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能のバランスを保ちます。テキストエージェントと異なり、realtime エージェントではガードレール発火時に Exception は発生しません。 +ガードレールが発火すると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンスの挙動により、安全性とリアルタイム性能要件のバランスを取ります。テキスト エージェントと異なり、リアルタイム エージェントはガードレール作動時に例外（Exception）を発生させることは **ありません**。 ## 音声処理 -音声は [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] で送信し、テキストは [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] で送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] でセッションに音声を送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] でテキストを送信します。 -音声出力を受信するには `audio` イベントを監視し、お好みの音声ライブラリで再生してください。`audio_interrupted` イベントを監視して、ユーザーが割り込んだ際に即座に再生を停止し、キューにある音声をクリアするようにしてください。 +音声出力については、`audio` イベントを待ち受けて任意の音声ライブラリで再生します。ユーザーがエージェントに割り込んだ際には、すぐに再生を停止しキュー済みの音声をクリアできるよう、`audio_interrupted` イベントも必ず監視してください。 -## 直接的なモデルアクセス +## モデルへの直接アクセス -カスタムリスナーの追加や高度な操作を行うため、基盤モデルへ直接アクセスできます。 +基盤となるモデルにアクセスして、カスタム リスナーの追加や高度な操作を実行できます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスでき、低レベルの接続制御が必要な高度なユースケースに対応できます。 +これにより、接続をより低レベルに制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## 例 +## コード例 -動作する完全な例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI あり／なしのデモを含みます。 \ No newline at end of file +完全な動作するコード例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI コンポーネントの有無それぞれのデモが含まれています。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 3c18bc3cc..37b4ca4cc 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,26 +4,26 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を実現します。このガイドでは、初めてのリアルタイム音声エージェントを作成する手順を説明します。 +Realtime エージェントは、 OpenAI の Realtime API を使用して、 AI エージェントと音声で会話できるようにします。このガイドでは、最初の Realtime 音声エージェントを作成する手順を説明します。 -!!! warning "Beta feature" -Realtime エージェントは β 版です。実装の改善に伴い、互換性が壊れる変更が入る可能性があります。 +!!! warning "ベータ機能" +Realtime エージェントは現在ベータ版です。実装の改善に伴い、互換性のない変更が入る可能性があります。 ## 前提条件 - Python 3.9 以上 - OpenAI API キー -- OpenAI Agents SDK に関する基本的な知識 +- OpenAI Agents SDK の基本的な知識 ## インストール -まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: +まだインストールしていない場合は、 OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## 初めてのリアルタイム エージェントを作成する +## 最初の Realtime エージェントの作成 ### 1. 必要なコンポーネントをインポート @@ -32,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. リアルタイム エージェントを作成 +### 2. Realtime エージェントを作成する ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. Runner をセットアップ +### 3. Runner のセットアップ ```python runner = RealtimeRunner( @@ -56,7 +56,7 @@ runner = RealtimeRunner( ) ``` -### 4. セッションを開始 +### 4. セッションを開始する ```python async def main(): @@ -79,9 +79,9 @@ async def main(): asyncio.run(main()) ``` -## 完全な例 +## 完全なコード例 -以下は動作する完全な例です: +動作する完全なコード例は次のとおりです: ```python import asyncio @@ -139,30 +139,30 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-4o-realtime-preview`) -- `voice`: 音声を選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストおよび/またはオーディオを有効化 (`["text", "audio"]`) +- `model_name`: 利用可能な Realtime モデルから選択します（例: `gpt-4o-realtime-preview`） +- `voice`: 音声を選択します（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） +- `modalities`: テキストおよび/または音声を有効化します（`["text", "audio"]`） -### オーディオ設定 +### 音声設定 -- `input_audio_format`: 入力オーディオのフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力オーディオのフォーマット -- `input_audio_transcription`: 文字起こし設定 +- `input_audio_format`: 入力音声のフォーマット（`pcm16`、`g711_ulaw`、`g711_alaw`） +- `output_audio_format`: 出力音声のフォーマット +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声活動のしきい値 (0.0-1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前のオーディオパディング +- `type`: 検出方法（`server_vad`、`semantic_vad`） +- `threshold`: 音声活動のしきい値（0.0-1.0） +- `silence_duration_ms`: ターン終了を検出するための無音継続時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ - [Realtime エージェントについて詳しく学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作する code examples を確認 -- エージェントにツールを追加 -- エージェント間のハンドオフを実装 -- 安全性のためにガードレールを設定 +- 動作するサンプルコードは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーをご覧ください +- エージェントにツールを追加する +- エージェント間のハンドオフを実装する +- 安全のためのガードレールを設定する ## 認証 @@ -172,7 +172,7 @@ OpenAI API キーが環境変数に設定されていることを確認してく export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション作成時に直接渡します: +また、セッション作成時に直接渡すこともできます: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index ec742b905..cc0f0c20f 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,29 +4,29 @@ search: --- # リリースプロセス/変更履歴 -このプロジェクトでは、`0.Y.Z` 形式を用いた、わずかに変更したセマンティックバージョニングを採用しています。先頭の `0` は SDK が依然として急速に進化していることを示します。各コンポーネントの増分ルールは次のとおりです。 +このプロジェクトは、形式 `0.Y.Z` を用いる、やや変更したセマンティック バージョニングに従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントの増やし方は次のとおりです: -## マイナー (`Y`) バージョン +## マイナー（`Y`）バージョン -ベータではない公開インターフェースに **破壊的変更 (breaking changes)** が入る場合、マイナー番号 `Y` を増やします。たとえば `0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータとしてマークされていない公開インターフェースに対する **破壊的変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定することをおすすめします。 +破壊的変更を望まない場合は、プロジェクトで `0.0.x` のバージョンに固定することをおすすめします。 -## パッチ (`Z`) バージョン +## パッチ（`Z`）バージョン -非破壊的変更がある場合に `Z` を増やします。 +後方互換性を壊さない変更には、`Z` を増やします: -- バグ修正 -- 新機能 -- 非公開インターフェースの変更 -- ベータ機能の更新 +- バグ修正 +- 新機能 +- 非公開インターフェースへの変更 +- ベータ機能の更新 ## 破壊的変更の変更履歴 ### 0.2.0 -このバージョンでは、以前 `Agent` を引数として受け取っていた箇所のいくつかが、代わりに `AgentBase` を受け取るようになりました。例としては MCP サーバーでの `list_tools()` 呼び出しなどです。これは型定義だけの変更で、実際には引き続き `Agent` オブジェクトを受け取ります。更新する際は、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 +このバージョンでは、これまで `Agent` を引数に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。たとえば、 MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型に関する変更で、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承しているクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 2 つのパラメーター: `run_context` と `agent` が追加されました。`MCPServer` を継承するあらゆるクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index caac61752..bd066894e 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,8 +4,7 @@ search: --- # REPL ユーティリティ - SDK は `run_demo_loop` を提供しており、ターミナル内で エージェント の挙動を迅速かつインタラクティブにテストできます。 - +SDK は、お使いのターミナルでエージェントの動作を手早くインタラクティブにテストできる `run_demo_loop` を提供します。 ```python import asyncio @@ -19,6 +18,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 69bea56a5..ea1e7eb53 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 結果 +# 実行結果 -`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` +- そのエージェントに出力タイプが定義されている場合は、型 `last_agent.output_type` のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフが発生する可能性があるため、静的に型を決定できません。ハンドオフが起こると、どのエージェントが最後になるか分からないため、可能な出力型の集合を静的に特定できないのです。 + `final_output` の型は `Any` です。ハンドオフが発生し得るため、静的に型付けできません。ハンドオフが起こると、どのエージェントでも最後のエージェントになり得るため、取り得る出力タイプの集合を静的には特定できません。 -## 次ターン入力 +## 次のターンの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用すると、元の入力とエージェント実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、一度のエージェント実行の出力を次の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするのが簡単になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、実行結果を、最初に与えた元の入力とエージェントの実行中に生成されたアイテムを連結した入力リストに変換できます。これにより、あるエージェントの実行結果を別の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするのが簡単になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されます。アプリケーションによっては、ユーザーが次に入力を送る際にこれが役立つことがよくあります。たとえば、フロントラインのトリアージエージェントが言語別エージェントへハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にメッセージを送ったときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されます。アプリケーションによっては、次回ユーザーが入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージエージェントが言語別のエージェントにハンドオフする構成であれば、最後のエージェントを保存しておき、次回ユーザーがエージェントにメッセージを送るときに再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。各アイテムは [`RunItem`][agents.items.RunItem]s です。RunItem は LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、 LLM によって生成された生のアイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しに対するツール応答です。source/target エージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツールの応答で、ツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は、 LLM からのメッセージを示します。生のアイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は、 LLM がハンドオフツールを呼び出したことを示します。生のアイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。生のアイテムは、そのハンドオフツール呼び出しに対するツールのレスポンスです。アイテムからソース/ターゲットのエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は、 LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。生のアイテムはツールのレスポンスです。アイテムからツールの出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は、 LLM からの推論アイテムを示します。生のアイテムは生成された推論です。 ## その他の情報 -### ガードレール結果 +### ガードレールの結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレール（存在する場合）の結果が含まれます。ガードレールの結果にはログや保存に便利な情報が含まれることがあるため、これらを利用できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果（存在する場合）が含まれます。ガードレール結果には、ログに記録したり保存したくなる有用な情報が含まれることがあるため、これらを参照できるようにしています。 -### raw レスポンス +### 生のレスポンス -[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が含まれます。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、 LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が格納されています。通常は不要ですが、必要に応じて参照できます。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が含まれます。多くの場合これは不要ですが、必要なときのために参照できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 0f01c484a..9660fc340 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは `Runner` クラスを通じて実行できます。方法は 3 通りあります: +エージェントは [`Runner`][agents.run.Runner] クラス経由で実行できます。オプションは 3 つあります: -1. `Runner.run()` — 非同期で実行し、 `RunResult` を返します。 -2. `Runner.run_sync()` — 同期メソッドで、内部的には `.run()` を呼び出します。 -3. `Runner.run_streamed()` — 非同期で実行し、 `RunResultStreaming` を返します。 LLM をストリーミングモードで呼び出し、そのイベントを受信次第ストリームします。 +1. [`Runner.run()`][agents.run.Runner.run] — 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync] — 同期メソッドで、内部的には `.run()` を実行します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] — 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。ストリーミングモードで LLM を呼び出し、受信したイベントをそのままストリーミングします。 ```python from agents import Agent, Runner @@ -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 は次のループを実行します: +Runner は次のようにループを実行します: -1. 現在のエージェントに対し、現在の入力を用いて LLM を呼び出します。 -2. LLM が出力を生成します。 - 1. `final_output` が返された場合、ループを終了し結果を返します。 - 2. ハンドオフが行われた場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. ツール呼び出しを生成した場合、それらを実行し結果を追加したうえでループを再実行します。 -3. 渡された `max_turns` を超えた場合、 `MaxTurnsExceeded` 例外を送出します。 +1. 現在の入力を用いて、現在のエージェントに対して LLM を呼び出します。 +2. LLM が出力を生成します。 + 1. LLM が `final_output` を返した場合、ループを終了し、実行結果を返します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し、その実行結果を追加して、ループを再実行します。 +3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされるルールは、所定の型でテキスト出力を生成し、かつツール呼び出しが存在しない場合です。 + ある LLM 出力が「最終出力」と見なされる条件は、所望の型のテキスト出力を生成し、かつツール呼び出しが存在しないことです。 ## ストリーミング -ストリーミングを使用すると、LLM 実行中のイベントを逐次受け取れます。ストリーム終了後、 `RunResultStreaming` には実行に関する完全な情報 (新たに生成されたすべての出力を含む) が格納されます。 ` .stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 +ストリーミングを使うと、 LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了時には、[`RunResultStreaming`][agents.result.RunResultStreaming] に、生成されたすべての新規出力を含む実行の完全な情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すと取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 -## Run config +## 実行設定 -`run_config` パラメーターでは、エージェント実行に関するグローバル設定を行えます: +`run_config` パラメーターでは、エージェントの実行に関するグローバル設定を構成できます: -- `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` — すべてのトレースに含めるメタデータ。 +- [`model`][agents.run.RunConfig.model]: 各エージェントの `model` に関わらず、使用するグローバルな LLM モデルを設定できます。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力または出力のガードレールのリスト。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既定の入力フィルターがない場合に、すべてのハンドオフへ適用するグローバルな入力フィルターです。入力フィルターにより、新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体に対して [トレーシング](tracing.md) を無効化できます。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、 LLM やツール呼び出しの入出力など、潜在的に機密なデータを含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は、複数の実行にまたがってトレースを関連付けるための任意のフィールドです。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 ## 会話 / チャットスレッド -任意の run メソッドの呼び出しは、1 つ以上のエージェント実行 (つまり 1 つ以上の LLM 呼び出し) を伴いますが、チャット会話における単一の論理ターンを表します。例: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行されることがあります（つまり、1 回以上の LLM 呼び出しが発生します）。ただし、これはチャット会話における 1 回の論理的なターンを表します。たとえば: -1. ユーザーターン: ユーザーがテキストを入力 -2. Runner 実行: 第 1 エージェントが LLM を呼び出し、ツールを実行し、第 2 エージェントへハンドオフ。第 2 エージェントがさらにツールを実行し、出力を生成。 +1. ユーザーのターン: ユーザーがテキストを入力します。 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行し、最終的に出力を生成します。 -エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。たとえばエージェントが生成したすべての新規アイテムを見せるか、最終出力のみを見せるかです。いずれの場合も、ユーザーがフォローアップ質問を行ったら再度 run メソッドを呼び出します。 +エージェントの実行の最後に、ユーザーへ何を表示するかを選べます。たとえば、エージェントが生成した新規アイテムをすべて表示することも、最終出力のみを表示することもできます。いずれにせよ、その後ユーザーが追質問をするかもしれません。その場合は、再度 run メソッドを呼び出します。 ### 手動での会話管理 -`RunResultBase.to_input_list()` メソッドで次ターン用の入力を取得し、会話履歴を手動管理できます: +[`RunResultBase.to_input_list()`][agents.result.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 ごとに会話を分離して管理 +- 各実行の前に会話履歴を取得 +- 各実行の後に新しいメッセージを保存 +- 異なるセッション 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` — 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 +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。他の特定の例外の親となる汎用型として機能します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` の各メソッドに渡した `max_turns` 制限を、エージェントの実行が超えたときに送出されます。指定されたやり取り回数内にタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成したときに発生します。例: + - 不正な JSON: モデルが、ツール呼び出し用、または直接出力に対して不正な JSON 構造を返した場合（とくに特定の `output_type` が定義されているとき）。 + - 予期しないツール関連の失敗: モデルが想定どおりにツールを使用できなかった場合。 +- [`UserError`][agents.exceptions.UserError]: SDK を利用するあなた（SDK を用いてコードを書く人）が誤った使い方をしたときに送出されます。誤った実装、無効な設定、SDK の API の誤用が主な原因です。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ、入力ガードレールまたは出力ガードレールの条件に合致したときに送出されます。入力ガードレールは処理前に受信メッセージを検査し、出力ガードレールは配信前にエージェントの最終応答を検査します。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 2933901c5..ba4b8be79 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()` を手動で扱う必要がなくなります。 -セッションは特定のセッションに対して会話履歴を保存し、明示的なメモリ管理をせずにエージェントがコンテキストを維持できるようにします。これはチャット アプリケーションやマルチターンの会話で、エージェントに過去のやり取りを覚えさせたい場合に特に便利です。 +セッションメモリは特定のセッションの会話履歴を保存し、明示的な手動のメモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャット アプリケーションやマルチターンの会話を構築するときに特に有用です。 ## クイックスタート @@ -49,11 +49,11 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッション メモリを有効にすると、次のように動作します。 +セッションメモリを有効にすると: -1. **各実行前**: Runner がセッションの会話履歴を自動で取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出し など）がすべて自動でセッションに保存されます。 -3. **コンテキスト保持**: 同じセッションで後続の実行を行うたび、完全な会話履歴が入力に含まれるため、エージェントはコンテキストを維持できます。 +1. **各実行の前**: Runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に付加します。 +2. **各実行の後**: 実行中に生成されたすべての新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出し など) は自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの以降の各実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 @@ -61,7 +61,7 @@ print(result.final_output) # "Approximately 39 million" ### 基本操作 -セッションでは会話履歴を管理するための複数の操作をサポートしています。 +セッションは会話履歴を管理するためのいくつかの操作をサポートします: ```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 @@ -145,7 +145,7 @@ result = await Runner.run( ) ``` -### 複数セッション +### 複数のセッション ```python from agents import Agent, Runner, 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 など ) ### セッション管理 @@ -252,9 +252,9 @@ result2 = await Runner.run( ) ``` -## 完全な例 +## 完全なコード例 -以下はセッション メモリが動作する完全な例です。 +セッションメモリの動作を示す完全なコード例です: ```python import asyncio @@ -318,7 +318,7 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは次を参照してください。 +詳細な API ドキュメントは次を参照してください: -- [`Session`][agents.memory.Session] – プロトコル インターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] – SQLite 実装 \ No newline at end of file +- [`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 64f00b4cf..b65821106 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、エージェントの実行が進行するにつれて発生する更新を購読できます。これにより、エンドユーザーに進行状況の更新や部分的なレスポンスを表示するのに役立ちます。 +ストリーミングを使うと、エージェントの実行の進行に合わせて更新を購読できます。これは、エンドユーザーに進捗の更新や部分的な応答を表示するのに役立ちます。 -ストリームするには、`Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。返された `result.stream_events()` を呼び出すと、非同期で `StreamEvent` オブジェクトのストリームを取得できます。各オブジェクトの詳細は後述します。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出すと、[`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 ## raw レスポンスイベント -`RawResponsesStreamEvent` は LLM から直接渡される raw なイベントです。これらは OpenAI Responses API 形式で提供されるため、各イベントは type（例: `response.created`, `response.output_text.delta` など）と data を持ちます。これらのイベントは、レスポンスメッセージが生成され次第ユーザーへストリーム配信したい場合に便利です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、 LLM から直接渡される raw イベントです。これは OpenAI Responses API 形式であり、各イベントには種類 (たとえば `response.created`、`response.output_text.delta` など) とデータがあります。これらのイベントは、応答メッセージが生成され次第ユーザーにストリーミングしたい場合に有用です。 -例えば、以下の例では LLM が生成したテキストをトークン単位で出力します。 +たとえば、これは LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Run アイテムイベントとエージェントイベント +## 実行アイテムイベントとエージェントイベント -`RunItemStreamEvent` はより高レベルのイベントです。アイテムが完全に生成されたときに通知します。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などのレベルで進行状況をプッシュできます。同様に、`AgentUpdatedStreamEvent` は現在のエージェントが変更されたとき（例: ハンドオフの結果として）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき (例: ハンドオフの結果など) に更新を通知します。 -例えば、以下の例では raw イベントを無視し、ユーザーへ更新のみをストリーム配信します。 +たとえば、これは raw イベントを無視し、更新をユーザーにストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 55c1387e9..cda0bbed1 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールを使うと、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。Agents SDK には次の 3 種類のツールがあります。 +ツールはエージェントがアクションを実行できるようにします。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などです。 Agents SDK にはツールのクラスが 3 つあります: -- Hosted tools: LLM サーバー上で AI モデルと並行して動作するツールです。OpenAI は retrieval、web search、computer use を hosted tools として提供しています。 -- Function calling: 任意の Python 関数をツールとして利用できます。 -- Agents as tools: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せます。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。 OpenAI は、リトリーバル、 Web 検索、コンピュータ操作をホスト型ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして使えるようにします。 +- エージェントをツールとして: エージェントをツールとして使えるため、ハンドオフせずにエージェントが他のエージェントを呼び出せます。 -## Hosted tools +## ホスト型ツール -[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用すると、OpenAI がいくつかの組み込みツールを提供します。 +[`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 サーバーのツールをモデルに公開します。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントが Web を検索できるようにします。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は、 OpenAI のベクトルストアから情報を取得できます。 +- [`ComputerTool`][agents.tool.ComputerTool] は、コンピュータ操作タスクの自動化を可能にします。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は、 LLM がサンドボックス化された環境でコードを実行できるようにします。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモート MCP サーバーのツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] は、プロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] は、ローカルマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## Function tools +## 関数ツール -任意の Python 関数をツールとして利用できます。Agents SDK が自動でセットアップします。 +任意の Python 関数をツールとして使用できます。 Agents SDK がツールを自動的にセットアップします: -- ツール名は Python 関数名になります（別名を指定することも可能）。 -- ツールの説明は関数の docstring から取得されます（別途指定も可能）。 -- 関数引数から入力スキーマを自動生成します。 -- 各入力の説明は、無効化しない限り docstring から取得します。 +- ツール名は Python 関数名になります（または任意の名前を指定できます）。 +- ツールの説明は関数のドックストリングから取得されます（または説明を指定できます）。 +- 関数の入力のスキーマは、関数の引数から自動的に作成されます。 +- 各入力の説明は、無効化しない限り関数のドックストリングから取得されます。 -Python の `inspect` モジュールで関数シグネチャを取得し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、`pydantic` でスキーマを生成します。 +関数シグネチャの抽出には Python の `inspect` モジュールを使用し、ドックストリングの解析には [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマの作成には `pydantic` を使用します。 ```python import json @@ -102,10 +102,10 @@ for tool in agent.tools: ``` -1. 任意の Python 型を引数に使用でき、関数は sync／async どちらでも構いません。 -2. Docstring があれば、ツールと各引数の説明を取得します。 -3. 関数は任意で `context`（先頭の引数）を受け取れます。また、ツール名や説明、docstring スタイルなどを上書き設定できます。 -4. デコレートした関数をツールのリストに渡せます。 +1. 任意の Python 型を関数の引数に使え、関数は同期/非同期のいずれでも構いません。 +2. ドックストリングがあれば、説明や引数の説明として利用されます。 +3. 関数は任意で `context` を受け取れます（先頭の引数である必要があります）。また、ツール名や説明、使用するドックストリングのスタイルなどのオーバーライドも設定できます。 +4. デコレートした関数をツールのリストに渡せます。 ??? note "展開して出力を表示" @@ -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 文字列で受け取り、ツールの出力を文字列で返す非同期関数） ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 引数と docstring の自動解析 +### 引数とドックストリングの自動解析 -前述のとおり、関数シグネチャを解析してスキーマを生成し、docstring から説明を抽出します。ポイントは次のとおりです。 +前述のとおり、ツールのスキーマを得るために関数シグネチャを自動解析し、ツールおよび各引数の説明を得るためにドックストリングも解析します。注意点は次のとおりです: -1. シグネチャ解析は `inspect` を使用します。型アノテーションから引数型を理解し、動的に Pydantic モデルを組み立てます。Python プリミティブ型、Pydantic モデル、TypedDict など多くの型をサポートします。 -2. Docstring 解析には `griffe` を使用します。対応フォーマットは `google`、`sphinx`、`numpy` です。自動検出を試みますが、`function_tool` 呼び出し時に明示的に設定もできます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 +1. `inspect` モジュールでシグネチャを解析します。引数の型は型アノテーションから解釈し、全体のスキーマを表す Pydantic モデルを動的に構築します。 Python の基本型、 Pydantic モデル、 TypedDict など、ほとんどの型をサポートします。 +2. ドックストリングの解析には `griffe` を使用します。対応するドックストリング形式は `google`、`sphinx`、`numpy` です。ドックストリング形式は自動検出を試みますがベストエフォートのため、`function_tool` を呼び出す際に明示的に指定できます。`use_docstring_info` を `False` に設定して、ドックストリング解析を無効化することも可能です。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## Agents as tools +## ツールとしてのエージェント -ワークフローによっては、ハンドオフせずに中央エージェントが専門エージェント群をオーケストレーションしたい場合があります。その際はエージェントをツールとしてモデル化できます。 +一部のワークフローでは、制御をハンドオフするのではなく、中核のエージェントが特化したエージェント群をオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデリングすることで実現できます。 ```python from agents import Agent, Runner @@ -269,7 +269,7 @@ async def main(): ### ツール化したエージェントのカスタマイズ -`agent.as_tool` はエージェントを簡単にツール化するための便利メソッドです。ただし全設定に対応しているわけではなく、たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で `Runner.run` を直接呼び出してください。 +`agent.as_tool` 関数は、エージェントを簡単にツール化できるようにする簡便なメソッドです。ただし、すべての設定をサポートしているわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツールの実装内で `Runner.run` を直接使用してください: ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 出力のカスタム抽出 +### カスタム出力抽出 -場合によっては、ツール化したエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば次のようなケースです。 +場合によっては、中央のエージェントに返す前にツール化したエージェントの出力を加工したいことがあります。例えば次のような場合に有用です: -- サブエージェントのチャット履歴から特定情報（例: JSON ペイロード）のみ抽出したい。 -- エージェントの最終回答を別形式に変換したい（例: 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,13 +315,13 @@ json_tool = data_agent.as_tool( ) ``` -## function tools のエラー処理 +## 関数ツールでのエラー処理 -`@function_tool` で function tool を作成するとき、`failure_error_function` を指定できます。これはツール呼び出しがクラッシュした場合に LLM へ渡すエラーレスポンスを生成する関数です。 +`@function_tool` で関数ツールを作成する際は、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを返す関数です。 -- 省略した場合は `default_tool_error_function` が実行され、LLM にエラー発生を通知します。 -- 独自のエラーファンクションを渡すと、それが実行されて LLM に返されます。 -- 明示的に `None` を渡すと、ツール呼び出しエラーは再スローされます。このとき、モデルが不正な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などが発生します。 +- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、 LLM にエラーが発生したことを伝えます。 +- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 +- 明示的に `None` を渡すと、ツール呼び出しのエラーは再送出され、呼び出し側で処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -344,4 +344,4 @@ def get_user_profile(user_id: str) -> str: ``` -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 内でエラーを処理する必要があります。 \ No newline at end of file +手動で `FunctionTool` オブジェクトを作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 9d440efad..78ceac7a2 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. 単一の実行に対しては [`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）ポリシーのもとで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 1 つの「ワークフロー」のエンドツーエンドの操作を表します。複数のスパンで構成されます。トレースには次のプロパティがあります： - - `workflow_name`：論理的なワークフローまたはアプリ名。例：`"Code generation"` や `"Customer service"` - - `trace_id`：トレースの一意 ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` - - `group_id`：省略可。同一会話からの複数トレースを結び付けるための ID。たとえばチャットスレッド ID など - - `disabled`：`True` の場合、このトレースは記録されません - - `metadata`：省略可。トレースに付随するメタデータ -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります： - - `started_at` と `ended_at` タイムスタンプ - - 所属するトレースを示す `trace_id` - - 親スパンを指す `parent_id`（存在する場合） - - スパンに関する情報を含む `span_data`。例：`AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など +- **トレース** は、1 つの「ワークフロー」のエンドツーエンドの処理を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 同一の会話からの複数トレースを関連付けるための任意のグループ ID。たとえばチャットスレッドの ID など + - `disabled`: True の場合、このトレースは記録されません。 + - `metadata`: トレースの任意のメタデータ +- **スパン** は、開始時刻と終了時刻を持つ処理を表します。スパンには次が含まれます: + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを表す `trace_id` + - 親スパン（存在する場合）を指す `parent_id` + - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLMの生成に関する情報を含みます。 -## デフォルトのトレーシング +## 既定のトレーシング -デフォルトでは SDK が以下をトレースします： +既定では、Agents SDKは次をトレースします: -- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ -- エージェント実行ごとに `agent_span()` でラップ -- LLM 生成は `generation_span()` でラップ -- 関数ツール呼び出しは `function_span()` でラップ -- ガードレールは `guardrail_span()` でラップ -- ハンドオフは `handoff_span()` でラップ -- 音声入力（音声→テキスト）は `transcription_span()` でラップ -- 音声出力（テキスト→音声）は `speech_span()` でラップ -- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります +- 全体の `Runner.{run, run_sync, run_streamed}()` が `trace()` でラップされます +- エージェントが実行されるたびに、`agent_span()` でラップされます +- LLMの生成は `generation_span()` でラップされます +- 関数ツールの呼び出しは、それぞれ `function_span()` でラップされます +- ガードレールは `guardrail_span()` でラップされます +- ハンドオフは `handoff_span()` でラップされます +- 音声入力（speech-to-text）は `transcription_span()` でラップされます +- 音声出力（text-to-speech）は `speech_span()` でラップされます +- 関連する音声スパンは、`speech_group_span()` の配下にまとめられる場合があります -デフォルトではトレース名は `"Agent workflow"` です。`trace` を使用する際に名前を指定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他プロパティを設定できます。 +既定では、トレース名は「Agent workflow」です。`trace` を使う場合にこの名前を設定でき、または [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 -さらに、[カスタム トレーシングプロセッサー](#custom-tracing-processors) を設定して、別の送信先へトレースをプッシュする（置き換え・追加のいずれも可）ことができます。 +加えて、[custom trace processors](#custom-tracing-processors) を設定して、トレースを他の送信先へ送信できます（置き換え先、またはセカンダリの送信先として）。 -## より上位のトレース +## より高レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合は、コード全体を `trace()` でラップしてください。 +複数回の `run()` 呼び出しを 1 つのトレースに含めたい場合があります。その場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,48 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しは `with trace()` に包まれているため、個別のトレースを作成せず、全体トレースの一部になります。 +1. `with trace()` で 2 回の `Runner.run` 呼び出しをラップしているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。開始と終了が必要で、方法は 2 通りあります： +[`trace()`][agents.tracing.trace] 関数でトレースを作成できます。トレースは開始と終了が必要で、方法は 2 つあります: -1. **推奨**：コンテキストマネージャとして使用し、`with trace(...) as my_trace` とする。適切なタイミングで自動的に開始・終了します。 -2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 +1. 推奨: トレースをコンテキストマネージャーとして使用します（例: `with trace(...) as my_trace`）。これにより、適切なタイミングで自動的に開始・終了されます。 +2. また、[`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理でも自動的に機能します。手動で開始・終了する場合は、`start()`／`finish()` に `mark_as_current` と `reset_current` を指定して現在のトレースを更新してください。 +現在のトレースは、 Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を介して追跡されます。これは、並行処理でも自動的に機能することを意味します。手動でトレースを開始/終了する場合は、現在のトレースを更新するために、`start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドでスパンを作成できますが、通常は手動での作成は不要です。カスタム情報を追跡したい場合は [`custom_span()`][agents.tracing.custom_span] を利用できます。 +各種の [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。通常、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も利用できます。 -スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これも Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 +スパンは自動的に現在のトレースの一部となり、 Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される、最も近い現在のスパンの配下にネストされます。 -## 機微データ +## 機密データ -一部のスパンは機微データを含む可能性があります。 +一部のスパンでは、機密になり得るデータが取得される場合があります。 -`generation_span()` は LLM 生成の入出力を、`function_span()` は関数呼び出しの入出力を格納します。これらに機微データが含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] で記録を無効化できます。 +`generation_span()` は LLMの生成の入力と出力を保存し、`function_span()` は関数呼び出しの入力と出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの取得を無効化できます。 -同様に、音声スパンはデフォルトで入出力音声の base64 エンコード PCM データを含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して音声データの記録を無効化できます。 +同様に、音声関連のスパンには、既定で入力音声と出力音声の base64 でエンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して、この音声データの取得を無効化できます。 -## カスタム トレーシングプロセッサー +## カスタムトレーシングプロセッサー -トレーシングの高レベル構成は以下のとおりです： +トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、これがトレースを生成 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、バッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] へスパン／トレースを送信して OpenAI バックエンドにエクスポート +- 初期化時に、グローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。これはトレースの作成を担当します。 +- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。`BackendSpanExporter` は、これらのスパンとトレースを OpenAIバックエンドへバッチでエクスポートします。 -デフォルト設定を変更して他のバックエンドへ送信したり、エクスポーターの挙動を変更したりするには次の 2 つの方法があります： +既定のセットアップをカスタマイズして、別のバックエンドや追加のバックエンドにトレースを送信したり、エクスポーターの挙動を変更したりするには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] - 既存の送信に **追加** でトレースプロセッサーを登録し、OpenAI バックエンドへの送信に加えて独自処理を行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] - デフォルトプロセッサーを **置き換え** て独自プロセッサーのみを使用します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含めてください。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第受け取る、追加のトレースプロセッサーを追加できます。これにより、OpenAIのバックエンドにトレースを送信するのに加えて、独自の処理を行えます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、既定のプロセッサーを独自のトレースプロセッサーに置き換えられます。これにより、該当の処理を行う TracingProcessor を含めない限り、トレースは OpenAIバックエンドに送信されません。 -## 非 OpenAI モデルでのトレーシング +## OpenAI以外のモデルでのトレーシング -OpenAI API キーを使用して非 OpenAI モデルでもトレーシングを有効化できます。これによりトレーシングを無効化せずに OpenAI Traces ダッシュボードで無料トレースを確認できます。 +トレーシングを無効化することなく、 OpenAI Traces ダッシュボードで無料のトレーシングを有効にするために、OpenAIの API キーを OpenAI以外のモデルで使用できます。 ```python import os @@ -126,27 +124,27 @@ 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) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) -- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) \ No newline at end of file +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index c075bc645..233239e80 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,13 +2,13 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェントの可視化を使用すると、 **Graphviz** を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、およびハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェント の可視化では、 **Graphviz** を使用して、エージェント とその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフ がどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存グループをインストールします: +オプションの `viz` 依存関係グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は以下のような有向グラフを作成します: +`draw_graph` 関数を使用して、エージェント の可視化を生成できます。この関数は、次のような有向グラフを作成します: - **エージェント** は黄色のボックスで表されます。 - **MCP サーバー** は灰色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **ハンドオフ** は一方のエージェントから別のエージェントへ向かう有向エッジで表されます。 +- **ツール** は緑の楕円で表されます。 +- **ハンドオフ** は、あるエージェント から別のエージェント への有向エッジです。 ### 使用例 @@ -67,35 +67,36 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![エージェント グラフ](../assets/images/graph.png) + +これにより、トリアージ エージェント の構造と、サブエージェント やツール との接続を視覚的に表すグラフが生成されます。 -これにより、 **triage エージェント** の構造とそのサブエージェントおよびツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されたグラフには以下が含まれます: +生成されたグラフには次が含まれます: -- エントリーポイントを示す **開始ノード** (`__start__`) -- 黄色で塗りつぶされた **長方形** で表されるエージェント -- 緑色で塗りつぶされた **楕円** で表されるツール -- 灰色で塗りつぶされた **長方形** で表される **MCP サーバー** -- 相互作用を示す有向エッジ - - **実線の矢印** はエージェント間のハンドオフ - - **点線の矢印** はツール呼び出し - - **破線の矢印** は MCP サーバー呼び出し -- 実行の終了地点を示す **終了ノード** (`__end__`) +- **開始ノード** ( `__start__` ) はエントリーポイントを示します。 +- エージェント は黄色の塗りの **長方形** で表されます。 +- ツール は緑の塗りの **楕円** で表されます。 +- MCP サーバー は灰色の塗りの **長方形** で表されます。 +- 相互作用を示す有向エッジ: + - **実線の矢印** はエージェント 間のハンドオフを表します。 + - **点線の矢印** はツール の呼び出しを表します。 + - **破線の矢印** は 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 9bb66ec07..d3f29dcc2 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -`VoicePipeline` は、エージェント的なワークフローを音声アプリへ簡単に変換するためのクラスです。ワークフローを渡すだけで、入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理を自動で行います。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント ワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の書き起こし、音声の終了検知、適切なタイミングでのワークフロー呼び出し、さらにワークフローの出力を音声へ戻す処理までを引き受けます。 ```mermaid graph LR @@ -34,31 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成するとき、次の項目を設定できます: +パイプラインを作成する際には、次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] — 新しい音声が文字起こしされるたびに実行されるコード。 -2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] の各モデル。 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] — 以下のような設定を行えます。 - - モデルプロバイダー: モデル名をモデルにマッピングします - - トレーシング: トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など - - TTS と STT モデルの設定: プロンプト、言語、データ型など +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]。新しい音声が書き起こされるたびに実行されるコードです。 +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデルです。 +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。次のような項目を設定できます。 + - モデルプロバイダー。モデル名をモデルに対応付けできます + - トレーシング。トレーシングの無効化可否、音声ファイルのアップロード可否、ワークフロー名、トレース ID など + - TTS と STT モデルの設定（使用するプロンプト、言語、データ型など） ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 つの形式で渡せます: +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声ファイルがあり、その文字起こしに対して結果だけを生成したい場合に使用します。話者がいつ話し終えたかを検知する必要がないケース、たとえば事前録音された音声やユーザーが話し終えるタイミングが明確なプッシュ・トゥ・トーク アプリで便利です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] - ユーザーが話し終えたタイミングを検知する必要がある場合に使用します。音声チャンクを検知し次第プッシュでき、パイプラインが「アクティビティ検知」により適切なタイミングでエージェント ワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の書き起こしがあり、その結果だけを生成したい場合に使います。話者の発話終了を検知する必要がない状況、たとえば事前録音の音声がある場合や、ユーザーの発話終了が明確な push-to-talk アプリで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検知する必要がある場合に使います。検出された音声チャンクを逐次プッシュでき、音声パイプラインが 「activity detection」 と呼ばれる処理により適切なタイミングでエージェントのワークフローを自動実行します。 ## 結果 -音声パイプライン実行の結果は [`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 @@ -78,4 +76,4 @@ async for event in result.stream(): ### 割り込み -現在、 Agents SDK には [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートはありません。検知された各ターンごとにワークフローが個別に実行されます。アプリケーション側で割り込みを処理したい場合は [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] を監視してください。`turn_started` は新しいターンが文字起こしされ、処理が始まったことを示します。`turn_ended` は該当ターンのすべての音声が送信された後に発火します。モデルがターンを開始した際にマイクをミュートし、ターンに関連する音声をすべて送った後でアンミュートするといった制御にこれらのイベントを利用できます。 \ No newline at end of file +現在、Agents SDK は [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み機能をサポートしていません。その代わり、検出された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] のイベントを監視してください。`turn_started` は新しいターンが書き起こされ、処理が開始されたことを示します。`turn_ended` は該当のターンに対するすべての音声が送出された後に発火します。これらのイベントを利用して、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべて送出し終えた後にミュートを解除するといった制御ができます。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index a654fbfc4..d1067f32b 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -まず、Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。その後、SDK から追加の音声依存関係をインストールします。 +まず、 Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。次に、 SDK から音声用のオプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -ここで覚えておくべき主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは次の 3 ステップのプロセスになります。 +主要な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、 3 段階のプロセスです: -1. 音声をテキストに変換するために speech-to-text モデルを実行する -2. 通常はエージェント的ワークフローであるあなたのコードを実行し、結果を生成する -3. 結果のテキストを音声に戻すために text-to-speech モデルを実行する +1. 音声認識 (speech-to-text) モデルを実行して、音声をテキストに変換します。 +2. 通常はエージェント的なワークフローであるご自身のコードを実行して、結果を生成します。 +3. テキスト読み上げ (text-to-speech) モデルを実行して、結果のテキストを音声に戻します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントをセットアップしましょう。すでにこの SDK でエージェントを作成したことがある場合は、馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、およびツールを用意します。 +まず、いくつかのエージェントを設定します。これは、この SDK でエージェントを構築したことがある方にはおなじみのはずです。ここでは、 2 つのエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使い、シンプルな音声パイプラインを設定します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめ +## 統合 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけてきます！ 自分でエージェントに話しかけられるデモは、[examples/voice/static のサンプル](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話しかけます。[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のサンプルで、エージェントと会話できるデモをご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index e6231442f..619ecd4c5 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントがトレーシングされる](../tracing.md) のと同様に、音声パイプラインも自動的にトレーシングされます。 +上記の [エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレースされます。 -基本的なトレーシング情報については上記のトレーシングドキュメントをご覧いただけますが、さらに [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使用してパイプラインのトレーシングを設定することも可能です。 +基本的なトレーシング情報については上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] でパイプラインのトレーシングを構成できます。 -トレーシングに関係する主なフィールドは次のとおりです。 +トレーシングに関連する主なフィールドは次のとおりです: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：音声の文字起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプラインに限定され、ワークフロー内部には影響しません。 -- [`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 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは、トレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の文字起こしなど、機密になり得るデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、お使いの Workflow 内で行われる処理には適用されません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースワークフローの名前です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` です。複数のトレースを関連付けることができます。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file diff --git a/docs/ref/memory/session.md b/docs/ref/memory/session.md new file mode 100644 index 000000000..37a0d50f1 --- /dev/null +++ b/docs/ref/memory/session.md @@ -0,0 +1,3 @@ +# `Session` + +::: agents.memory.session diff --git a/docs/ref/realtime/handoffs.md b/docs/ref/realtime/handoffs.md new file mode 100644 index 000000000..f85b010d7 --- /dev/null +++ b/docs/ref/realtime/handoffs.md @@ -0,0 +1,3 @@ +# `Handoffs` + +::: agents.realtime.handoffs diff --git a/docs/ref/realtime/items.md b/docs/ref/realtime/items.md new file mode 100644 index 000000000..49b48cc2e --- /dev/null +++ b/docs/ref/realtime/items.md @@ -0,0 +1,3 @@ +# `Items` + +::: agents.realtime.items diff --git a/docs/ref/realtime/model_events.md b/docs/ref/realtime/model_events.md new file mode 100644 index 000000000..833b4dcef --- /dev/null +++ b/docs/ref/realtime/model_events.md @@ -0,0 +1,3 @@ +# `Model Events` + +::: agents.realtime.model_events diff --git a/docs/ref/realtime/model_inputs.md b/docs/ref/realtime/model_inputs.md new file mode 100644 index 000000000..27023cdfd --- /dev/null +++ b/docs/ref/realtime/model_inputs.md @@ -0,0 +1,3 @@ +# `Model Inputs` + +::: agents.realtime.model_inputs diff --git a/docs/ref/realtime/openai_realtime.md b/docs/ref/realtime/openai_realtime.md new file mode 100644 index 000000000..075bef650 --- /dev/null +++ b/docs/ref/realtime/openai_realtime.md @@ -0,0 +1,3 @@ +# `Openai Realtime` + +::: agents.realtime.openai_realtime diff --git a/docs/scripts/translate_docs.py b/docs/scripts/translate_docs.py index a337a90ef..a447a08a4 100644 --- a/docs/scripts/translate_docs.py +++ b/docs/scripts/translate_docs.py @@ -9,7 +9,7 @@ # logging.basicConfig(level=logging.INFO) # logging.getLogger("openai").setLevel(logging.DEBUG) -OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "o3") +OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-5") ENABLE_CODE_SNIPPET_EXCLUSION = True # gpt-4.5 needed this for better quality @@ -87,6 +87,7 @@ "* The term 'primitives' can be translated as basic components.", "* When the terms 'instructions' and 'tools' are mentioned as API parameter names, they must be kept as is.", "* The terms 'temperature', 'top_p', 'max_tokens', 'presence_penalty', 'frequency_penalty' as parameter names must be kept as is.", + "* Keep the original structure like `* **The thing**: foo`; this needs to be translated as `* **(translation)**: (translation)`", ], "ja": [ "* The term 'result' in the Runner guide context must be translated like 'execution results'", @@ -172,7 +173,7 @@ def built_instructions(target_language: str, lang_code: str) -> str: 1. Read the input markdown text given by the user. 2. Translate the markdown file into {target_language}, carefully following the requirements above. -3. Perform a self-review to evaluate the quality of the translation, focusing on naturalness, accuracy, and consistency in detail. +3. Self-review your translation to ensure high quality, focusing on naturalness, accuracy, and consistency while avoiding unnecessary changes or spacing. 4. If improvements are necessary, refine the content without changing the original meaning. 5. Continue improving the translation until you are fully satisfied with the result. 6. Once the final output is ready, return **only** the translated markdown text. No extra commentary. @@ -222,7 +223,16 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None: translated_content: list[str] = [] for chunk in chunks: instructions = built_instructions(languages[lang_code], lang_code) - if OPENAI_MODEL.startswith("o"): + if OPENAI_MODEL.startswith("gpt-5"): + response = openai_client.responses.create( + model=OPENAI_MODEL, + instructions=instructions, + input=chunk, + reasoning={"effort": "high"}, + text={"verbosity": "low"}, + ) + translated_content.append(response.output_text) + elif OPENAI_MODEL.startswith("o"): response = openai_client.responses.create( model=OPENAI_MODEL, instructions=instructions,