diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 871223d9f..e26156bc5 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる基本コンポーネントです。エージェントは instructions とツールで構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる基本コンポーネントです。エージェントは instructions と tools で構成された大規模言語モデル（ LLM ）です。 -## 基本設定 +## 基本構成 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +設定で最も一般的に指定するエージェントのプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージまたは システムプロンプト とも呼ばれます。 -- `model`: 使用する LLM と、temperature、top_p などのモデル調整パラメーターを設定する任意の `model_settings`。 -- `tools`: エージェントがタスクを達成するために使用できるツールです。 +- `name`: エージェントを識別する必須の文字列。 +- `instructions`: developer メッセージ、または system prompt とも呼ばれます。 +- `model`: 使用する LLM と、temperature、top_p などのモデル調整用 `model_settings`（任意）。 +- `tools`: エージェントがタスク達成のために使用できるツール。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態の入れ物として機能します。コンテキストには任意の Python オブジェクトを指定できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行における依存関係と状態の入れ物として機能します。任意の Python オブジェクトを context として提供できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト（すなわち `str`）を出力します。特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な任意の型（dataclasses、lists、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.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを提供すると、エージェントは関連がある場合にそれらへ委譲できます。これは、単一タスクに特化したモジュール型のエージェントをオーケストレーションする強力なパターンです。詳しくは [ハンドオフ](handoffs.md) のドキュメントを参照してください。 ```python from agents import Agent @@ -98,7 +98,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を与えられますが、関数を介して動的に instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用可能です。 +多くの場合、エージェント作成時に instructions を指定できますが、関数を使って動的に提供することも可能です。この関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用できます。 ```python def dynamic_instructions( @@ -115,15 +115,15 @@ agent = Agent[UserContext]( ## ライフサイクルイベント（フック） -エージェントのライフサイクルを観察したい場合があります。たとえば、イベントを記録したり、特定のイベント発生時にデータを事前取得したりします。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりするなどです。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行して ユーザー 入力に対するチェックや検証を、またエージェントの出力が生成された後に出力に対するチェックや検証を実行できます。たとえば、 ユーザー の入力とエージェントの出力の関連性をスクリーニングできます。詳細は [ガードレール](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 にツールの使用を必須にします（ただし、どのツールを使うかは賢く判断します）。 -3. `none`: LLM にツールを使用しないことを必須にします。 -4. 文字列を指定（例: `my_tool`）: その特定のツールを使用することを LLM に必須にします。 +1. `auto`: ツールを使用するかどうかを LLM に委ねます。 +2. `required`: ツールの使用を必須にします（どのツールを使うかは賢く選択されます）。 +3. `none`: ツールを使用しないことを必須にします。 +4. 特定の文字列（例: `my_tool`）を設定: その特定のツールを必ず使用させます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -165,8 +165,8 @@ agent = Agent( ## ツール使用の動作 -`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 -- `"run_llm_again"`: デフォルト。ツールを実行し、LLM が結果を処理して最終応答を生成します。 +`Agent` 構成の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 +- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 - `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしで最終応答として使用します。 ```python @@ -207,7 +207,7 @@ agent = Agent( tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 +- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを決定するカスタム関数。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -245,4 +245,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツールの結果が LLM に送られ、`tool_choice` のために LLM が再度ツール呼び出しを生成し続けることが原因です。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、`tool_choice` により LLM が再びツール呼び出しを生成し続けるために発生します。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index ed7a81611..410b55602 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポートされるとすぐに、LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を探します。アプリが起動する前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 +デフォルトで、SDK はインポートされるとすぐに、LLM リクエストおよび トレーシング 用の `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -あるいは、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーから API キーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記で設定したデフォルトキーから 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 には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これにより警告とエラーは `stdout` に送られますが、それ以外のログは抑制されます。 +SDK には、ハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られ、その他のログは抑制されます。 -詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログ出力を有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -あるいは、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) をご覧ください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging ガイド](https://docs.python.org/3/howto/logging.html)を参照してください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機微なデータ +### ログ内の機微データ -一部のログには機微なデータ（たとえば、ユーザー データ）が含まれる場合があります。このデータの記録を無効化したい場合は、次の環境変数を設定してください。 +一部のログには機微なデータ（例: ユーザー データ）が含まれる場合があります。これらのデータをログ出力しないようにするには、次の環境変数を設定します。 -LLM 入出力のロギングを無効化するには: +LLM の入力および出力のログを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツール入出力のロギングを無効化するには: +ツールの入力および出力のログを無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index a2372c00c..b18e8cae1 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという用語は多義的です。考慮すべきコンテキストには大きく 2 つの種類があります。 +コンテキストは多義的な用語です。主に次の 2 つのクラスのコンテキストがあります。 -1. コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 -2. LLM に提供されるコンテキスト: これは、応答を生成する際に LLM が参照できるデータです。 +1. コードでローカルに利用可能なコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック内、ライフサイクルフック内などで必要となるデータや依存関係です。 +2. LLM に対して利用可能なコンテキスト: これは、応答を生成するときに LLM が参照できるデータです。 ## ローカルコンテキスト これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティを通じて表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 -2. そのオブジェクトを各種の実行メソッドに渡します（例: `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` 経由でアクセスできます。 - **最重要** な点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは、同じコンテキストの型を使用する必要があります。 +最も **重要** な注意点: あるエージェント実行においては、そのエージェント、ツール関数、ライフサイクルなどのすべてで、同じ型のコンテキストを使う必要があります。 コンテキストは次のような用途に使えます: -- 実行のためのコンテキストデータ（例: ユーザー名 / uid など、ユーザーに関するその他の情報） -- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） -- ヘルパー関数 +- 実行のためのコンテキストデータ（例: ユーザー名/uid など、ユーザーに関する情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルなオブジェクトであり、読み取り・書き込み・メソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM には送信されません。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから読み取ります。 -3. 型チェッカーがエラーを検出できるように、エージェントにジェネリクス `UserInfo` を付与しています（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることが分かります。ツールの実装はコンテキストから読み取ります。 +3. ジェネリクスの `UserInfo` をエージェントに付与し、型チェッカーがエラーを検出できるようにします（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 4. コンテキストは `run` 関数に渡されます。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM のコンテキスト +## エージェント/ LLM のコンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴のもの **のみ** です。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できるようにする必要があります。方法はいくつかあります。 +LLM が呼び出されると、参照できるデータは会話履歴にあるものだけです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できるようにする必要があります。これには次の方法があります。 -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは固定文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 -2. `Runner.run` を呼び出すときの `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) においてより下位のメッセージを持たせることができます。 -3. 関数ツールを通じて公開します。これはオンデマンドのコンテキストに有用で、LLM が必要に応じてそのデータを取得するためにツールを呼び出せます。 -4. ファイル検索 または Web 検索 を使用します。これらは、ファイルやデータベース（ファイル検索）または Web（Web 検索）から関連データを取得できる特別なツールです。これは、応答を関連するコンテキストデータに「グラウンディング」するのに有用です。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。これは常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 +2. `Runner.run` 関数を呼び出すときに `input` に追加します。これは `instructions` の手法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できます。 +3. 関数ツールを通じて公開します。これはオンデマンドなコンテキストに有用です。LLM が必要になったときにデータを取得するためにツールを呼び出せます。 +4. リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）または Web（Web 検索）から関連データを取得できる特別なツールです。これは、関連するコンテキストデータに応答を「グラウンディング」するのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index f50e5f3e3..af72fd700 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,45 +4,45 @@ search: --- # コード例 -[リポジトリ](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):** - このカテゴリーのコード例は、次のような一般的な エージェント の設計パターンを示します + このカテゴリーのコード例は、一般的なエージェントの設計パターンを示します。たとえば次のとおりです。 - 決定的なワークフロー - - ツールとしての エージェント - - エージェント の並列実行 + - ツールとしてのエージェント + - エージェントの並列実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらのコード例は、次のような SDK の基礎的な機能を紹介します + これらのコード例は、 SDK の基礎的な機能を紹介します。たとえば次のとおりです。 - - 動的な システムプロンプト - - ストリーミング 出力 - - ライフサイクル イベント + - 動的な system prompts + - ストリーミング出力 + - ライフサイクルイベント - **[ツールのコード例](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツールの実装方法と、エージェント への統合方法を学べます。 + Web 検索やファイル検索などの OpenAI がホストするツールの実装方法を学び、エージェントに統合する方法を理解できます。 - **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 非 OpenAI モデルを SDK で利用する方法を紹介します。 + OpenAI 以外のモデルを SDK で使う方法を学べます。 - **[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 を使ってエージェントを構築する方法を学べます。 - **[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 つのコード例 + 実運用を想定した 2 つのより作り込まれたコード例です。 - - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 - - **research_bot**: シンプルな ディープリサーチ クローン。 + - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 + - **research_bot**: シンプルなディープリサーチのクローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを用いた音声 エージェント のコード例をご覧ください。 + TTS と STT のモデルを使った音声エージェントのコード例です。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイム体験を構築する方法を示すコード例。 \ No newline at end of file + SDK を使ってリアルタイム体験を構築する方法を示すコード例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index b79317a4e..3f224d532 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは、あなたのエージェントと _並行して_ 実行され、 ユーザー 入力のチェックや検証を行います。たとえば、非常に賢い（したがって遅く/高価な）モデルを使って顧客の問い合わせを支援するエージェントがあるとします。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるよう依頼することは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意のある利用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を停止して時間とコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を行います。例えば、顧客からのリクエストに対応するために非常に賢い（つまり遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーに、数学の宿題を手伝うようにそのモデルへ依頼させたくはありません。そのために、より高速/低コストのモデルでガードレールを走らせることができます。ガードレールが悪意のある利用を検出した場合、即座にエラーを送出し、高価なモデルの実行を止めて時間と費用を節約できます。 -ガードレールには 2 つの種類があります: +ガードレールには 2 種類あります。 -1. 入力ガードレールは最初の ユーザー 入力で実行されます -2. 出力ガードレールは最終的なエージェントの出力で実行されます +1. 入力ガードレールは最初のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 ステップで実行されます: +入力ガードレールは 3 つのステップで実行されます。 -1. まず、ガードレールはエージェントに渡されるのと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これは [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、 ユーザー へ適切に応答したり例外を処理できます。 +1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップします。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの適切な応答や例外処理ができます。 !!! Note - 入力ガードレールは ユーザー 入力で実行されることを意図しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントの場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント上にあり、`Runner.run` に渡さないのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことが可読性の向上に役立ちます。 + 入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントのガードレールはそのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`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] 例外が発生し、 ユーザー へ適切に応答したり例外を処理できます。 +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 @@ -96,7 +96,7 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果に追加情報を含めることができます。 +3. ガードレール結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 979c36345..60647ed77 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# Handoffs +# ハンドオフ -Handoffs は、ある エージェント が別の エージェント にタスクを委譲できるようにします。これは、異なる エージェント がそれぞれ別個の分野を専門としているシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に扱う エージェント がいるかもしれません。 +ハンドオフは、エージェント が別の エージェント にタスクを委譲できる機能です。これは、異なる エージェント が異なる分野を専門としている状況で特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱う エージェント がいるかもしれません。 -Handoffs は ツール として LLM に提示されます。たとえば、`Refund Agent` に handoff する場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM からはツールとして表現されます。たとえば `Refund Agent` へのハンドオフがある場合、そのツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すか、Handoff をカスタマイズする `Handoff` オブジェクトを渡すことができます。 +すべての エージェント は [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、これは `Agent` を直接渡すか、ハンドオフをカスタマイズする `Handoff` オブジェクトを受け取れます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使って handoff を作成できます。この関数では、handoff 先の エージェント に加えて、任意の上書き設定や入力フィルターを指定できます。 +OpenAI Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き渡し先の エージェント に加えて、任意のオーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -以下のように、シンプルな handoff を作成できます。 +シンプルなハンドオフの作成方法は次のとおりです。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェント を直接使う（`billing_agent` のように）ことも、`handoff()` 関数を使うこともできます。 +1. `billing_agent` のように エージェント を直接使っても、`handoff()` 関数を使っても構いません。 -### `handoff()` 関数による handoffs のカスタマイズ +### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数では、以下の項目をカスタマイズできます。 -- `agent`: handoff 先の エージェント です。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使われ、`transfer_to_` に解決されます。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` の既定のツール説明を上書きします。 -- `on_handoff`: handoff が呼び出されたときに実行されるコールバック関数です。handoff が呼ばれたことが分かった時点でデータ取得を開始する、といった用途に便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: handoff が期待する入力の型（任意）。 -- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は下記を参照してください。 -- `is_enabled`: handoff が有効かどうか。真偽値または真偽値を返す関数を指定でき、実行時に動的に 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`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は下記を参照してください。 +- `is_enabled`: ハンドオフを有効にするかどうか。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## Handoff inputs +## ハンドオフの入力 -状況によっては、handoff を呼び出す際に LLM にデータを提供してほしいことがあります。例えば、「Escalation agent」への handoff を考えてみましょう。ログのために理由を提供してもらいたい場合があります。 +状況によっては、ハンドオフ呼び出し時に LLM にいくらかのデータを渡してほしい場合があります。たとえば「エスカレーション エージェント」へのハンドオフを考えてみてください。ログのために理由を渡したいかもしれません。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -handoff が発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、以前の会話履歴全体を参照できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] として既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -よくあるパターン（例えば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除する）が、[`agents.extensions.handoff_filters`][] に実装されています。 ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. これにより、`FAQ agent` が呼ばれたときに履歴からすべてのツールが自動的に削除されます。 +1. これは、`FAQ agent` が呼び出されたときに履歴から自動的にすべてのツールを削除します。 ## 推奨プロンプト -LLM が handoffs を正しく理解できるようにするため、エージェント に handoffs に関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動的に追加できます。 +LLM がハンドオフを正しく理解できるようにするため、エージェント にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に提案のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨情報をプロンプトに自動的に追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 3d65818d0..c4aca6001 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、最小限の抽象化で軽量かつ使いやすいパッケージにより、エージェント的な AI アプリを構築できるようにします。これは、以前のエージェント向け実験である [Swarm](https://github.com/openai/swarm/tree/main) のプロダクション対応版アップグレードです。Agents SDK には、非常に小さな基本コンポーネントのセットがあります。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、当社のエージェントに関する過去の実験である [Swarm](https://github.com/openai/swarm/tree/main) の本番対応版アップグレードです。Agents SDK にはごく少数の基本コンポーネントがあります。 -- ** エージェント **: instructions と tools を備えた LLM -- ** ハンドオフ **: 特定のタスクについて、エージェントが他のエージェントへ委譲できる機能 -- ** ガードレール **: エージェントの入力と出力の検証を可能にする機能 -- ** セッション **: エージェントの実行間で会話履歴を自動的に保持する機能 +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントへ委譲できる機能 +- **ガードレール**: エージェントの入力と出力を検証できる機能 +- **セッション**: エージェントの実行をまたいで会話履歴を自動的に維持 -これらの基本コンポーネントは、 Python と組み合わせることで、ツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実世界のアプリケーションを構築できます。さらに、 SDK には組み込みの ** トレーシング ** が含まれており、エージェントのフローを可視化・デバッグし、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を十分に表現でき、学習コストをかけずに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントフローの可視化とデバッグ、評価、そしてアプリケーション向けのモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -この SDK は、次の 2 つの設計原則に基づいています。 +この SDK は次の 2 つの設計原則に基づいています。 -1. 使う価値があるだけの十分な機能を備えつつ、学習がすばやく済むよう基本コンポーネントは少数にする。 -2. すぐに使えて優れた体験を提供しつつ、動作を細部までカスタマイズできる。 +1. 使う価値があるだけの機能を備えつつ、学習が速いよう基本コンポーネントは少数にする。 +2. すぐ使えて優れた体験を提供しつつ、挙動を正確にカスタマイズできる。 -主な機能は次のとおりです。 +SDK の主な機能は次のとおりです。 -- エージェントループ: ツールの呼び出し、結果の LLM への送信、 LLM の完了までのループを処理する組み込みのエージェントループ。 -- Python ファースト: 新しい抽象化を学ぶ必要なく、言語の組み込み機能でエージェントのオーケストレーションとチェーン化が可能。 -- ハンドオフ: 複数のエージェント間の調整と委譲を可能にする強力な機能。 -- ガードレール: 検証をエージェントと並行して実行し、チェックが失敗したら早期に打ち切り。 -- セッション: エージェントの実行間で会話履歴を自動管理し、手動の状態管理を不要に。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 -- トレーシング: ワークフローの可視化・デバッグ・監視を可能にし、 OpenAI の評価、ファインチューニング、蒸留ツール群も利用可能。 +- エージェントループ: ツールの呼び出し、結果を LLM へ渡す処理、LLM が完了するまでのループを内蔵。 +- Python ファースト: 新しい抽象化を学ぶのではなく、言語の機能を使ってエージェントをオーケストレーションし連鎖できます。 +- ハンドオフ: 複数のエージェント間で協調と委譲を行う強力な機能。 +- ガードレール: エージェントと並行して入力の検証やチェックを実行し、チェックが失敗したら早期に中断。 +- セッション: エージェントの実行をまたいだ会話履歴の自動管理により、手動での状態管理が不要。 +- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と Pydantic ベースの検証を提供。 +- トレーシング: ワークフローの可視化、デバッグ、監視に加え、OpenAI の評価、ファインチューニング、蒸留ツール群を活用可能。 ## インストール diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index ecb1c58d2..48179984e 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,23 +4,23 @@ search: --- # Model context protocol (MCP) -The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka MCP) is a way to provide tools and context to the LLM. From the MCP docs: +[Model context protocol](https://modelcontextprotocol.io/introduction)（別名 MCP）は、LLM にツールとコンテキストを提供するための方法です。MCP のドキュメントからの引用です: -> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 -Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用して、エージェント にツールやプロンプトを提供できます。 +Agents SDK には MCP のサポートがあります。これにより、幅広い MCP サーバーを使用して、エージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、MCP の仕様は、使用するトランスポート方式に基づいて 3 種類の サーバー を定義しています。 +現在、MCP 仕様は、使用するトランスポートメカニズムに基づいて 3 種類のサーバーを定義しています: -1. **stdio** サーバーはアプリケーションのサブプロセスとして実行されます。いわゆる「ローカル」で動作すると考えられます。 -2. **HTTP over SSE** サーバーはリモートで実行されます。URL 経由で接続します。 +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] クラスを使用して接続できます。 -たとえば、[official MCP filesystem server](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 @@ -54,11 +54,11 @@ agent=Agent( ## ツールのフィルタリング -MCP サーバーでツールフィルターを設定することで、エージェント で利用可能なツールを制限できます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーでツールフィルターを構成して、エージェントで使用可能なツールを制限できます。SDK は静的および動的なツールフィルタリングの両方をサポートします。 ### 静的ツールフィルタリング -単純な許可/ブロック リストには、静的フィルタリングを使用できます。 +単純な許可/ブロックリストの場合は、静的フィルタリングを使用できます: ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合の処理順序は次のとおりです。** -1. まず `allowed_tool_names`（許可リスト）を適用し、指定したツールのみを残します -2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定したツールを除外します +**`allowed_tool_names` と `blocked_tool_names` の両方が構成されている場合、処理順序は次のとおりです:** +1. まず `allowed_tool_names`（許可リスト）を適用します — 指定されたツールのみを残します +2. 次に `blocked_tool_names`（ブロックリスト）を適用します — 残ったツールから指定されたツールを除外します -たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定した場合、`read_file` と `write_file` のツールのみが利用可能になります。 +たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を構成した場合、使用可能になるのは `read_file` と `write_file` ツールのみです。 ### 動的ツールフィルタリング -より複雑なフィルタリングロジックには、関数を用いた動的フィルターを使用できます。 +より複雑なフィルタリングロジックには、関数を使った動的フィルターを使用できます: ```python from agents.mcp import ToolFilterContext @@ -134,18 +134,18 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では次の情報にアクセスできます。 +`ToolFilterContext` では次の情報にアクセスできます: - `run_context`: 現在の実行コンテキスト -- `agent`: ツールを要求している エージェント -- `server_name`: MCP サーバーの名前 +- `agent`: ツールを要求しているエージェント +- `server_name`: MCP サーバー名 ## プロンプト -MCP サーバーは、エージェント の指示を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な指示テンプレートを作成できます。 +MCP サーバーは、エージェントの instructions を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な指示テンプレートを作成できます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは、次の 2 つの主要なメソッドを提供します。 +プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します: - `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示します - `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得します @@ -173,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェント が実行されるたびに、MCP サーバーで `list_tools()` が呼び出されます。特に サーバー がリモートの場合はレイテンシが発生し得ます。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないと確信できる場合にのみ使用してください。 +エージェントが実行されるたびに、MCP サーバーで `list_tools()` が呼び出されます。特にサーバーがリモートサーバーの場合、これはレイテンシーの原因になり得ます。ツール一覧を自動的にキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないことが確実な場合にのみ行ってください。 -キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出せます。 ## エンドツーエンドの code examples -[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で、完全に動作する code examples を参照してください。 +完全に動作する code examples は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。 ## トレーシング -[Tracing](./tracing.md) は、以下を含む MCP の操作を自動的に取得します。 +[トレーシング](./tracing.md)は、次を含む MCP の操作を自動的に捕捉します: -1. ツール一覧の取得に対する MCP サーバーへの呼び出し +1. ツール一覧を取得するための MCP サーバーへの呼び出し 2. 関数呼び出しに関する MCP 関連情報 -![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file +![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 6185d0896..06bb8bb8e 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、OpenAI モデル向けの標準サポートが 2 つの形で含まれています。 +Agents SDK には、OpenAI モデルのサポートが 2 種類用意されています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい Responses API を使って OpenAI API を呼び出します (https://platform.openai.com/docs/api-reference/responses)。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。Chat Completions API を使って OpenAI API を呼び出します (https://platform.openai.com/docs/api-reference/chat)。 +- **推奨**: [`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 モデル -`Agent` を初期化する際にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント的ワークフローにおける予測可能性と低レイテンシのバランスが優れています。 +`Agent` を初期化するときにモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント型ワークフローの予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) のような他のモデルに切り替える場合は、次のセクションの手順に従ってください。 -### 既定の OpenAI モデル +### OpenAI のデフォルトモデル -カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使いたい場合は、エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 +カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使用したい場合は、エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -この方法で GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用すると、SDK は既定で適切な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 +GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）をこの方法で使用すると、SDK はデフォルトで妥当な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` をどちらも `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 -レイテンシを下げたい場合や特定の要件がある場合は、別のモデルと設定を選べます。デフォルトモデルの reasoning 努力度を調整するには、独自の `ModelSettings` を渡してください。 +レイテンシを下げたい場合や特定の要件がある場合は、別のモデルと設定を選択できます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。 ```python from openai.types.shared import Reasoning @@ -44,11 +44,11 @@ my_agent = Agent( ) ``` -特に低レイテンシを狙う場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を組み合わせると、デフォルト設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（ファイル検索 や 画像生成 など）は `"minimal"` の reasoning 努力度をサポートしていないため、この Agents SDK は既定で `"low"` を使用します。 +特に低レイテンシが目的であれば、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) や [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、デフォルト設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（例えば ファイル検索 と 画像生成）は `"minimal"` の reasoning effort をサポートしていないため、本 Agents SDK ではデフォルトを `"low"` にしています。 #### 非 GPT-5 モデル -カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はどのモデルでも互換性がある汎用的な `ModelSettings` にフォールバックします。 +カスタム `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用の `ModelSettings` にフォールバックします。 ## 非 OpenAI モデル @@ -58,38 +58,38 @@ my_agent = Agent( pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて [サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 +次に、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) を使用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使用する他の方法 +### 非 OpenAI モデルを使う他の方法 -他の LLM プロバイダーは、さらに 3 つの方法で統合できます（code examples は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーは、さらに 3 つの方法で統合できます（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に適しています。設定可能な code examples は [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` レベルで設定します。これにより、「この実行でのすべての エージェント にカスタムモデルプロバイダーを使う」と指定できます。設定可能な code examples は [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 インスタンスでモデルを指定できます。これにより、エージェント ごとに異なるプロバイダーを組み合わせて使用できます。設定可能な code examples は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使う方法として、[LiteLLM 連携](./litellm.md) があります。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、グローバルに `AsyncOpenAI` インスタンスを LLM クライアントとして使いたい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能な code examples は [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` レベルにあります。これにより、「この実行のすべての エージェント にカスタムのモデルプロバイダーを使う」と指定できます。設定可能な code examples は [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 インスタンスにモデルを指定できます。これにより、異なる エージェント に対して異なるプロバイダーを組み合わせて使用できます。設定可能な code examples は [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) を設定することを推奨します。 !!! note - これらの code examples では、Responses API をまだサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの code examples では、Responses API/モデルではなく Chat Completions API/モデルを使用しています。これは、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーが対応している場合は、Responses の使用をおすすめします。 ## モデルの組み合わせ -単一のワークフロー内で、エージェント ごとに異なるモデルを使用したいことがあります。例えば、トリアージには小さく高速なモデルを使い、複雑なタスクにはより大きく高性能なモデルを使うといった形です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選択できます。 +単一のワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。例えば、振り分けには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使うといった具合です。[`Agent`][agents.Agent] を設定するとき、以下のいずれかで特定のモデルを選択できます。 1. モデル名を渡す。 -2. 任意のモデル名 + それを Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 -3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 +2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接提供する。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしますが、両者はサポートする機能やツールの集合が異なるため、ワークフローごとに単一のモデル形状を使用することを推奨します。ワークフローでモデル形状を混在させる場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + 本 SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、各ワークフローでは単一のモデル形状を使用することを推奨します。2 つの形状はサポートする機能やツールのセットが異なるためです。もしワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が双方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -122,10 +122,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデルの名前を直接設定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +1. OpenAI のモデル名を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェント で使用するモデルをさらに構成したい場合は、温度 (temperature) などの任意のモデル構成パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェント で使用するモデルをさらに細かく設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。これは temperature などの任意のモデル設定パラメーターを提供します。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、[他にもいくつか任意の パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで利用できない場合は、`extra_args` を使ってそれらを渡せます。 +また、OpenAI の Responses API を使う場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`, `service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` で渡せます。 ```python from agents import Agent, ModelSettings @@ -154,24 +154,24 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー使用時の一般的な問題 +## 他社 LLM プロバイダー利用時の一般的な問題 ### トレーシング クライアントのエラー 401 -トレーシング に関連するエラーが発生する場合、これはトレースが OpenAI サーバー にアップロードされ、OpenAI API キーを持っていないためです。解決には次の 3 つの選択肢があります。 +トレーシング に関連するエラーが発生する場合、これはトレースが OpenAI の サーバー にアップロードされる一方で、OpenAI の API キーをお持ちでないことが原因です。解決策は次の 3 つです。 -1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. トレーシング 用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものを使用する必要があります。 -3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシング ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシング を完全に無効化: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +2. トレーシング 用に OpenAI キーを設定: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 +3. 非 OpenAI のトレース プロセッサーを使用。 [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK は既定で Responses API を使用しますが、多くの他の LLM プロバイダーはまだ対応していません。その結果、404 などの問題が発生することがあります。解決するには、次のいずれかを行ってください。 +SDK はデフォルトで Responses API を使用しますが、多くの他社 LLM プロバイダーはまだ対応していません。そのため、404 などの問題が発生する場合があります。解決策は次の 2 つです。 1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](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) をサポートしていません。これにより、次のようなエラーが発生することがあります。 @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダーの制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないという問題です。現在これに対する修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することを推奨します。そうでない場合、不正な JSON によりアプリがしばしば壊れてしまいます。 +これは一部のモデルプロバイダー側の制限で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないというものです。現在この問題の修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダーに依存することをおすすめします。そうでない場合、JSON の形式が不正になることでアプリが頻繁に壊れる可能性があります。 -## プロバイダーをまたいだモデルの混在 +## プロバイダーをまたぐモデルの混在 -モデルプロバイダー間の機能差を把握しておかないと、エラーに直面する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしていますが、多くの他プロバイダーはこれらの機能に対応していません。以下の制約に注意してください。 +モデルプロバイダー間の機能差異に注意しないと、エラーに遭遇する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、多くの他社プロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 -- サポートしていない `tools` を理解しないプロバイダーに送信しないでください -- テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがある点に注意してください。 \ No newline at end of file +- サポートされていない `tools` を理解しないプロバイダーに送らないでください +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください +- structured JSON 出力をサポートしないプロバイダーでは、無効な JSON が生成されることがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index cc402f960..7dff14767 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 との統合は beta です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) に報告してください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK で任意の AI モデルを使えるように、LiteLLM 連携を追加しました。 +[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`、OpenAI の API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、Anthropic の API キー +- モデルには `openai/gpt-4.1`、API キーには OpenAI の API キー +- モデルには `anthropic/claude-3-5-sonnet-20240620`、API キーには Anthropic の API キー - など -LiteLLM でサポートされているモデルの全一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM でサポートされているモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 42b79fee5..95e222018 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内のエージェントの流れを指します。どのエージェントが、どの順番で実行され、次に何をするかをどう決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントが、どの順番で動作し、その後どう決めるのか。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定を任せる方法: LLM の知能を使って計画・推論し、それに基づいて取るべきステップを決定します。 -2. コードでオーケストレーションする方法: コードによってエージェントの流れを決めます。 +1. LLM に意思決定させる: LLM の知能を使って、計画・推論し、それに基づいて次に取るべきステップを決定します。 +2. コードでオーケストレーションする: コードによってエージェントの流れを決定します。 -これらのパターンは組み合わせて使えます。各方式にはトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせ可能です。それぞれにトレードオフがあります。以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、instructions、ツール、ハンドオフを備えた LLM です。これは、オープンエンドなタスクに対して、LLM が自律的にタスクの進め方を計画し、ツールを使って行動やデータ取得を行い、ハンドオフを使ってサブエージェントにタスクを委任できることを意味します。たとえば、リサーチ用のエージェントには次のようなツールを備えられます。 +エージェントは、 instructions、tools、handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたときに、LLM はタスクへの取り組み方を自律的に計画し、ツールを使って行動やデータ取得を行い、ハンドオフを使ってサブエージェントにタスクを委任できます。例えば、リサーチ用エージェントには次のようなツールを備えられます。 -- Web 検索によりオンラインで情報を見つける -- ファイル検索と取得によりプロプライエタリデータや接続を検索する -- コンピュータ操作によりコンピュータ上でアクションを実行する -- コード実行によりデータ分析を行う -- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索でオンライン情報を探す +- ファイル検索と取得で独自データや接続先を横断検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画立案、レポート作成などが得意な特化エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に頼りたい場合に有効です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知能に依拠したい場合に適しています。ここで重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべきパラメーターを明確にします。 -2. アプリを監視し、反復改善する。問題が起きる箇所を把握し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して優れたエージェントを用意する。 -5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練してタスク遂行能力を高められます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、守るべきパラメーターを明確にします。 +2. アプリを監視して反復する。どこで問題が起きるかを確認し、プロンプトを反復改善します。 +3. エージェントに内省と改善を許可する。例えばループで実行し、自己批評させる、またはエラーメッセージを提供して改善させます。 +4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して優れるエージェントを用意する。 +5. [Evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスクの遂行能力を向上できます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度・コスト・性能の観点でより決定的かつ予測可能にできます。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ、といった使い方です。 -- あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事の執筆を、リサーチ→アウトライン作成→本文作成→批評→改善という一連のステップに分解できます。 -- タスクを実行するエージェントを、評価とフィードバックを行うエージェントとともに `while` ループで回し、評価者が一定の基準を満たしたと判断するまで繰り返す。 -- 複数のエージェントを並列実行する（例: Python の基本コンポーネントである `asyncio.gather` を利用）。相互依存しない複数タスクがある場合に高速化に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次のエージェントを選択できます。 +- 複数のエージェントを連結し、1 つの出力を次の入力に変換する。ブログ記事の作成のようなタスクを、リサーチ、アウトライン作成、本文作成、批評、改善という一連のステップに分解できます。 +- タスクを実行するエージェントと評価・フィードバックを行うエージェントを `while` ループで回し、評価者が特定の基準を満たしたと判断するまで繰り返す。 +- 複数のエージェントを並列に実行する（例: Python の基本コンポーネントである `asyncio.gather` を使用）。相互に依存しない複数のタスクがある場合、速度向上に有用です。 [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 9625e4d84..e518cdac0 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは最初の 1 回だけ実行します。 +これは最初に 1 回だけ実施します。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行します。 +新しいターミナル セッションを開始するたびに実施します。 ```bash source .venv/bin/activate @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -お持ちでない場合は、[この手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +未作成の場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初のエージェントの作成 +## 最初の エージェント の作成 -エージェントは instructions、名前、および任意の config（たとえば `model_config`）で定義します。 +エージェントは instructions、名前、オプションの設定（`model_config` など）で定義します。 ```python from agents import Agent @@ -49,7 +49,7 @@ agent = Agent( ) ``` -## エージェントの追加 +## さらにいくつかの エージェント を追加 追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 @@ -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 @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてを組み合わせる +## 全体の統合 -ハンドオフと入力ガードレールを使って、すべてを組み合わせ、ワークフロー全体を実行しましょう。 +すべてをまとめて、ハンドオフと入力ガードレールを使い、ワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して、エージェント実行のトレースを表示してください。 +エージェント実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動し、エージェント実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェント フローの構築方法: +より複雑なエージェント フローの構築方法を学びましょう: -- [エージェント](agents.md) の設定について学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md) について学びます。 \ No newline at end of file +- Learn about how to configure [エージェント](agents.md). +- Learn about [エージェントの実行](running_agents.md). +- Learn about [ツール](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 52d8abc42..00e559215 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,59 +4,59 @@ search: --- # ガイド -このガイドでは、 OpenAI Agents SDK の realtime 機能を使って音声対応 AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、 OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 -!!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改良に伴い、破壊的変更が発生する可能性があります。 +!!! warning "Beta feature" +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、会話のフローを実現し、音声およびテキスト入力をリアルタイムに処理して、リアルタイム音声で応答します。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話と、割り込みへのスムーズな対応を可能にします。 +Realtime エージェントは、会話フローを実現し、音声とテキストの入力をリアルタイムに処理して、リアルタイム音声で応答します。OpenAI の Realtime API と永続的な接続を維持し、低遅延で自然な音声会話と、割り込みへのスムーズな対応を可能にします。 ## アーキテクチャ ### 中核コンポーネント -realtime システムは、いくつかの重要なコンポーネントで構成されます。 +realtime システムは、いくつかの主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、ハンドオフで設定されたエージェント。 +- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェント。 - **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデルのインターフェース（一般的には OpenAI の WebSocket 実装） +- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデル インターフェース（一般的には OpenAI の WebSocket 実装） -### セッションの流れ +### セッションフロー -一般的な realtime セッションは次の流れに従います。 +一般的な realtime セッションは次のフローに従います。 -1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 -2. **RealtimeRunner を設定** し、エージェントと構成オプションを渡します。 -3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返ります。 -4. **音声またはテキストメッセージを送信** します。`send_audio()` または `send_message()` を使用します。 -5. **イベントをリッスン** します。セッションをイテレートして、音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーなどのイベントを受け取ります。 -6. **割り込みに対応** します。ユーザーがエージェントの発話にかぶせた場合、進行中の音声生成は自動的に停止します。 +1. instructions、tools、handoffs を使用して **RealtimeAgent を作成** します。 +2. エージェントと設定オプションで **RealtimeRunner をセットアップ** します。 +3. `await runner.run()` を使用して **セッションを開始** します。RealtimeSession が返されます。 +4. `send_audio()` または `send_message()` を使用して **音声またはテキストメッセージを送信** します。 +5. セッションを反復処理して **イベントをリッスン** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザーがエージェントの発話に被せて話したときに **割り込みを処理** します。現在の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの永続的な接続を管理します。 -## エージェントの設定 +## エージェント設定 -RealtimeAgent は通常の Agent クラスと類似していますが、いくつか重要な相違があります。完全な API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご参照ください。 +RealtimeAgent は、通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデル選択はエージェントではなくセッション単位で設定します。 -- structured outputs のサポートはありません（`outputType` は非対応）。 -- 声質はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- ツール、ハンドオフ、instructions などのその他の機能は同様に動作します。 +- モデル選択はエージェント レベルではなく、セッション レベルで設定します。 +- structured outputs はサポートされません（`outputType` はサポートされません）。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- その他の機能（tools、handoffs、instructions）は同様に動作します。 -## セッションの設定 +## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの挙動を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、対応するモダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力・出力の両方で指定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-4o-realtime-preview` など）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、サポートするモダリティ（テキストや音声）を設定できます。音声フォーマットは入力と出力の両方で設定でき、既定は PCM16 です。 ### 音声設定 -音声設定は、セッションが音声の入出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の書き起こし、言語設定、ドメイン固有用語の精度向上に役立つ書き起こしプロンプトを設定できます。ターン検出設定では、エージェントがいつ応答を開始・終了すべきかを制御でき、音声活動検出のしきい値、無音時間、検出された発話周辺のパディングなどを指定できます。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper のようなモデルを使用した入力音声の文字起こし、言語設定、ドメイン固有用語の精度を高めるための文字起こしプロンプトを設定できます。応答開始・終了の検出（ターン検出）は、音声活動検出の閾値、無音時間、検出された発話の前後のパディングなどのオプションにより制御できます。 ## ツールと関数 @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、会話を専門化されたエージェント間で引き継げます。 +ハンドオフにより、特化したエージェント間で会話を移譲できます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーミングし、セッションオブジェクトをイテレートしてリッスンできます。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始/終了、エージェントのハンドオフ、エラーが含まれます。特に扱うべき主なイベントは次のとおりです。 +セッションは、セッションオブジェクトを反復処理することでリッスン可能なイベントをストリーム配信します。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に処理すべき主なイベントは次のとおりです。 -- **audio**: エージェントの応答からの raw 音声データ -- **audio_end**: エージェントの発話完了 +- **audio**: エージェントの応答の生の音声データ +- **audio_end**: エージェントの発話が終了 - **audio_interrupted**: ユーザーがエージェントを割り込み - **tool_start/tool_end**: ツール実行のライフサイクル -- **handoff**: エージェントのハンドオフ発生 +- **handoff**: エージェントのハンドオフが発生 - **error**: 処理中にエラーが発生 -完全なイベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +イベントの詳細は、[`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -realtime エージェントでサポートされるのは出力ガードレールのみです。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために（毎語ではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでサポートされるのは出力ガードレールのみです。パフォーマンス上の問題を避けるため、これらのガードレールはデバウンスされ、リアルタイム生成の最中でも定期的に（すべての単語ごとではなく）実行されます。既定のデバウンス長は 100 文字ですが、設定で変更可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースのガードレールは一緒に実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` から提供できます。両方のソースからのガードレールは併用して実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,17 +152,17 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断することがあります。デバウンス動作は、安全性とリアルタイム性能要件のバランスを取るのに役立ちます。テキストエージェントと異なり、realtime エージェントはガードレールがトリップしても Exception をスローしません。 +ガードレールがトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を中断できます。デバウンス動作は、安全性とリアルタイムのパフォーマンス要件のバランスを取るのに役立ちます。テキスト エージェントと異なり、realtime エージェントはガードレールが発火しても例外を発生させません。 ## 音声処理 -[`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 @@ -171,6 +171,6 @@ session.model.add_listener(my_custom_listener) これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`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 +完全な動作する code examples は、UI コンポーネントあり/なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 1bd1e8ec2..bb6700d60 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,10 +4,10 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声会話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントを作成する手順を説明します。 +リアルタイム エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声対話を可能にします。本ガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装改善に伴い、破壊的な変更が入る可能性があります。 ## 前提条件 @@ -79,7 +79,7 @@ async def main(): asyncio.run(main()) ``` -## 完全な例 +## 完全なコード例 以下は動作する完全な例です: @@ -135,38 +135,38 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 構成オプション +## 設定オプション ### モデル設定 -- `model_name`: 利用可能なリアルタイム モデルから選択（例: `gpt-4o-realtime-preview`） -- `voice`: 音声の選択（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） -- `modalities`: テキスト および/または 音声を有効化（`["text", "audio"]`） +- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-4o-realtime-preview`) +- `voice`: 音声を選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストや音声を有効化 (`["text", "audio"]`) ### 音声設定 -- `input_audio_format`: 入力音声の形式（`pcm16`、`g711_ulaw`、`g711_alaw`） +- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) - `output_audio_format`: 出力音声の形式 - `input_audio_transcription`: 文字起こしの設定 -### 発話区切り検出 +### ターン検出 -- `type`: 検出方法（`server_vad`、`semantic_vad`） -- `threshold`: 音声活動のしきい値（0.0–1.0） +- `type`: 検出方式 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動のしきい値 (0.0–1.0) - `silence_duration_ms`: ターン終了を検出する無音時間 - `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ - [リアルタイム エージェントの詳細](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作する code examples を確認 +- 動作するコードは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダを参照 - エージェントにツールを追加 - エージェント間のハンドオフを実装 -- 安全性のためにガードレールを設定 +- 安全性のためのガードレールを設定 ## 認証 -OpenAI API キーが環境に設定されていることを確認します: +OpenAI API キーが環境に設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/ja/release.md b/docs/ja/release.md index e15f96a08..a68ef7d59 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` ) バージョン -ベータではない公開インターフェースに対する破壊的変更がある場合、マイナー版 `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` を引数（arg）に取っていたいくつかの箇所が、代わりに `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] に 2 つの新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` をサブクラス化しているすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 2 つの新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承する任意のクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 42769bfdb..e326f0181 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -この SDK では、ターミナル上でエージェントの動作を素早く対話的にテストできる `run_demo_loop` を提供します。 +この SDK は、ターミナルでエージェントの挙動をすばやく対話的にテストできる `run_demo_loop` を提供します。 ```python @@ -19,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成されたモデル出力をそのままストリーミングします。上記の例を実行すると、 run_demo_loop は対話型のチャットセッションを開始します。入力を継続的に尋ね、ターン間で会話全体の履歴を記憶し（これによりエージェントは何が議論されたかを把握します）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 +`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成されたそばからモデルの出力をストリーミングします。上記の例を実行すると、`run_demo_loop` は対話型のチャットセッションを開始します。継続的に入力を求め、ターン間で会話全体の履歴を記憶し（そのためエージェントは何が話されたかを把握できます）、生成と同時にエージェントの応答をリアルタイムで自動でストリーミングします。 -このチャットセッションを終了するには、 `quit` または `exit` と入力（して Enter を押下）するか、 `Ctrl-D` キーボードショートカットを使用します。 \ No newline at end of file +このチャットセッションを終了するには、`quit` または `exit` と入力して（そして Enter を押す）、または `Ctrl-D` のキーボードショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index 3dba44265..62b86c079 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 実行結果 +# 結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: +`Runner.run` メソッドを呼び出すと、以下のいずれかが得られます。 -- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] -- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ここに最も有用な情報が含まれます。 +どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、最も有用な情報はここに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は、`last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `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] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。Run item は、LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフ が発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース／ターゲットのエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツール応答です。アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem]: LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem]: LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM のツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem]: LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]: ツールが呼び出されたことを示します。raw アイテムはツール応答です。アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem]: LLM の推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 -### ガードレールの実行結果 +### ガードレールの結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、該当する場合にガードレールの実行結果 が含まれます。ガードレールの実行結果 には、ログ記録や保存に役立つ有用な情報が含まれることがあるため、参照できるように提供しています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、存在する場合はガードレールの結果が含まれます。ガードレールの結果には、ログや保存に役立つ情報が含まれることがあるため、利用できるようにしています。 -### raw レスポンス +### Raw 応答 [`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。ほとんどの場合これを必要としませんが、必要なときのために利用可能です。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。多くの場合これは不要ですが、必要な場合に備えて利用できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 1c6846924..06d08ea72 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。オプションは 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。方法は 3 つあります。 1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリーミングします。 +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 は以下のループを実行します。 1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループは終了し、実行結果を返します。 - 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新して、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加して、ループを再実行します。 + 1. LLM が `final_output` を返した場合、ループを終了し、結果を返します。 + 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新して、ループを再実行します。 + 3. LLM が ツール呼び出し を行った場合、それらを実行し、結果を追加して、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM の出力が「最終出力」と見なされるルールは、目的の型のテキスト出力を生成し、ツール呼び出しがない場合です。 ## ストリーミング -ストリーミングにより、LLM の実行中にストリーミングイベントを受け取ることができます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に、その実行で生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すことで取得できます。詳しくは [ストリーミングガイド](streaming.md) をご覧ください。 +ストリーミング を使うと、LLM の実行中に ストリーミング イベントも受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に、その実行で生成されたすべての新規出力を含む、実行の完全な情報が格納されます。ストリーミング イベントは `.stream_events()` を呼び出して取得できます。詳細は [ストリーミング ガイド](streaming.md) を参照してください。 -## 実行設定 +## 実行設定 (Run config) -`run_config` パラメーターは、エージェント実行のグローバル設定を構成できます。 +`run_config` パラメーターでは、エージェント実行のグローバル設定をいくつか構成できます。 - [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関わらず、使用するグローバルな LLM モデルを設定できます。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーで、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。例えば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力のガードレールのリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに対して、まだ設定されていない場合に適用するグローバルな入力フィルターです。入力フィルターにより、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントをご覧ください。 +- [`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_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、潜在的に機微なデータをトレースに含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングにおけるワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にわたってトレースを関連付けるのに使えます。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話/チャットスレッド -任意の run メソッドを呼び出すと、1 つ以上のエージェントが実行される（つまり 1 回以上 LLM が呼び出される）可能性がありますが、これはチャット会話の 1 回の論理ターンを表します。例: +いずれの run メソッドを呼び出しても、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行されることがありますが、チャット会話における 1 つの論理的なターンを表します。例: 1. ユーザーのターン: ユーザーがテキストを入力 -2. ランナーの実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフし、2 番目のエージェントがさらにツールを実行し、その後に出力を生成します。 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントに ハンドオフ、2 つ目のエージェントがさらにツールを実行し、その後に出力を生成。 -エージェントの実行の最後に、ユーザーに何を表示するかを選べます。例えば、エージェントが生成したすべての新しいアイテムを表示することも、最終出力のみを表示することもできます。いずれの場合も、ユーザーが追質問をするかもしれません。その場合は再度 run メソッドを呼び出せます。 +エージェントの実行が終わったら、ユーザーに何を見せるかを選べます。たとえば、エージェントが生成したすべての新規アイテムを表示することも、最終出力だけを表示することもできます。いずれにせよ、ユーザーが追質問をするかもしれないので、その場合は再度 run メソッドを呼び出します。 -### 手動の会話管理 +### 手動での会話管理 -次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って、会話履歴を手動で管理できます。 +次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 ```python async def main(): @@ -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 は自動で以下を行います。 -- 各実行の前に会話履歴を取得 -- 各実行の後に新しいメッセージを保存 -- 異なるセッション 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`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外は、この汎用型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに渡した `max_turns` 制限を、エージェントの実行が超えたときに送出されます。指定された対話ターン数内にタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。例: - - 不正な JSON: 特定の `output_type` が定義されている場合に、ツール呼び出しや直接の出力として、不正な JSON 構造をモデルが返したとき。 - - 予期しないツール関連の失敗: モデルが想定どおりにツールを使用できなかったとき -- [`UserError`][agents.exceptions.UserError]: SDK を使用する（SDK を使ってコードを書く）あなたがエラーを起こした場合に送出されます。これは通常、不正なコード実装、無効な設定、または SDK の API の誤用に起因します。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 入力ガードレールまたは出力ガードレールの条件が満たされたときに、それぞれ送出されます。入力ガードレールは処理前に受信メッセージを確認し、出力ガードレールは配信前にエージェントの最終応答を確認します。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかのすべての特定の例外はここから派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `max_turns` 制限を超えたときに送出されます。`Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに適用されます。所定の対話ターン数内にタスクを完了できなかったことを示します。 +- [`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 9d62ab970..c3c820861 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行間で会話履歴を自動的に保持する組み込みの session メモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 +Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に保持する組み込みセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 -Sessions は特定の session の会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、エージェントが明示的な手動メモリ管理なしでコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターン会話を構築する際に特に有用です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -session メモリが有効な場合: +セッションメモリが有効な場合: -1. **各実行の前**: runner は session の会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が自動的に session に保存されます。 -3. **コンテキストの保持**: 同じ session での後続の実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 +1. **各実行前** : ランナーはセッションの会話履歴を自動で取得し、入力アイテムの先頭に追加します。 +2. **各実行後** : 実行中に生成された新しいアイテム (ユーザー入力、アシスタント応答、ツール呼び出しなど) はすべて自動的にセッションに保存されます。 +3. **コンテキストの保持** : 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出して、実行間の会話状態を管理する必要がなくなります。 +これにより、実行間で `.to_input_list()` を手動で呼び出したり、会話状態を管理したりする必要がなくなります。 ## メモリ操作 ### 基本操作 -Sessions は、会話履歴を管理するための複数の操作をサポートします: +セッションは会話履歴を管理するための複数の操作をサポートします: ```python from agents import SQLiteSession @@ -88,7 +88,7 @@ await session.clear_session() ### 修正のための pop_item の使用 -`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したい場合に特に有用です: +`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したい場合に特に役立ちます: ```python from agents import Agent, Runner, SQLiteSession @@ -119,7 +119,7 @@ print(f"Agent: {result.final_output}") ## メモリオプション -### メモリなし（デフォルト） +### メモリなし (デフォルト) ```python # Default behavior - no session memory @@ -170,11 +170,11 @@ result2 = await Runner.run( ### SQLAlchemy ベースのセッション -より高度なユースケースでは、SQLAlchemy ベースの session バックエンドを使用できます。これにより、session の保存に SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 +より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) をセッションストレージとして使用できます。 -**例 1: `from_url` とインメモリ SQLite を使用** +**例 1: `from_url` とインメモリ SQLite の使用** -これは最も簡単な始め方で、開発やテストに最適です。 +これは最も簡単な開始方法で、開発やテストに最適です。 ```python import asyncio @@ -195,9 +195,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy engine を使用** +**例 2: 既存の SQLAlchemy エンジンの使用** -本番アプリケーションでは、既に SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性が高いです。これを session に直接渡せます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性が高いです。これをセッションに直接渡せます。 ```python import asyncio @@ -228,7 +228,7 @@ if __name__ == "__main__": ## カスタムメモリ実装 -[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自の session メモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: ```python from agents.memory.session import SessionABC @@ -275,18 +275,18 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすい意味のある session 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")`）を使用します -- 既存のデータベースを SQLAlchemy がサポートする本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します -- より高度なユースケース向けに、他の本番システム（Redis、Django など）用のカスタム session バックエンドの実装を検討します +- 一時的な会話にはインメモリ SQLite (`SQLiteSession("session_id")`) を使用 +- 永続的な会話にはファイルベース SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用 +- 既存のデータベースを持つ本番システムには SQLAlchemy ベースのセッション (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) を使用 +- さらに高度なユースケースでは、他の本番システム (Redis、Django など) 向けにカスタムセッションバックエンドの実装を検討 ### セッション管理 @@ -314,7 +314,7 @@ result2 = await Runner.run( ## 完全な例 -以下は、session メモリの動作を示す完全な例です: +セッションメモリの動作を示す完全な例です: ```python import asyncio @@ -378,8 +378,8 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは以下を参照してください: +詳細な API ドキュメントは以下をご覧ください: -- [`Session`][agents.memory.Session] - プロトコルインターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 \ No newline at end of file +- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 7391c0a8c..1a02748f5 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、エージェント実行の進行に合わせて更新を購読できます。これは、エンドユーザーに進捗更新や部分的な応答を表示するのに役立ちます。 +ストリーミングを使うと、エージェントの実行が進むにつれて更新を購読できます。これはエンドユーザーに進捗や部分的な応答を表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより、[`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼ぶと、後述の [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼ぶと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 -## Raw レスポンスイベント +## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。形式は OpenAI Responses API で、各イベントは `response.created`、`response.output_text.delta` などのタイプとデータを持ちます。これらのイベントは、生成され次第ユーザーに応答メッセージをストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、 LLM から直接渡される raw なイベントです。これらは OpenAI Responses API フォーマットであり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。生成され次第、ユーザーへ応答メッセージをストリーミングしたい場合に有用です。 -例えば、以下は LLM が生成したテキストをトークンごとに出力します。 +たとえば、次の例は LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 実行アイテムイベントとエージェントイベント +## Run アイテムのイベントと エージェントのイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変化したとき（例: ハンドオフの結果として）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークンごとではなく「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を届けられます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果）に更新を提供します。 -例えば、以下は raw イベントを無視し、ユーザーに更新のみをストリーミングします。 +たとえば、次の例は raw イベントを無視して、ユーザーへ更新のみをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index c110ed0ca..ca30bc030 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント に行動を取らせます。たとえば、データ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作 などです。Agents SDK には 3 つのツールのクラスがあります。 +ツールは エージェント にアクションを取らせます。データ取得、コード実行、外部 API の呼び出し、さらにはコンピュータ操作 などです。Agents SDK には 3 つのツールのクラスがあります: -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 -- Function calling: 任意の Python 関数をツールとして使用できます。 -- ツールとしての エージェント: エージェント をツールとして利用でき、ハンドオフ せずに エージェント から別の エージェント を呼び出せます。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は リトリーバル、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして使用できます。 +- エージェントをツールとして利用: エージェント をツールとして使えるため、ハンドオフ せずにエージェント同士を呼び出せます。 ## ホスト型ツール -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供します。 +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 利用時にいくつかの組み込みツールを提供します: -- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web 検索 を実行させます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を行います。 -- [`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 @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして使用できます。Agents SDK がツールを自動的にセットアップします。 +任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的にセットアップします: -- ツール名は Python 関数名になります（任意で名前を指定可能） -- ツールの説明は関数の docstring から取得します（任意で説明を指定可能） -- 関数入力のスキーマは、関数の引数から自動的に作成されます -- 各入力の説明は、無効化しない限り関数の docstring から取得します +- ツール名は Python 関数名になります（または任意の名前を指定できます） +- ツールの説明は関数の docstring から取得します（または任意の説明を指定できます） +- 関数入力のスキーマは関数の引数から自動生成されます +- 各入力の説明は、無効化していない限り、関数の docstring から取得します -Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、スキーマ作成には `pydantic` を使用します。 +Python の `inspect` モジュールを使用して関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、スキーマ生成には pydantic を使用します。 ```python import json @@ -102,10 +102,10 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期どちらでも構いません。 -2. docstring があれば、説明文と引数の説明に利用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring の形式などを上書き設定することも可能です。 -4. デコレートした関数をツール一覧に渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期いずれでも構いません。 +2. docstring があれば、説明および引数の説明の取得に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数でなければなりません）。ツール名や説明、docstring のスタイルなどを上書き設定することもできます。 +4. デコレートした関数をツールのリストに渡せます。 ??? note "出力を表示" @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。必要に応じて直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を指定する必要があります。 +Python 関数をツールとして使いたくない場合もあります。必要に応じて、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: -- `name` -- `description` -- `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列の引数を受け取り、ツールの出力を文字列で返す非同期関数） +- `name` +- `description` +- `params_json_schema`（引数の JSON スキーマ） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツールの出力文字列を返す async 関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足事項は以下のとおりです。 +前述の通り、関数シグネチャを自動解析してツールのスキーマを抽出し、docstring を解析してツールや各引数の説明を抽出します。補足事項: -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を解釈し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。対応フォーマットは `google`、`sphinx`、`numpy` です。docstring の形式は自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に指定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することも可能です。 +1. シグネチャ解析は `inspect` モジュールで行います。引数の型は型アノテーションから解釈し、全体スキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。サポートしている docstring フォーマットは `google`、`sphinx`、`numpy` です。docstring 形式は自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示指定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することも可能です。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## ツールとしての エージェント +## ツールとしてのエージェント -ワークフローによっては、制御をハンドオフ する代わりに、中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。これは エージェント をツールとしてモデリングすることで実現できます。 +一部のワークフローでは、ハンドオフ せずに、中央の エージェント が専門 エージェント のネットワークをオーケストレーションしたい場合があります。エージェント をツールとしてモデリングすることで実現できます。 ```python from agents import Agent, Runner @@ -269,7 +269,7 @@ async def main(): ### ツール化したエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント をツール化するための簡便なメソッドです。ただし、すべての設定をサポートするわけではありません。たとえば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 +`agent.as_tool` 関数は、エージェント を簡単にツールへ変換するためのユーティリティです。ただし、すべての設定をサポートしているわけではありません。たとえば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 出力のカスタム抽出 +### カスタム出力抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に有用です。 +場合によっては、中央の エージェント に返す前に ツール化したエージェント の出力を加工したいことがあります。例えば次のような場合に有用です: -- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 -- エージェント の最終回答を変換または再整形する（例: Markdown をプレーンテキストや CSV に変換）。 +- サブエージェントのチャット履歴から特定情報（例: JSON ペイロード）を抽出する。 +- エージェント の最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 - 出力を検証し、エージェント の応答が欠落または不正な場合にフォールバック値を提供する。 -これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます。 +これは、`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 条件付きツール有効化 -`is_enabled` パラメーター を使用して、実行時に エージェント ツールを条件付きで有効・無効にできます。これにより、コンテキスト、ユーザー の嗜好、実行時条件に基づいて、LLM に提供されるツールを動的に絞り込めます。 +実行時に `is_enabled` パラメーター を使って エージェント ツールを条件付きで有効・無効にできます。これにより、コンテキスト、ユーザー の設定、実行時条件に基づいて、LLM に提供するツールを動的にフィルタリングできます。 ```python import asyncio @@ -372,24 +372,24 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーター は次を受け付けます。 -- **ブール値**: `True`（常に有効）または `False`（常に無効） -- **呼び出し可能な関数**: `(context, agent)` を受け取り、真偽値を返す関数 -- **非同期関数**: 複雑な条件ロジック用の async 関数 +`is_enabled` パラメーター は次を受け付けます: +- **Boolean values**: `True`（常に有効）または `False`（常に無効） +- **Callable functions**: `(context, agent)` を取り、真偽値を返す関数 +- **Async functions**: 複雑な条件ロジック向けの非同期関数 -無効化されたツールは実行時に LLM から完全に隠蔽されるため、次の用途に有用です。 +無効化されたツールは実行時に LLM から完全に隠されるため、以下に有用です: - ユーザー 権限に基づく機能ゲーティング -- 環境別のツール可用性（dev と prod） +- 環境別のツール可用性（開発 vs 本番） - 異なるツール構成の A/B テスト - 実行時状態に基づく動的ツールフィルタリング ## 関数ツールでのエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラー応答を提供する関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラーレスポンスを提供する関数です。 -- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 -- 独自のエラー関数を渡した場合はそれが実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、呼び出し側で処理する必要があります。これは、モデルが不正な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などになり得ます。 +- 既定（何も渡さない場合）では、エラーが発生したことを LLM に伝える `default_tool_error_function` を実行します。 +- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送られます。 +- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、あなたが処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、あなたのコードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 52912abd1..681098c2f 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェント実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタム イベントまで含まれます。 [Traces ダッシュボード](https://platform.openai.com/traces) を使用して、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシングが組み込まれており、エージェント実行中に発生するイベントの包括的な記録（ LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで）を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。トレーシングを無効にする方法は 2 つあります。 + トレーシングはデフォルトで有効です。トレーシングを無効にする方法は 2 つあります: - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化できます - 2. 1 回の実行については、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます + 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます -*** ZDR (Zero Data Retention) ポリシーの下で OpenAI の API を使用して運用する組織では、トレーシングは利用できません。 *** +***OpenAI の API を使用し、 Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- ** トレース ** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります。 - - `workflow_name`: これは論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースをリンクするために使用します。例えばチャット スレッド ID を使うことができます。 +- **トレース** は「ワークフロー」の単一のエンドツーエンドの処理を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。渡さなかった場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 省略可能なグループ ID。同一の会話からの複数のトレースを関連付けるために使用します。たとえば、チャットスレッド ID を使用できます。 - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースの任意のメタデータ。 -- ** スパン ** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。 + - `metadata`: トレースのためのオプションのメタデータ。 +- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには次が含まれます: - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` - - 親スパン (ある場合) を指す `parent_id` - - スパンに関する情報である `span_data`。例えば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます。 + - 親スパン（ある場合）を指す `parent_id` + - スパンに関する情報である `span_data`。例えば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM の生成に関する情報などを含みます。 ## デフォルトのトレーシング -デフォルトで、SDK は次をトレースします。 +デフォルトでは、 SDK は次をトレースします: -- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます -- エージェントが実行されるたびに `agent_span()` でラップされます -- LLM 生成は `generation_span()` でラップされます +- `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()` の下に親子付けされる場合があります +- 音声入力（音声認識）は `transcription_span()` でラップされます +- 音声出力（テキスト読み上げ）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親子関係で配置される場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定でき、または [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 -さらに、[custom trace processors](#custom-tracing-processors) を設定して、トレースを別の宛先にプッシュできます (置き換えまたは副次的な宛先として)。 +さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、別の送信先（置き換えまたはセカンダリ送信先）にトレースを送ることができます。 -## 上位レベルのトレース +## 高レベルのトレース -`run()` への複数回の呼び出しを単一のトレースの一部にしたい場合があります。これは、コード全体を `trace()` でラップすることで実現できます。 +複数回の `run()` 呼び出しを単一のトレースの一部にしたい場合があります。これは、コード全体を `trace()` でラップすることで行えます。 ```python from agents import Agent, Runner, trace @@ -68,43 +68,42 @@ async def main(): ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。実施方法は 2 つあります。 +[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始して終了する必要があります。次の 2 つの方法があります: -1. ** 推奨 **: トレースをコンテキスト マネージャとして使用します。つまり、`with trace(...) as my_trace`。これにより適切なタイミングで自動的に開始・終了します。 +1. 【推奨】トレースをコンテキストマネージャーとして使用します（例: `with trace(...) as my_trace`）。これにより、適切なタイミングで自動的にトレースが開始・終了されます。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。これは、自動的に並行実行で機能することを意味します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。これは、自動的に並行処理で機能することを意味します。トレースを手動で開始・終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般的に、スパンを手動で作成する必要はありません。カスタム スパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が用意されています。 +各種の [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために、[`custom_span()`][agents.tracing.custom_span] 関数が利用できます。 -スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される最も近い現在のスパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される、最も近い現在のスパンの下にネストされます。 -## 機微なデータ +## 機微（センシティブ）データ -一部のスパンは機微なデータを取得する可能性があります。 +一部のスパンは、機微なデータを取得する可能性があります。 -`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使用してそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそれらのデータの取得を無効化できます。 -同様に、音声スパンにはデフォルトで入力および出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成して、この音声データの取得を無効化できます。 +同様に、音声スパンにはデフォルトで入力および出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。 ## カスタム トレーシング プロセッサー -トレーシングの高レベル アーキテクチャは次のとおりです。 +トレーシングのハイレベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。これはトレースの作成を担当します。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を構成し、これはトレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。エクスポーターはスパンとトレースを OpenAI バックエンドにバッチでエクスポートします。 +- 初期化時に、トレースを作成する役割を持つグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 +- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、スパンとトレースをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。これが、スパンとトレースをバッチで OpenAI のバックエンドにエクスポートします。 -このデフォルト設定をカスタマイズして、トレースを代替または追加のバックエンドに送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります。 +このデフォルト設定をカスタマイズして、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポーターの動作変更を行うには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースとスパンが準備できたときに受け取る ** 追加の ** トレース プロセッサーを追加できます。これにより、トレースを OpenAI のバックエンドに送信することに加えて、独自の処理を実行できます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレース プロセッサーに ** 置き換える ** ことができます。つまり、OpenAI バックエンドにトレースを送信する `TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備できたタイミングで受け取る、**追加の** トレースプロセッサーを追加できます。これにより、 OpenAI のバックエンドへの送信に加えて独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを自分のトレースプロセッサーに**置き換える**ことができます。これは、 OpenAI のバックエンドにトレースが送信されなくなることを意味します（その役割を果たす `TracingProcessor` を含めない限り）。 +## Non-OpenAI Models でのトレーシング -## OpenAI 以外のモデルでのトレーシング - -OpenAI の API キーを OpenAI 以外のモデルで使用して、トレーシングを無効にすることなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 +OpenAI の API キーを Non-OpenAI Models と併用することで、トレーシングを無効化せずに OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -125,9 +124,8 @@ agent = Agent( ) ``` -## 注意 -- 無料のトレースは OpenAI Traces ダッシュボードで確認できます。 - +## 注意事項 +- OpenAI Traces ダッシュボードで無料のトレースを表示します。 ## 外部トレーシング プロセッサー一覧 diff --git a/docs/ja/usage.md b/docs/ja/usage.md index c3ced94c4..730817710 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -4,21 +4,21 @@ search: --- # 使用状況 -Agents SDK は、各実行のトークン使用量を自動で追跡します。実行コンテキストから参照し、コストの監視、制限の適用、分析の記録に利用できます。 +Agents SDK は、すべての実行ごとにトークン使用状況を自動追跡します。実行コンテキストから参照でき、コストの監視、上限の適用、分析記録に利用できます。 ## 追跡対象 -- **requests**: 行われた LLM API 呼び出し回数 -- **input_tokens**: 送信された入力トークンの合計 -- **output_tokens**: 受信した出力トークンの合計 -- **total_tokens**: 入力 + 出力 -- **details**: +- **requests** : LLM API 呼び出し回数 +- **input_tokens** : 送信した入力トークン合計 +- **output_tokens** : 受信した出力トークン合計 +- **total_tokens** : 入力 + 出力 +- **details** : - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 実行からの使用状況へのアクセス +## 実行からの使用状況の取得 -`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況にアクセスできます。 +`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況にアクセスします。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 +使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）にわたり集計されます。 -## セッションでの使用状況へのアクセス +## セッションでの使用状況の取得 -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各実行の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行の使用状況を返します。セッションはコンテキストのために会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -46,11 +46,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -なお、セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しが返す使用状況の指標は、その時点の実行結果のみを表します。セッションでは、前のメッセージが各実行の入力として再投入されることがあり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況の指標はその実行に限られます。セッションでは、前のメッセージが各実行に入力として再投入されることがあり、その結果、後続ターンの入力トークン数に影響します。 ## フックでの使用状況の利用 -`RunHooks` を使用する場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクル時点で使用状況を記録できます。 +`RunHooks` を使用する場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクル上の重要なタイミングで使用状況を記録できます。 ```python class MyHooks(RunHooks): @@ -61,8 +61,8 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは以下を参照してください: +詳細な API ドキュメントは次を参照してください: - [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況へアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡ライフサイクルへのフック \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 使用状況の追跡ライフサイクルにフックする \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 6b646fb56..5b5872874 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,7 +4,7 @@ search: --- # エージェントの可視化 -エージェントの可視化では、 **Graphviz** を用いてエージェントとその関係を構造化されたグラフィカル表現で生成できます。これはアプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を使用して、エージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は以下のような有向グラフを作成します: - **エージェント** は黄色のボックスで表されます。 -- ** MCP サーバー** は灰色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 - **ツール** は緑の楕円で表されます。 -- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジです。 +- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -67,38 +67,38 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェント グラフ](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -これは **トリアージ エージェント** と、そのサブエージェントやツールへの接続構造を視覚的に表すグラフを生成します。 +これは、 **triage agent** の構造と、そのサブエージェントやツールへの接続を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されるグラフには次が含まれます: +生成されたグラフには次が含まれます: -- エントリーポイントを示す **開始ノード**（`__start__`）。 +- エントリーポイントを示す **start ノード** (`__start__`)。 - 黄色で塗りつぶされた **長方形** で表されるエージェント。 - 緑で塗りつぶされた **楕円** で表されるツール。 - 灰色で塗りつぶされた **長方形** で表される MCP サーバー。 - 相互作用を示す有向エッジ: - - エージェント間ハンドオフには **実線の矢印**。 - - ツール呼び出しには **点線の矢印**。 - - MCP サーバー呼び出しには **破線の矢印**。 -- 実行の終了箇所を示す **終了ノード**（`__end__`）。 + - エージェント間のハンドオフを表す **実線の矢印**。 + - ツール呼び出しを表す **点線の矢印**。 + - MCP サーバー呼び出しを表す **破線の矢印**。 +- 実行が終了する場所を示す **end ノード** (`__end__`)。 -**注意:** MCP サーバーは最近の `agents` パッケージでレンダリングされます（ **v0.2.8** で検証済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**Note:** MCP サーバーは、最近の `agents` package のバージョンでレンダリングされます（ **v0.2.8** で確認済み）。可視化で MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`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 eec59540b..41cb9d60f 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント型ワークフローを音声アプリに変換するのを容易にするクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理を行います。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントによるワークフローを音声アプリに変換しやすくするクラスです。実行したいワークフローを渡すと、入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、そしてワークフローの出力を音声に戻す処理をパイプラインが担います。 ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成するとき、以下を設定できます。 +パイプラインを作成する際、次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]（新しい音声が文字起こしされるたびに実行されるコード） +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]。次のような項目を設定できます: +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 次のような項目を設定できます。 - モデルプロバイダー（モデル名をモデルにマッピングできます） - トレーシング（トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） - - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） + - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型 など） ## パイプラインの実行 パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の書き起こしがあり、その結果だけを生成したいときに使います。これは、話者の発話終了を検出する必要がない場合に便利です。たとえば、事前録音された音声や、ユーザーの発話終了が明確なプッシュ・トゥ・トーク型アプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検出する必要がある場合に使用します。検出に合わせて音声チャンクをプッシュでき、音声パイプラインは「アクティビティ検出」によって適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput]: 完全な音声があり、その結果だけを生成したい場合に使います。話者が話し終えたタイミングの検出が不要なケース、たとえば録音済み音声や、ユーザーが話し終えるタイミングが明確なプッシュトゥトーク アプリで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]: ユーザーが話し終えたタイミングの検出が必要になり得る場合に使います。検出された音声チャンクを順次プッシュでき、パイプラインは「アクティビティ検出」により適切なタイミングで自動的にエージェントのワークフローを実行します。 ## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生するイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 +音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生するイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次のものを含みます。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]（音声チャンクを含みます） -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]（ターンの開始・終了などのライフサイクルイベントを通知します） -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]（エラーイベントです） +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]: 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]: ターンの開始や終了など、ライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]: エラーイベントです。 ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンについてワークフローの別個の実行をトリガーします。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示し、`turn_ended` は該当ターンのすべての音声が送出された後にトリガーされます。これらのイベントを用いて、モデルがターンを開始したときに話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にミュート解除するといった制御が可能です。 \ No newline at end of file +Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとにワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] のイベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が始まったことを示し、`turn_ended` は該当ターンの音声がすべて送出された後に発火します。これらのイベントを使って、モデルがターンを開始したら話者のマイクをミュートし、そのターンに関連する音声をすべてフラッシュした後にミュート解除する、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 7382ee2d4..3976080b7 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境を設定してください。次に、SDK から音声用の省略可能な依存関係をインストールします。 +Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -中心となる概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。 +主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです: -1. 音声認識モデルで音声をテキスト化します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行して、結果を生成します。 -3. 音声合成モデルで結果のテキストを音声に戻します。 +1. 音声をテキストに変換するために音声認識モデルを実行します。 +2. 通常はエージェントのワークフローであるあなたのコードを実行して、結果を生成します。 +3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定します。これは、この SDK でエージェントを作成したことがあれば馴染みがあるはずです。ここでは、2 つのエージェント、ハンドオフ、そして 1 つのツールを用意します。 +まず、いくつかのエージェントをセットアップします。この SDK でエージェントを作成したことがあれば、見覚えがあるはずです。ここでは複数のエージェント、ハンドオフ、そして 1 つのツールを用意します。 ```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 d9a7797d5..352b9df6c 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]: 音声の書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用で、ワークフロー内部で起こることには適用されません。 +- [`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 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース Workflow の名前。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるためのトレースの `group_id`。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータ。 \ No newline at end of file diff --git a/docs/scripts/translate_docs.py b/docs/scripts/translate_docs.py index bb8a2be5b..704638149 100644 --- a/docs/scripts/translate_docs.py +++ b/docs/scripts/translate_docs.py @@ -136,6 +136,27 @@ def built_instructions(target_language: str, lang_code: str) -> str: - Fenced code blocks delimited by ``` or ~~~, including all comments inside them. - Link URLs inside `[label](URL)` – translate the label, never the URL. +######################### +## HARD CONSTRAINTS ## +######################### +- Never insert spaces immediately inside emphasis markers. Use `**bold**`, not `** bold **`. +- Preserve the number of emphasis markers from the source: if the source uses `**` or `__`, keep the same pair count. +- Ensure one space after heading markers: `##Heading` -> `## Heading`. +- Ensure one space after list markers: `-Item` -> `- Item`, `*Item` -> `* Item` (does not apply to `**`). +- Trim spaces inside link/image labels: `[ Label ](url)` -> `[Label](url)`. + +########################### +## GOOD / BAD EXAMPLES ## +########################### +- Good: This is **bold** text. +- Bad: This is ** bold ** text. +- Good: ## Heading +- Bad: ##Heading +- Good: - Item +- Bad: -Item +- Good: [Label](https://example.com) +- Bad: [ Label ](https://example.com) + ######################### ## LANGUAGE‑SPECIFIC ## ######################### @@ -159,6 +180,7 @@ def built_instructions(target_language: str, lang_code: str) -> str: ## EXTRA GUIDELINES ## ######################### {specific_instructions} +- When translating Markdown tables, preserve the exact table structure, including all delimiters (|), header separators (---), and row/column counts. Only translate the cell contents. Do not add, remove, or reorder columns or rows. ######################### ## IF UNSURE ## @@ -173,7 +195,11 @@ 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. Self-review your translation to ensure high quality, focusing on naturalness, accuracy, and consistency while avoiding unnecessary changes or spacing. +3. Perform a self-review to check for the following common issues: + - Naturalness, accuracy, and consistency throughout the text. + - Spacing inside markdown syntax such as `*` or `_`; `**bold**` is correct whereas `** bold **` is not. + - Unwanted spaces inside link or image labels, such as `[ Label ](url)`. + - Headings or list markers missing a space after their marker. 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. @@ -208,7 +234,7 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None: code_block_chunks.append(line) if in_code_block is True: code_blocks.append("\n".join(code_block_chunks)) - current_chunk.append(f"CODE_BLOCK_{(len(code_blocks) - 1):02}") + current_chunk.append(f"CODE_BLOCK_{(len(code_blocks) - 1):03}") code_block_chunks.clear() in_code_block = not in_code_block continue @@ -250,7 +276,7 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None: translated_text = "\n".join(translated_content) for idx, code_block in enumerate(code_blocks): - translated_text = translated_text.replace(f"CODE_BLOCK_{idx:02}", code_block) + translated_text = translated_text.replace(f"CODE_BLOCK_{idx:03}", code_block) # FIXME: enable mkdocs search plugin to seamlessly work with i18n plugin translated_text = SEARCH_EXCLUSION + translated_text