diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 115689b62..c2d7ced57 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは、指示とツールで構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる基本コンポーネントです。エージェントは、instructions と tools で構成された大規模言語モデル（LLM）です。 ## 基本設定 -エージェントでよく設定するプロパティは次のとおりです。 +エージェントで最も一般的に設定するプロパティは次のとおりです。 - `name`: エージェントを識別する必須の文字列です。 -- `instructions`: 開発者メッセージまたはシステムプロンプトとも呼ばれます。 -- `model`: 使用する LLM と、任意の `model_settings` を指定します（ temperature、 top_p などのモデル調整パラメーター）。 -- `tools`: エージェントがタスクを達成するために使用できるツール。 +- `instructions`: developer message または 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 オブジェクトを指定できます。 ```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 @@ -77,7 +77,7 @@ agent = Agent( ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、状況に応じてエージェントがそれらへ委譲できます。これは、単一のタスクに秀でたモジュール式の専門エージェントをオーケストレーションする強力なパターンです。詳しくは [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを提供すると、エージェントは関連があればそれらに委任できます。これは、単一のタスクに特化して優れた能力を発揮する、モジュール式の専門エージェントをオーケストレーションできる強力なパターンです。詳しくは [handoffs](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -96,9 +96,9 @@ triage_agent = Agent( ) ``` -## 動的な指示 +## 動的 instructions -多くの場合、エージェント作成時に指示を指定できます。ただし、関数経由で動的な指示を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも利用できます。 +多くの場合、エージェントの作成時に instructions を指定できますが、関数を介して動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `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](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`: LLM にツールの使用を要求します（どのツールを使うかは賢く選択します）。 +3. `none`: LLM にツールを使用しないことを要求します。 +4. 具体的な文字列（例: `my_tool`）を設定すると、LLM にその特定のツールの使用を要求します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -163,11 +163,11 @@ agent = Agent( ) ``` -## ツール使用の挙動 +## ツール使用時の挙動 -`Agent` の構成にある `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します: -- `"run_llm_again"`: 既定。ツールを実行し、 LLM がその結果を処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM による処理なしで最終応答として使用します。 +`Agent` 構成の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 +- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 +- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、追加の LLM 処理なしで最終応答として使用します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -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 42fb8f7ab..4665d346a 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 を使用します。これを上書きして Chat Completions API を使うには、[set_default_openai_api()][agents.set_default_openai_api] 関数を使用してください。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効です。既定では、上のセクションの OpenAI API キー（つまり、環境変数またはあなたが設定したデフォルト キー）を使用します。トレーシングに使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用します。 +トレーシングはデフォルトで有効です。デフォルトでは上記の OpenAI API キー（つまり環境変数、または設定したデフォルトキー）を使用します。トレーシングに使用する API キーを個別に設定するには、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -また、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数でトレーシングを完全に無効化できます。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用すると、トレーシングを完全に無効化することもできます。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグ ロギング +## デバッグログ -SDK には、ハンドラーが設定されていない Python のロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に送られますが、その他のログは抑制されます。 +SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これにより warnings と errors が `stdout` に送られ、その他のログは抑制されます。 -詳細なロギングを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログ出力を有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳しくは [Python のロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳しくは [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -83,15 +83,15 @@ 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 ac71085a2..022ba9d83 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. LLMs に提供されるコンテキスト: 応答生成時に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです: +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティによって表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的なパターンは、 dataclass や Pydantic オブジェクトを使うことです。 -2. そのオブジェクトを各種の実行メソッドに渡します (例えば `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 "注意" - コンテキストオブジェクトは LLM に **送信されません**。あくまでローカルなオブジェクトであり、読み取り・書き込みやメソッド呼び出しができます。 + コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルなオブジェクトで、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることが分かります。ツールの実装はコンテキストから読み取ります。 -3. エージェントにジェネリックな `UserInfo` を付けることで、型チェッカーが誤りを検出できます (例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など)。 -4. コンテキストは `run` 関数に渡されます。 -5. エージェントは正しくツールを呼び出し、年齢を取得します。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることがわかります。ツールの実装ではコンテキストから読み取ります。 +3. 型チェッカーがエラーを検出できるよう、エージェントにジェネリックの `UserInfo` を指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +4. `run` 関数にコンテキストを渡します。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント / LLM コンテキスト -LLM を呼び出したとき、LLM が見られるのは会話履歴にあるデータだけです。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴に現れる形で提供しなければなりません。方法はいくつかあります: +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴にあるものだけです。したがって、新しいデータを 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 検索) から関連データを取得できる特別なツールです。応答を関連するコンテキストデータで「根拠付け (grounding)」するのに役立ちます。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは "system prompt" や "developer message" とも呼ばれます。System prompt は静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 +2. `Runner.run` を呼び出すときの `input` に追加します。これは `instructions` と似た手法ですが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できます。 +3. 関数ツールで公開します。これはオンデマンドのコンテキストに有用です。LLM が必要なタイミングを判断し、ツールを呼び出してそのデータを取得できます。 +4. 検索（retrieval）や Web 検索を使用します。これらは、ファイルやデータベースから関連データを取得（retrieval）したり、Web から取得（Web 検索）したりできる特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index d976d21a8..84296ced4 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,45 +4,46 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご覧ください。これらの例は、異なるパターンや機能を示す複数の カテゴリー に整理されています。 ## カテゴリー -- **[エージェントパターン (agent_patterns)](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーのコード例では、一般的なエージェントの設計パターンを示します。たとえば次のとおりです +- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** + このカテゴリーの例では、次のような一般的な エージェント の設計パターンを示します - 決定的なワークフロー - - ツールとしてのエージェント - - エージェントの並列実行 + - ツールとしての エージェント + - エージェント の並列実行 -- **[基本 (basic)](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらのコード例では、 SDK の基礎的な機能を扱います。たとえば +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + これらの例では、次のような SDK の基礎的な機能を紹介します - - 動的なシステムプロンプト + - 動的な system prompt - ストリーミング出力 - ライフサイクルイベント -- **[ツールのコード例 (tool examples)](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索やファイル検索などのOpenAIがホストするツールを実装し、エージェントに統合する方法を学べます。 +- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法を学び、 + それらを エージェント に統合する方法を確認できます。 -- **[モデルプロバイダー (model providers)](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI以外のモデルを SDK で使う方法を紹介します。 +- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + SDK で OpenAI 以外のモデルを使用する方法を探求します。 -- **[ハンドオフ (handoffs)](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフの実用的な例をご覧ください。 +- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + エージェントの ハンドオフ の実用例をご覧ください。 -- **[MCP (mcp)](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCPを使ってエージェントを構築する方法を学びます。 +- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** + MCP で エージェント を構築する方法を学びます。 -- **[カスタマーサービス (customer_service)](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[リサーチボット (research_bot)](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 実世界のアプリケーションを示す、より作り込まれたコード例が 2 つあります +- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** + 実世界のアプリケーションを示す、より作り込まれた 2 つの例 - - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 - - **research_bot**: シンプルなディープリサーチ クローン。 + - **customer_service**: 航空会社向けのカスタマーサービスシステム。 + - **research_bot**: シンプルな ディープリサーチ のクローン。 -- **[音声 (voice)](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 音声エージェントのコード例をご覧ください。TTS と STT モデルを使用しています。 +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + 当社の TTS と STT モデルを用いた音声 エージェント の例をご覧ください。 -- **[リアルタイム (realtime)](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイムな体験を構築する方法を示すコード例。 \ No newline at end of file +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使ってリアルタイムな体験を構築する例。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index 61605a170..91cab83dd 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは、エージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を行えます。例えば、顧客からのリクエストに対応するために、非常に賢い（そのため遅くて高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーに、数学の宿題を手伝うようモデルに依頼させたくはありません。そこで、高速かつ低コストなモデルでガードレールを実行できます。ガードレールが不正な利用を検知した場合は、直ちにエラーを送出して高価なモデルの実行を止め、時間とコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックや検証を行います。たとえば、非常に高性能（そのぶん遅く/高価）なモデルでカスタマーリクエストを支援するエージェントがあるとします。悪意のあるユーザーが、そのモデルに数学の宿題を手伝わせるよう求めることは避けたいはずです。そのため、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意ある使用を検知すると、即座にエラーを送出し、高価なモデルの実行を止め、時間とコストを節約できます。 ガードレールには 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 @@ -94,9 +94,9 @@ async def main(): print("Math homework guardrail tripped") ``` -1. このエージェントをガードレール関数で使用します。 +1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果に追加情報を含められます。 +3. ガードレール結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 77dce60a8..8385bfcfc 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # Handoffs -Handoffs は、エージェントが別のエージェントにタスクを委譲できるようにします。これは、異なるエージェントがそれぞれ異なる領域に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、 FAQ などのタスクを個別に担当するエージェントがいるかもしれません。 +Handoffs により、ある エージェント が別の エージェント にタスクを委譲できます。これは、異なる エージェント がそれぞれ異なる分野を専門とするシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ担当する エージェント がいるかもしれません。 -Handoffs は LLM にはツールとして表現されます。そのため、`Refund Agent` という名前のエージェントへハンドオフする場合、ツール名は `transfer_to_refund_agent` になります。 +Handoffs は LLM に対してツールとして表現されます。例えば `Refund Agent` という エージェント にハンドオフする場合、そのツール名は `transfer_to_refund_agent` になります。 -## ハンドオフの作成 +## Handoff の作成 -すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは直接 `Agent` を受け取るか、ハンドオフをカスタマイズする `Handoff` オブジェクトを受け取れます。 +すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは直接 `Agent` を受け取るか、Handoff をカスタマイズする `Handoff` オブジェクトを受け取ります。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントを指定し、任意のオーバーライドや入力フィルターを設定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使って handoff を作成できます。この関数では、ハンドオフ先の エージェント を指定し、任意でオーバーライドや入力フィルターを設定できます。 ### 基本的な使い方 -シンプルなハンドオフの作り方は次のとおりです。 +簡単な handoff の作成方法は次のとおりです。 ```python from agents import Agent, handoff @@ -28,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェントを直接使う方法（`billing_agent` のように）と、`handoff()` 関数を使う方法のどちらでも構いません。 +1. `billing_agent` のように エージェント を直接渡すことも、`handoff()` 関数を使うこともできます。 -### `handoff()` 関数による handoffs のカスタマイズ +### `handoff()` 関数による handoff のカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数でカスタマイズできます。 +[`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフ先のエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使われ、`transfer_to_` に解決されます。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが起動されることが分かった時点でデータ取得を開始する、といった用途に便利です。この関数はエージェントのコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフが受け取る想定の入力の型（任意）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。 +- `agent`: ハンドオフ先の エージェント です。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使用され、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` の既定のツール説明を上書きします。 +- `on_handoff`: handoff が呼び出されたときに実行されるコールバック関数です。これは、handoff が実行されることが分かった時点でデータ取得を開始するなどに便利です。この関数は エージェント のコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: handoff が期待する入力の型（任意）。 +- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は以下を参照してください。 ```python from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフの入力 +## Handoff の入力 -状況によっては、ハンドオフを呼び出す際に LLM からいくつかのデータを提供してほしいことがあります。たとえば、「エスカレーション エージェント」へのハンドオフを想定してください。記録のために理由を受け取りたい、ということがあるでしょう。 +状況によっては、handoff を呼び出す際に LLM にデータの提供を求めたい場合があります。例えば「エスカレーション エージェント」への handoff を想定してください。記録のために理由を提供してほしい、というようなケースです。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を閲覧できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +handoff が発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を参照できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -よくあるパターン（たとえば履歴からすべてのツール呼び出しを取り除くなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +一般的なパターン（例えば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. `FAQ agent` が呼び出されたときに、履歴からすべてのツールを自動的に削除します。 +1. これは、`FAQ agent` が呼び出されたときに履歴から自動的にすべてのツールを削除します。 ## 推奨プロンプト -LLMs が handoffs を正しく理解できるように、エージェントに handoffs に関する情報を含めることをおすすめします。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスが用意されています。あるいは、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトへ自動追加できます。 +LLM が handoffs を正しく理解できるようにするため、エージェント に handoffs に関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index cb0e02a9a..d42e28452 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 の主な機能は次のとおりです: +SDK の主な機能は次のとおりです。 -- エージェント ループ: ツールの呼び出し、結果を LLM に送る処理、そして LLM が完了するまでのループを扱う組み込みのエージェント ループ。 -- Python ファースト: 新しい抽象を学ぶ必要はなく、組み込みの言語機能で エージェント をオーケストレーションし、連鎖させられます。 -- ハンドオフ: 複数の エージェント 間の調整と委譲を可能にする強力な機能。 -- ガードレール: エージェント と並行して入力のバリデーションやチェックを実行し、失敗時は早期に中断。 -- セッション: エージェント の実行をまたいだ会話履歴を自動管理し、手動の状態管理を不要にします。 -- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と Pydantic によるバリデーションを提供。 -- トレーシング: ワークフローの可視化・デバッグ・モニタリングを可能にする組み込みのトレーシングに加え、評価、ファインチューニング、蒸留ツールを含む OpenAI のスイートを利用可能。 +- エージェントループ: ツールの呼び出し、結果の LLM への送信、LLM の完了までのループを内蔵で処理。 +- Python ファースト: 新しい抽象化を学ぶのではなく、言語の標準機能でエージェントのオーケストレーションや連携を実現。 +- ハンドオフ: 複数エージェント間の調整と委譲を可能にする強力な機能。 +- ガードレール: エージェントと並行して入力検証やチェックを実行し、失敗時は早期に中断。 +- セッション: エージェントの実行間での会話履歴を自動管理し、手動での状態管理を不要に。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 +- トレーシング: ワークフローの可視化・デバッグ・監視を可能にし、OpenAI の評価、ファインチューニング、蒸留ツール群も活用可能。 ## インストール @@ -36,7 +36,7 @@ Python と組み合わせることで、これらの基本コンポーネント pip install openai-agents ``` -## Hello world の例 +## Hello World の例 ```python from agents import Agent, Runner @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定していることを確認してください_) +(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index acbf194b3..ac7715b54 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)（別名 MCP）は、 LLM にツールとコンテキストを提供する方法です。MCP のドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction)（aka MCP）は、LLM にツールとコンテキストを提供する方法です。MCP のドキュメントより引用します: -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーションにとっての USB-C ポートのようなものだと考えてください。USB-C がさまざまな周辺機器やアクセサリーにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーション向けの USB-C ポートのようなものだと考えてください。USB-C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを利用して、エージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用して、エージェントにツールやプロンプトを提供できます。 -## MCP servers +## MCP サーバー -現在、MCP の仕様では、使用するトランスポート メカニズムに基づいて 3 種類のサーバーが定義されています: +現在、MCP の仕様は、使用するトランスポート方式に基づいて 3 種類のサーバーを定義しています: 1. **stdio** サーバーは、アプリケーションのサブプロセスとして実行されます。いわば「ローカル」で動作します。 -2. **HTTP over SSE** サーバーはリモートで実行されます。 URL 経由で接続します。 +2. **HTTP over SSE** サーバーはリモートで実行されます。URL で接続します。 3. **Streamable HTTP** サーバーは、MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の各クラスを使って接続できます。 +これらのサーバーに接続するには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用できます。 -たとえば、[公式の MCP ファイルシステム サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)は次のように使います。 +例として、[official MCP filesystem server](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 @@ -137,15 +137,15 @@ server = MCPServerStdio( `ToolFilterContext` では次の情報にアクセスできます: - `run_context`: 現在の実行コンテキスト - `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバーの名前 +- `server_name`: MCP サーバー名 ## プロンプト -MCP サーバーは、エージェントの指示を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な指示テンプレートを作成できます。 +MCP サーバーは、エージェントの instructions を動的に生成するために使用できるプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な 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) を参照してください。 +[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で、完全に動作する code examples を参照してください。 ## トレーシング -[トレーシング](./tracing.md) は、以下を含む MCP の操作を自動的に記録します: +[Tracing](./tracing.md) は、以下を含む MCP の操作を自動的に取得します: -1. ツールを一覧表示するための MCP サーバーへの呼び出し +1. ツール一覧取得のための MCP サーバーへの呼び出し 2. 関数呼び出しに関する MCP 関連情報 -![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) \ No newline at end of file +![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 1b94eae36..da5e00ab2 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,51 +4,51 @@ search: --- # モデル -Agents SDK には、OpenAI モデル向けの標準サポートが 2 つ用意されています: +Agents SDK には、2 種類の OpenAI モデルへのすぐに使えるサポートが含まれます: -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 +- ** 推奨 **: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 ## 非 OpenAI モデル -ほとんどの非 OpenAI モデルは [LiteLLM 連携](./litellm.md) を通じて利用できます。まず、litellm の依存関係グループをインストールします: +[LiteLLM 連携](./litellm.md) を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、 litellm の依存関係グループをインストールします: ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて [サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します: +次に、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) のいずれかを使用します: ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使うその他の方法 +### 非 OpenAI モデルを使う他の方法 -ほかの LLM プロバイダーを統合する方法は、さらに 3 つあります（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーは、さらに 3 つの方法で統合できます（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` を設定できるケース向けです。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより「この実行のすべてのエージェントでカスタムのモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] では、特定のエージェントインスタンスに対してモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使えます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) を利用するのが簡単です。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、グローバルに `AsyncOpenAI` のインスタンスを LLM クライアントとして使いたい場合に便利です。これは、 LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に使用します。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルにあります。これにより、「この実行のすべての エージェント にカスタムのモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] は、特定の Agent インスタンス上でモデルを指定できます。これにより、異なる エージェント に対して異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。最も手軽に多くのモデルを使う方法は [LiteLLM 連携](./litellm.md) です。 -`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` で トレーシング を無効化するか、[別の トレーシング プロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions の API/モデルを使用しています。もしお使いの LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの例では Chat Completions API/モデルを使用しています。多くの LLM プロバイダーはまだ Responses API をサポートしていないためです。プロバイダーが対応している場合は、 Responses の使用をおすすめします。 ## モデルの組み合わせ -単一のワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえばトリアージには小さく高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使うといった形です。[`Agent`][agents.Agent] を設定する際は、次のいずれかの方法で特定のモデルを選択できます。 +単一のワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。例えば、振り分けには小さく高速なモデルを、複雑なタスクにはより大きく高性能なモデルを使う、といった使い分けです。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選べます: 1. モデル名を渡す。 -2. 任意のモデル名 + その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +2. 任意のモデル名と、それを Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、ワークフローごとに 1 つのモデル形状に統一することを推奨します。両者はサポートする機能やツールのセットが異なるためです。ワークフロー上でモデル形状を混在させる場合は、使用するすべての機能が双方で利用可能であることを確認してください。 + この SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、ワークフローごとに単一のモデル形状を使うことを推奨します。両者は対応する機能やツールのセットが異なるためです。ワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -81,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデルの名前を直接指定します。 -2. [`Model`][agents.models.interface.Model] 実装を提供します。 +1. OpenAI モデルの名前を直接設定します。 +2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに詳細に設定したい場合は、`temperature` などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェント で使用するモデルをさらに設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。これは、 temperature などの任意のモデル設定 パラメーター を提供します。 ```python from agents import Agent, ModelSettings @@ -97,7 +97,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、`user` や `service_tier` などの任意パラメーターを追加で指定できます。これらがトップレベルで指定できない場合は、`extra_args` を使って渡せます。 +また、 OpenAI の Responses API を使用する場合、[他にもいくつかの任意 パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡せます。 ```python from agents import Agent, ModelSettings @@ -113,26 +113,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダーを使用する際の一般的な問題 +## 他の LLM プロバイダー利用時の一般的な問題 -### トレーシング クライアント エラー 401 +### トレーシング クライアントの 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.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK は既定で Responses API を使用しますが、多くの他社 LLM プロバイダーはまだサポートしていません。その結果、404 エラーなどが発生することがあります。解決するには次のいずれかの方法を取ってください。 +SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだ対応していません。その結果、 404s などの問題が発生することがあります。解決するには次の 2 つの方法があります: -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは `OPENAI_API_KEY` と `OPENAI_BASE_URL` を環境変数で設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。コード例は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。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) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーが発生することがあります: ``` @@ -140,12 +140,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダー側の制約で、JSON 出力自体はサポートしていても、出力に使用する `json_schema` を指定できないためです。現在修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することを推奨します。そうでない場合、JSON の形式が不正でアプリが頻繁に壊れる可能性があります。 +これは一部のモデルプロバイダーの弱点で、 JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないというものです。現在この点の改善に取り組んでいますが、 JSON schema 出力をサポートするプロバイダーに依存することをおすすめします。さもないと、 JSON の形式不備により、アプリが頻繁に動作しなくなる可能性があります。 -## プロバイダー間でのモデルの混在 +## プロバイダー間でのモデルの組み合わせ -モデルプロバイダー間で機能差がある点に注意しないと、エラーに遭遇することがあります。たとえば OpenAI は Structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、多くの他プロバイダーはこれらの機能をサポートしていません。次の制約に注意してください。 +モデルプロバイダー間の機能差に注意しないと、エラーに直面する可能性があります。例えば、 OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、他の多くのプロバイダーはこれらをサポートしていません。次の制約に注意してください: -- サポートしていない `tools` を理解しないプロバイダーには送らない -- テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外する -- 構造化された 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 6f0d0db53..5332d7a52 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM 経由の任意モデルの利用 +# LiteLLM による任意のモデルの利用 !!! note - LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生することがあります。問題があれば [Github の issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 + LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK内で任意の AI モデルを利用できるように、 LiteLLM 統合を追加しました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ モデルを利用できるライブラリです。Agents SDK で任意の AI モデルを使えるように、LiteLLM 連携を追加しました。 ## セットアップ -`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで対応できます: +`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください: ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば、次のように入力できます: +これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます: -- `openai/gpt-4.1` をモデルに、OpenAIの API キーを入力 -- `anthropic/claude-3-5-sonnet-20240620` をモデルに、 Anthropic の API キーを入力 +- モデルに `openai/gpt-4.1`、API キーに OpenAI の API キー +- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic の API キー - など -LiteLLM でサポートされているモデルの一覧は、[LiteLLM のプロバイダー ドキュメント](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 942588ef4..cdb036972 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -2,40 +2,40 @@ search: exclude: true --- -# 複数の エージェント のオーケストレーション +# 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内で エージェント がどのように流れるか（どの エージェント が、どの順序で実行され、次に何を行うかをどう判断するか）を指します。エージェント をオーケストレーションする主な方法は 2 つあります: +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で実行され、次に何をするかをどう判断するか、ということです。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定させる: これは LLM の知能を用いて計画・推論し、それに基づいて次に取るステップを決定します。 -2. コードによるオーケストレーション: コードで エージェント の流れを決定します。 +1. LLM に意思決定させる方法: これは、LLM の知性を使って計画・推論し、それに基づいて取るべきステップを決定します。 +2. コードでオーケストレーションする方法: コードでエージェントのフローを決めます。 -これらのパターンは組み合わせて使えます。どちらにもトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェント は、 instructions、 tools、ハンドオフ を備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的にタスクへの取り組み方を計画し、tools を使ってアクション実行やデータ取得を行い、ハンドオフ を使ってサブ エージェント にタスクを委任できることを意味します。例えば、リサーチ エージェント には次のようなツールを備えられます: +エージェントとは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的に計画を立て、ツールでアクションを実行してデータを取得し、ハンドオフでサブエージェントにタスクを委譲できることを意味します。たとえば、リサーチ用エージェントは次のようなツールを備えられます。 -- オンラインの情報を見つけるための Web 検索 -- 社内データや各種接続先を横断的に検索するための ファイル検索 と取得 -- コンピュータ上でアクションを実行するための コンピュータ操作 -- データ分析のためのコード実行 -- 計画立案、レポート作成などに長けた特化型 エージェント へのハンドオフ +- オンライン情報を見つけるための Web 検索 +- 企業データや接続を検索するためのファイル検索と取得 +- コンピュータでアクションを実行するためのコンピュータ操作 +- データ分析を行うためのコードの実行 +- 計画やレポート作成などが得意な専門エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、 LLM の知能に依拠したい場合に有効です。重要なポイントは次のとおりです: +このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に最適です。ここで重要な戦術は次のとおりです。 -1. 良いプロンプトに投資しましょう。利用可能な tools、使い方、どのパラメーター範囲で動作すべきかを明確にします。 -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) を使って、コードで検査できる適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選ぶ、といった方法です。 +- 複数のエージェントをチェーンし、前段の出力を次段の入力に変換する。ブログ記事の執筆のようなタスクを、リサーチ→アウトライン作成→本文執筆→批評→改善という一連のステップに分解できます。 +- タスクを実行するエージェントと、評価・フィードバックを行うエージェントを `while` ループで回し、評価者が一定の基準を満たしたと判断するまで続ける。 +- 複数のエージェントを並行実行する（例: Python の基本コンポーネントである `asyncio.gather` を利用）。互いに依存しない複数のタスクがある場合、速度向上に有用です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の コード例 があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index e58ee2059..9cb0f80a2 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは 1 回だけ実行すれば十分です。 +これは一度だけ実施すれば十分です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行してください。 +新しいターミナルセッションを開始するたびに実行します。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだお持ちでない場合は、[これらの手順](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-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions、名前、および省略可能な設定（`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 ビューアー](https://platform.openai.com/traces) に移動して、エージェントの実行のトレースを表示してください。 +エージェントの実行中に何が起きたかを確認するには、 OpenAI ダッシュボードの Trace ビューアに移動し、エージェント実行のトレースを表示します。 ## 次のステップ より複雑なエージェント フローの構築方法を学びましょう: -- [エージェント](agents.md) の設定について学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [ツール](tools.md)、[ガードレール](guardrails.md) および [モデル](models/index.md) について学びます。 \ No newline at end of file +- [エージェント](agents.md) の設定について学びましょう。 +- [エージェントの実行](running_agents.md) について学びましょう。 +- [ツール](tools.md)、[ガードレール](guardrails.md)、および [モデル](models/index.md) について学びましょう。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index eedcd6d90..dd1a89cde 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、 OpenAI Agents SDK のリアルタイム機能を用いて音声対応の AI エージェントを構築する方法を詳しく解説します。 +このガイドでは、OpenAI Agents SDK の realtime 機能を用いた音声対応 AI エージェントの構築について詳しく説明します。 !!! warning "ベータ機能" -リアルタイム エージェントはベータ版です。実装の改善に伴い、後方互換性のない変更が発生する場合があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的な変更が発生する可能性があります。 ## 概要 -リアルタイム エージェントは、音声とテキストの入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを実現します。 OpenAI の Realtime API への永続的な接続を維持し、低遅延で自然な音声対話と、割り込みへの柔軟な対応を可能にします。 +Realtime エージェントは、会話フローを実現し、音声とテキストの入力をリアルタイムに処理して realtime 音声で応答します。OpenAI の Realtime API との永続接続を維持し、低遅延で自然な音声会話と、割り込みへのスムーズな対応を可能にします。 ## アーキテクチャ -### コアコンポーネント +### 中核コンポーネント -このリアルタイム システムは、いくつかの主要コンポーネントで構成されます。 +realtime システムは、いくつかの主要コンポーネントで構成されます: -- **RealtimeAgent**: instructions、tools、ハンドオフで構成されるエージェントです。 -- **RealtimeRunner**: 構成を管理します。`runner.run()` を呼び出してセッションを取得できます。 +- **RealtimeAgent**: instructions、tools、handoffs で構成されたエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 - **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに作成し、会話が完了するまで維持します。 -- **RealtimeModel**: 基盤となるモデル インターフェース（一般的には OpenAI の WebSocket 実装） +- **RealtimeModel**: 基盤となるモデルのインターフェースです (通常は OpenAI の WebSocket 実装)。 -### セッション フロー +### セッションフロー -一般的なリアルタイム セッションの流れは次のとおりです。 +一般的な 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 モデルとの永続接続を管理します。 -## エージェント構成 +## エージェントの設定 -RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつかの重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつか重要な違いがあります。API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 -通常のエージェントとの主な相違点: +通常のエージェントとの主な違い: -- モデルの選択はエージェント レベルではなくセッション レベルで設定します。 -- structured outputs のサポートはありません（`outputType` は未対応）。 -- 音声（ボイス）はエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 -- それ以外の機能（tools、ハンドオフ、instructions など）は同様に動作します。 +- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 +- structured outputs のサポートはありません ( `outputType` は未対応です )。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、handoffs、instructions などのその他の機能は同様に動作します。 -## セッション構成 +## セッションの設定 ### モデル設定 -セッション構成では、基盤となるリアルタイム モデルの挙動を制御できます。モデル名（例：`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 などのモデルを用いた入力音声の書き起こし、言語設定、専門用語の精度を高めるための書き起こしプロンプトを指定できます。ターン検出の設定では、音声活動検出 (VAD) のしきい値、無音時間、検出された発話の前後パディングなどにより、エージェントがいつ応答を開始・終了すべきかを制御します。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、リアルタイム エージェントは会話中に実行される関数ツールをサポートします: +通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします: ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、専門化したエージェント間で会話を引き継げます。 +ハンドオフにより、専門特化したエージェント間で会話を転送できます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーミングし、セッション オブジェクトを反復処理して待ち受けできます。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーなどが含まれます。特に扱うべき主要なイベントは次のとおりです。 +セッションはイベントをストリーミングし、セッションオブジェクトを反復処理することで監視できます。イベントには音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーなどが含まれます。主要なイベントは次のとおりです: -- **audio**: エージェントの応答からの生の音声データ -- **audio_end**: エージェントの発話終了 -- **audio_interrupted**: ユーザーがエージェントに割り込み -- **tool_start/tool_end**: ツール実行ライフサイクル +- **audio**: エージェントの応答からの raw オーディオデータ +- **audio_end**: エージェントの発話が完了 +- **audio_interrupted**: ユーザーがエージェントを割り込み +- **tool_start/tool_end**: ツール実行のライフサイクル - **handoff**: エージェントのハンドオフが発生 - **error**: 処理中にエラーが発生 -完全なイベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +イベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -リアルタイム エージェントでサポートされるのは出力用のガードレールのみです。ガードレールはデバウンスされ、リアルタイム生成時のパフォーマンス問題を避けるために定期的（単語ごとではなく）に実行されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 +Realtime エージェントでサポートされるのは出力ガードレールのみです。パフォーマンス問題を避けるため、これらのガードレールはデバウンスされ、リアルタイム生成中に毎単語ではなく一定間隔で実行されます。既定のデバウンス長は 100 文字ですが、設定可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` で指定できます。両方の経路から与えたガードレールは併用されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` 経由で提供できます。両方の経路からのガードレールは併用されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレールが発火すると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンスの挙動により、安全性とリアルタイム性能要件のバランスを取ります。テキスト エージェントと異なり、リアルタイム エージェントはガードレール作動時に例外（Exception）を発生させることは **ありません**。 +ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断する場合があります。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキストエージェントと異なり、realtime エージェントはガードレール作動時に Exception をスローしません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] でセッションに音声を送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] でテキストを送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使って音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使ってテキストを送信します。 -音声出力については、`audio` イベントを待ち受けて任意の音声ライブラリで再生します。ユーザーがエージェントに割り込んだ際には、すぐに再生を停止しキュー済みの音声をクリアできるよう、`audio_interrupted` イベントも必ず監視してください。 +音声出力については、`audio` イベントを監視し、任意の音声ライブラリで再生してください。ユーザーがエージェントを割り込んだ際にはすぐに再生を停止し、キューにある音声をクリアするために `audio_interrupted` イベントを必ず監視してください。 ## モデルへの直接アクセス -基盤となるモデルにアクセスして、カスタム リスナーの追加や高度な操作を実行できます。 +基盤となるモデルにアクセスして、カスタムリスナーの追加や高度な操作を実行できます: ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、接続をより低レベルに制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、接続を低レベルで制御する必要がある高度なユースケースに向けて、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## コード例 +## 例 -完全な動作するコード例は、[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 37b4ca4cc..0c087d4fc 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,35 +4,35 @@ search: --- # クイックスタート -Realtime エージェントは、 OpenAI の Realtime API を使用して、 AI エージェントと音声で会話できるようにします。このガイドでは、最初の Realtime 音声エージェントを作成する手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声対話を可能にします。このガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントは現在ベータ版です。実装の改善に伴い、互換性のない変更が入る可能性があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、非互換の変更が発生する可能性があります。 ## 前提条件 - Python 3.9 以上 - OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- OpenAI Agents SDK の基本的な理解 ## インストール -まだインストールしていない場合は、 OpenAI Agents SDK をインストールしてください: +未インストールの場合は、OpenAI Agents SDK をインストールします: ```bash pip install openai-agents ``` -## 最初の Realtime エージェントの作成 +## 初めての Realtime エージェントの作成 -### 1. 必要なコンポーネントをインポート +### 1. 必要なコンポーネントのインポート ```python import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. Realtime エージェントを作成する +### 2. Realtime エージェントの作成 ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. Runner のセットアップ +### 3. runner のセットアップ ```python runner = RealtimeRunner( @@ -56,7 +56,7 @@ runner = RealtimeRunner( ) ``` -### 4. セッションを開始する +### 4. セッションの開始 ```python async def main(): @@ -81,7 +81,7 @@ asyncio.run(main()) ## 完全なコード例 -動作する完全なコード例は次のとおりです: +完全に動作するコード例はこちらです: ```python import asyncio @@ -135,44 +135,44 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 設定オプション +## 構成オプション ### モデル設定 -- `model_name`: 利用可能な Realtime モデルから選択します（例: `gpt-4o-realtime-preview`） -- `voice`: 音声を選択します（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） -- `modalities`: テキストおよび/または音声を有効化します（`["text", "audio"]`） +- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-4o-realtime-preview`) +- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストおよび/または音声を有効化します (`["text", "audio"]`) ### 音声設定 -- `input_audio_format`: 入力音声のフォーマット（`pcm16`、`g711_ulaw`、`g711_alaw`） -- `output_audio_format`: 出力音声のフォーマット +- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力音声の形式 - `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法（`server_vad`、`semantic_vad`） -- `threshold`: 音声活動のしきい値（0.0-1.0） -- `silence_duration_ms`: ターン終了を検出するための無音継続時間 +- `type`: 検出方式 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動のしきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了を検出する無音継続時間 - `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [Realtime エージェントについて詳しく学ぶ](guide.md) -- 動作するサンプルコードは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーをご覧ください +- [Realtime エージェントの詳細](guide.md) +- 動作する 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" ``` -また、セッション作成時に直接渡すこともできます: +または、セッション作成時に直接渡します: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index cc0f0c20f..ce52bc6a5 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリースプロセス/変更履歴 +# リリースプロセス / 変更履歴 -このプロジェクトは、形式 `0.Y.Z` を用いる、やや変更したセマンティック バージョニングに従います。先頭の `0` は、 SDK が依然として急速に進化していることを示します。各コンポーネントの増やし方は次のとおりです: +このプロジェクトは、形式 `0.Y.Z` を用いた、やや修正したセマンティックバージョニングに従います。先頭の `0` は、この SDK が依然として急速に進化していることを示します。各コンポーネントの増やし方は次のとおりです。 ## マイナー（`Y`）バージョン -ベータとしてマークされていない公開インターフェースに対する **破壊的変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータではないパブリック インターフェースに対する ** 破壊的変更 ** がある場合に、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には、破壊的変更が含まれる可能性があります。 -破壊的変更を望まない場合は、プロジェクトで `0.0.x` のバージョンに固定することをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` に固定することをおすすめします。 ## パッチ（`Z`）バージョン -後方互換性を壊さない変更には、`Z` を増やします: +破壊的でない変更では `Z` を増やします。 - バグ修正 - 新機能 -- 非公開インターフェースへの変更 +- 非公開インターフェースの変更 - ベータ機能の更新 ## 破壊的変更の変更履歴 ### 0.2.0 -このバージョンでは、これまで `Agent` を引数に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。たとえば、 MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型に関する変更で、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。 +このバージョンでは、以前は引数として `Agent` を受け取っていた箇所の一部が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、 MCP サーバーでの `list_tools()` 呼び出しです。これは純粋に型付け上の変更であり、引き続き `Agent` オブジェクトが渡されます。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に 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 bd066894e..41749b82f 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -SDK は、お使いのターミナルでエージェントの動作を手早くインタラクティブにテストできる `run_demo_loop` を提供します。 +この SDK は、`run_demo_loop` を提供しており、ターミナル上でエージェントの挙動を素早く対話的にテストできます。 ```python import asyncio @@ -18,6 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間の会話履歴を保持します。デフォルトでは、生成され次第、モデルの出力をストリーミングします。上の例を実行すると、 run_demo_loop がインタラクティブなチャットセッションを開始します。継続的に入力を求め、ターン間で会話の全履歴を保持します（そのため、エージェントは何が話されたかを把握できます）。そして、生成されるそばからエージェントの応答をリアルタイムで自動的にストリーミングします。 +`run_demo_loop` はループでユーザー入力を促し、各ターン間で会話履歴を保持します。デフォルトでは、生成と同時にモデル出力をストリーミングします。上記の例を実行すると、 run_demo_loop は対話型のチャットセッションを開始します。入力を継続的に求め、各ターン間で会話全体の履歴を記憶し（そのためエージェントは何が話されたかを把握します）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 -このチャットセッションを終了するには、 `quit` または `exit` と入力して（ Enter キーを押す）か、 `Ctrl-D` のキーボードショートカットを使用してください。 \ No newline at end of file +このチャットセッションを終了するには、`quit` または `exit` と入力する（そして Enter を押します）か、`Ctrl-D` のキーボードショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index ea1e7eb53..da696fd84 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 実行結果 -`Runner.run` 系メソッドを呼び出すと、結果は次のいずれかです。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] +- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] -これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報の多くはそこに含まれます。 +いずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。内容は次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- そのエージェントに出力タイプが定義されている場合は、型 `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 によって生成された生のアイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新規アイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw なアイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は、 LLM からのメッセージを示します。生のアイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、 LLM がハンドオフツールを呼び出したことを示します。生のアイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。生のアイテムは、そのハンドオフツール呼び出しに対するツールのレスポンスです。アイテムからソース/ターゲットのエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、 LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。生のアイテムはツールのレスポンスです。アイテムからツールの出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は、 LLM からの推論アイテムを示します。生のアイテムは生成された推論です。 +- [`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_responses`][agents.result.RunResultBase.raw_responses] プロパティには、 LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに渡した元の入力が含まれます。多くの場合これは不要ですが、必要なときのために参照できます。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] プロパティには、`run` メソッドに提供した元の入力が含まれます。多くの場合は不要ですが、必要に応じて参照できます。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index 9660fc340..e32f37381 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 を呼び出し、受信したイベントをそのままストリーミングします。 +1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリーミングします。 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳しくは [結果ガイド](results.md) を参照してください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の run メソッドを使うと、開始するエージェントと入力を渡します。入力は文字列（ユーザーメッセージとして扱われます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 +`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ユーザーのメッセージと見なされます）か、OpenAI Responses API のアイテムのリストのいずれかです。 -Runner は次のようにループを実行します: +runner は次のループを実行します。 -1. 現在の入力を用いて、現在のエージェントに対して LLM を呼び出します。 -2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し、実行結果を返します。 - 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらを実行し、その実行結果を追加して、ループを再実行します。 +1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 +2. LLM が出力を生成します。 + 1. LLM が `final_output` を返した場合、ループを終了し、結果を返します。 + 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新して、ループを再実行します。 + 3. LLM が ツール呼び出し を生成した場合、それらを実行し、結果を追加して、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - ある LLM 出力が「最終出力」と見なされる条件は、所望の型のテキスト出力を生成し、かつツール呼び出しが存在しないことです。 + LLM の出力が「final output」と見なされるルールは、目的の型のテキスト出力を生成し、かつツール呼び出しがない場合です。 ## ストリーミング -ストリーミングを使うと、 LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了時には、[`RunResultStreaming`][agents.result.RunResultStreaming] に、生成されたすべての新規出力を含む実行の完全な情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すと取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングでは、LLM の実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行の完全な情報が入ります。ストリーミングイベントは `.stream_events()` を呼び出すことで受け取れます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 ## 実行設定 -`run_config` パラメーターでは、エージェントの実行に関するグローバル設定を構成できます: +`run_config` パラメーターで、エージェント実行のグローバル設定を構成できます。 -- [`model`][agents.run.RunConfig.model]: 各エージェントの `model` に関わらず、使用するグローバルな LLM モデルを設定できます。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、グローバルな LLM モデルを設定できます。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーで、デフォルトは OpenAI です。 - [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力または出力のガードレールのリスト。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既定の入力フィルターがない場合に、すべてのハンドオフへ適用するグローバルな入力フィルターです。入力フィルターにより、新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体に対して [トレーシング](tracing.md) を無効化できます。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、 LLM やツール呼び出しの入出力など、潜在的に機密なデータを含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は、複数の実行にまたがってトレースを関連付けるための任意のフィールドです。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力の ガードレール のリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフ に入力フィルターがない場合に適用するグローバル入力フィルターです。入力フィルターにより、新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化できます。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングのワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話 / チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行されることがあります（つまり、1 回以上の LLM 呼び出しが発生します）。ただし、これはチャット会話における 1 回の論理的なターンを表します。たとえば: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される可能性がありますが、チャット会話の単一の論理ターンを表します。例: -1. ユーザーのターン: ユーザーがテキストを入力します。 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行し、最終的に出力を生成します。 +1. ユーザーターン: ユーザーがテキストを入力 +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) を参照してください。 -## 長時間実行のエージェントと人間の介在 (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: モデルが、ツール呼び出し用、または直接出力に対して不正な 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 +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。他の特定の例外はすべてここから派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えたときに送出されます。指定された対話ターン数内にエージェントがタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。たとえば次が含まれます。 + - 不正な JSON: 特定の `output_type` が定義されている場合などに、ツール呼び出しや直接の出力で JSON 構造が不正な場合。 + - 予期しないツール関連の失敗: モデルが想定どおりにツールを使用できなかった場合 +- [`UserError`][agents.exceptions.UserError]: SDK を使用する（この SDK でコードを書く）あなたが誤りを犯した場合に送出されます。誤ったコード実装、無効な設定、SDK の API の誤用が典型的な原因です。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 入力ガードレール または 出力ガードレール の条件が満たされた場合に、それぞれ送出されます。入力ガードレールは処理前に受信メッセージを検査し、出力ガードレールは配信前にエージェントの最終応答を検査します。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index ba4b8be79..b04b2da4e 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にまたがる会話履歴を自動で保持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要がなくなります。 +Agents SDK は、複数のエージェント実行にわたって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 -セッションメモリは特定のセッションの会話履歴を保存し、明示的な手動のメモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャット アプリケーションやマルチターンの会話を構築するときに特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を行わなくてもエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に役立ちます。 ## クイックスタート @@ -49,13 +49,13 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリを有効にすると: +セッションメモリが有効な場合: -1. **各実行の前**: Runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に付加します。 -2. **各実行の後**: 実行中に生成されたすべての新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出し など) は自動的にセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションでの以降の各実行には完全な会話履歴が含まれ、エージェントがコンテキストを維持できます。 +1. **各実行の前**: runner はセッションの会話履歴を自動的に取得し、入力アイテムの前に付加します。 +2. **各実行の後**: 実行中に生成されたすべての新規アイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）は、自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の実行には、完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 +これにより、実行間で `.to_input_list()` を手動で呼び出したり会話状態を管理したりする必要がなくなります。 ## メモリ操作 @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 修正のための `pop_item` の使用 +### `pop_item` の活用による修正 -会話の最後のアイテムを取り消したり変更したりしたい場合、`pop_item` メソッドが特に便利です: +`pop_item` メソッドは、会話内の最後のアイテムを取り消したり修正したりしたい場合に特に有用です: ```python from agents import Agent, Runner, SQLiteSession @@ -117,9 +117,9 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリ オプション +## メモリオプション -### メモリなし (デフォルト) +### メモリなし（デフォルト） ```python # Default behavior - no session memory @@ -145,7 +145,7 @@ result = await Runner.run( ) ``` -### 複数のセッション +### 複数セッション ```python from agents import Agent, Runner, SQLiteSession @@ -170,7 +170,7 @@ result2 = await Runner.run( ## カスタムメモリ実装 -[`Session`][agents.memory.session.Session] プロトコルに準拠するクラスを作成することで、独自のセッションメモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: ```python from agents.memory import Session @@ -218,15 +218,15 @@ result = await Runner.run( 会話の整理に役立つ意味のあるセッション ID を使用します: -- ユーザー ベース: `"user_12345"` -- スレッド ベース: `"thread_abc123"` -- コンテキスト ベース: `"support_ticket_456"` +- ユーザーベース: `"user_12345"` +- スレッドベース: `"thread_abc123"` +- コンテキストベース: `"support_ticket_456"` ### メモリの永続化 -- 一時的な会話にはインメモリの SQLite (`SQLiteSession("session_id")`) を使用します -- 永続的な会話にはファイル ベースの SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用します -- 本番システム向けにはカスタムのセッション バックエンドの実装を検討してください ( Redis、PostgreSQL など ) +- 一時的な会話にはメモリ内 SQLite（`SQLiteSession("session_id")`）を使用します +- 永続的な会話にはファイルベース SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します +- 本番システム向けにはカスタムセッションバックエンド（ Redis、PostgreSQL など）の実装を検討します ### セッション管理 @@ -252,9 +252,9 @@ result2 = await Runner.run( ) ``` -## 完全なコード例 +## 完全な例 -セッションメモリの動作を示す完全なコード例です: +セッションメモリの動作を示す完全な例です: ```python import asyncio @@ -318,7 +318,7 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは次を参照してください: +詳細な API ドキュメントは以下をご覧ください: -- [`Session`][agents.memory.Session] - プロトコル インターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 \ No newline at end of file +- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index b65821106..cc7da4a10 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、エージェントの実行の進行に合わせて更新を購読できます。これは、エンドユーザーに進捗の更新や部分的な応答を表示するのに役立ちます。 +ストリーミングは、エージェントの実行が進むにつれて更新に購読できるようにします。これは、エンドユーザーに進捗や部分的な応答を表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出すと、[`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 ## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、 LLM から直接渡される raw イベントです。これは OpenAI Responses API 形式であり、各イベントには種類 (たとえば `response.created`、`response.output_text.delta` など) とデータがあります。これらのイベントは、応答メッセージが生成され次第ユーザーにストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。形式は OpenAI Responses API で、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。これらのイベントは、生成され次第、応答メッセージをユーザーにストリーミングしたい場合に有用です。 -たとえば、これは LLM が生成したテキストをトークンごとに出力します。 +例えば、次の例は LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## 実行アイテムイベントとエージェントイベント -[`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 cda0bbed1..ce58eedb4 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールはエージェントがアクションを実行できるようにします。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などです。 Agents SDK にはツールのクラスが 3 つあります: +ツールは エージェント に行動を取らせます。データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 種類のツールがあります。 -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。 OpenAI は、リトリーバル、 Web 検索、コンピュータ操作をホスト型ツールとして提供しています。 -- Function calling: 任意の Python 関数をツールとして使えるようにします。 -- エージェントをツールとして: エージェントをツールとして使えるため、ハンドオフせずにエージェントが他のエージェントを呼び出せます。 +- Hosted tools: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を Hosted tools として提供します。 +- Function calling: 任意の Python 関数をツールとして利用できます。 +- Agents as tools: エージェント をツールとして利用でき、ハンドオフ せずに エージェント から他の エージェント を呼び出せます。 ## ホスト型ツール -[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合、 OpenAI はいくつかの組み込みツールを提供しています: +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 関数名になります（または任意の名前を指定できます）。 -- ツールの説明は関数のドックストリングから取得されます（または説明を指定できます）。 -- 関数の入力のスキーマは、関数の引数から自動的に作成されます。 -- 各入力の説明は、無効化しない限り関数のドックストリングから取得されます。 +- ツール名は Python 関数名になります（任意で名前を指定可能） +- ツールの説明は関数の docstring から取得します（任意で説明を指定可能） +- 関数の入力スキーマは関数の引数から自動生成されます +- 各入力の説明は、無効化しない限り関数の docstring から取得されます -関数シグネチャの抽出には Python の `inspect` モジュールを使用し、ドックストリングの解析には [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマの作成には `pydantic` を使用します。 +Python の `inspect` モジュールを使って関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析、`pydantic` でスキーマを作成します。 ```python import json @@ -102,14 +102,14 @@ for tool in agent.tools: ``` -1. 任意の Python 型を関数の引数に使え、関数は同期/非同期のいずれでも構いません。 -2. ドックストリングがあれば、説明や引数の説明として利用されます。 -3. 関数は任意で `context` を受け取れます（先頭の引数である必要があります）。また、ツール名や説明、使用するドックストリングのスタイルなどのオーバーライドも設定できます。 -4. デコレートした関数をツールのリストに渡せます。 +1. 関数の引数には任意の Python 型が使用でき、関数は同期/非同期どちらでも構いません。 +2. docstring があれば、説明や引数説明の取得に使用されます。 +3. 関数は任意で `context`（最初の引数である必要があります）を受け取れます。ツール名や説明、docstring スタイルなどの上書き設定も可能です。 +4. デコレートした関数は tools のリストに渡せます。 -??? note "展開して出力を表示" +??? note "出力を表示" - ``` + ``` fetch_weather Fetch the weather for a given location. { @@ -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 文字列で受け取り、ツールの出力を文字列で返す非同期関数） +- 引数用の JSON スキーマである `params_json_schema` +- [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツールの出力を文字列で返す非同期関数 `on_invoke_tool` ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 引数とドックストリングの自動解析 +### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを得るために関数シグネチャを自動解析し、ツールおよび各引数の説明を得るためにドックストリングも解析します。注意点は次のとおりです: +前述のとおり、関数シグネチャを自動解析してツール用のスキーマを抽出し、docstring を解析してツールおよび各引数の説明を抽出します。補足事項は以下のとおりです。 -1. `inspect` モジュールでシグネチャを解析します。引数の型は型アノテーションから解釈し、全体のスキーマを表す Pydantic モデルを動的に構築します。 Python の基本型、 Pydantic モデル、 TypedDict など、ほとんどの型をサポートします。 -2. ドックストリングの解析には `griffe` を使用します。対応するドックストリング形式は `google`、`sphinx`、`numpy` です。ドックストリング形式は自動検出を試みますがベストエフォートのため、`function_tool` を呼び出す際に明示的に指定できます。`use_docstring_info` を `False` に設定して、ドックストリング解析を無効化することも可能です。 +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 @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツール化したエージェントのカスタマイズ +### ツール化エージェントのカスタマイズ -`agent.as_tool` 関数は、エージェントを簡単にツール化できるようにする簡便なメソッドです。ただし、すべての設定をサポートしているわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツールの実装内で `Runner.run` を直接使用してください: +`agent.as_tool` 関数は、エージェント をツールへ簡単に変換するためのユーティリティです。ただし、すべての設定をサポートしているわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、中央のエージェントに返す前にツール化したエージェントの出力を加工したいことがあります。例えば次のような場合に有用です: +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を変更したいことがあります。次のような場合に有用です。 -- 特定の情報（例: JSON ペイロード）をサブエージェントのチャット履歴から抽出する。 -- エージェントの最終回答を変換または再整形する（例: Markdown をプレーンテキストや CSV に変換）。 -- 出力を検証する、またはエージェントの応答が欠落している/形式不正な場合にフォールバック値を提供する。 +- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 +- エージェント の最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 +- 応答が欠落している、または不正な形式のときに、出力を検証したりフォールバック値を提供する。 -これは、`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: +これは `as_tool` の `custom_output_extractor` 引数を指定することで行えます。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,11 +317,11 @@ json_tool = data_agent.as_tool( ## 関数ツールでのエラー処理 -`@function_tool` で関数ツールを作成する際は、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを返す関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へ返すエラー応答を生成する関数です。 -- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、 LLM にエラーが発生したことを伝えます。 -- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 -- 明示的に `None` を渡すと、ツール呼び出しのエラーは再送出され、呼び出し側で処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになり得ます。 +- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 +- 独自のエラー関数を渡した場合はそれが実行され、その応答が LLM に送られます。 +- 明示的に `None` を渡すと、ツール呼び出しのエラーは再スローされ、あなたの側で処理する必要があります。例えば、モデルが不正な JSON を生成した場合は `ModelBehaviorError`、あなたのコードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -344,4 +344,4 @@ def get_user_profile(user_id: str) -> str: ``` -手動で `FunctionTool` オブジェクトを作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 78ceac7a2..39d12083c 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDKにはトレーシング機能が組み込まれており、エージェントの実行中に発生するイベント（LLMの生成、ツール呼び出し、ハンドオフ、ガードレール、さらには発生したカスタムイベント）の包括的な記録を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使って、開発中および本番環境でワークフローのデバッグ、可視化、監視ができます。 +Agents SDK には組み込みのトレーシングが含まれており、 エージェント 実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、そしてカスタムイベントまで記録します。[Traces ダッシュボード](https://platform.openai.com/traces) を使うと、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングは既定で有効です。無効にする方法は 2 つあります: + トレーシングは既定で有効です。トレーシングを無効化する方法は次の 2 つです。 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAIの API を使用し、 Zero Data Retention（ZDR）ポリシーのもとで運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は、1 つの「ワークフロー」のエンドツーエンドの処理を表します。スパンで構成されます。トレースには次のプロパティがあります: +- **トレース (Traces)** は「ワークフロー」の単一のエンドツーエンドの処理を表します。スパンで構成されます。トレースには次のプロパティがあります: - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 同一の会話からの複数トレースを関連付けるための任意のグループ ID。たとえばチャットスレッドの ID など + - `group_id`: 同じ会話からの複数トレースを関連付けるためのオプションのグループ ID。たとえばチャットスレッド ID を使えます。 - `disabled`: True の場合、このトレースは記録されません。 - - `metadata`: トレースの任意のメタデータ -- **スパン** は、開始時刻と終了時刻を持つ処理を表します。スパンには次が含まれます: + - `metadata`: トレースのオプションのメタデータ。 +- **スパン (Spans)** は開始時刻と終了時刻を持つ処理を表します。スパンには次があります: - `started_at` と `ended_at` のタイムスタンプ - 所属するトレースを表す `trace_id` - - 親スパン（存在する場合）を指す `parent_id` - - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLMの生成に関する情報を含みます。 + - このスパンの親スパン (あれば) を指す `parent_id` + - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` には エージェント に関する情報が、`GenerationSpanData` には LLM 生成に関する情報が含まれます。 ## 既定のトレーシング -既定では、Agents SDKは次をトレースします: +既定では、SDK は次をトレースします: -- 全体の `Runner.{run, run_sync, run_streamed}()` が `trace()` でラップされます -- エージェントが実行されるたびに、`agent_span()` でラップされます -- LLMの生成は `generation_span()` でラップされます -- 関数ツールの呼び出しは、それぞれ `function_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] で名前やその他のプロパティを構成できます。 +既定では、トレース名は "エージェント ワークフロー" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 -加えて、[custom trace processors](#custom-tracing-processors) を設定して、トレースを他の送信先へ送信できます（置き換え先、またはセカンダリの送信先として）。 +さらに、[カスタム トレーシング プロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へ送ることができます (置き換えまたは第 2 の送信先として)。 ## より高レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースに含めたい場合があります。その場合は、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを単一のトレースの一部にしたい場合があります。その場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -68,42 +68,42 @@ async def main(): ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数でトレースを作成できます。トレースは開始と終了が必要で、方法は 2 つあります: +[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: -1. 推奨: トレースをコンテキストマネージャーとして使用します（例: `with trace(...) as my_trace`）。これにより、適切なタイミングで自動的に開始・終了されます。 -2. また、[`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 +1. 推奨: `with trace(...) as my_trace` のように、トレースをコンテキストマネージャーとして使います。これにより、適切なタイミングでトレースが自動的に開始・終了します。 +2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは、 Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を介して追跡されます。これは、並行処理でも自動的に機能することを意味します。手動でトレースを開始/終了する場合は、現在のトレースを更新するために、`start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。これにより、自動的に並行実行でも機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -各種の [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。通常、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も利用できます。 +さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数を利用できます。 -スパンは自動的に現在のトレースの一部となり、 Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される、最も近い現在のスパンの配下にネストされます。 +スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される、最も近い現在のスパンの下にネストされます。 -## 機密データ +## センシティブなデータ -一部のスパンでは、機密になり得るデータが取得される場合があります。 +特定のスパンは、機微なデータを含む可能性があります。 -`generation_span()` は LLMの生成の入力と出力を保存し、`function_span()` は関数呼び出しの入力と出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入出力を、`function_span()` は関数呼び出しの入出力を保存します。これらにはセンシティブなデータが含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそれらのデータの取得を無効化できます。 -同様に、音声関連のスパンには、既定で入力音声と出力音声の base64 でエンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して、この音声データの取得を無効化できます。 +同様に、音声スパンには、既定で入力および出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成することで、この音声データの取得を無効化できます。 -## カスタムトレーシングプロセッサー +## カスタム トレーシング プロセッサー トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時に、グローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。これはトレースの作成を担当します。 -- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。`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] は、既定のプロセッサーを独自のトレースプロセッサーに置き換えられます。これにより、該当の処理を行う TracingProcessor を含めない限り、トレースは OpenAIバックエンドに送信されません。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第受け取る、追加のトレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて、独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、既定のプロセッサーを独自のトレースプロセッサーに置き換えることができます。つまり、OpenAI バックエンドにトレースを送信する `TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません。 -## OpenAI以外のモデルでのトレーシング +## 非 OpenAI モデルでのトレーシング -トレーシングを無効化することなく、 OpenAI Traces ダッシュボードで無料のトレーシングを有効にするために、OpenAIの API キーを OpenAI以外のモデルで使用できます。 +OpenAI の API キーを、非 OpenAI モデルと一緒に使用して、トレーシングを無効化することなく、OpenAI Traces ダッシュボードで無料トレーシングを有効にできます。 ```python import os @@ -124,10 +124,10 @@ agent = Agent( ) ``` -## 注意事項 -- 無料のトレースは OpenAI Traces ダッシュボードで表示できます。 +## 注意 +- 無料トレースは OpenAI Traces ダッシュボードで閲覧できます。 -## 外部トレーシングプロセッサー一覧 +## 外部トレーシング プロセッサー一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 233239e80..1f6d257ef 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 サーバー ** は灰色のボックスで表されます。 +- ** ツール ** は緑色の楕円で表されます。 +- ** ハンドオフ ** はあるエージェントから別のエージェントへの有向エッジとして表されます。 ### 使用例 @@ -69,34 +69,34 @@ draw_graph(triage_agent) ![エージェント グラフ](../assets/images/graph.png) -これにより、トリアージ エージェント の構造と、サブエージェント やツール との接続を視覚的に表すグラフが生成されます。 +これは、 ** トリアージ エージェント ** とそのサブエージェントおよびツールへの接続を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されたグラフには次が含まれます: +生成されるグラフには以下が含まれます: -- **開始ノード** ( `__start__` ) はエントリーポイントを示します。 -- エージェント は黄色の塗りの **長方形** で表されます。 -- ツール は緑の塗りの **楕円** で表されます。 -- MCP サーバー は灰色の塗りの **長方形** で表されます。 +- エントリーポイントを示す ** スタート ノード **（`__start__`）。 +- 黄色で塗りつぶされた ** 長方形 ** で表されるエージェント。 +- 緑色で塗りつぶされた ** 楕円 ** で表されるツール。 +- 灰色で塗りつぶされた ** 長方形 ** で表される MCP サーバー。 - 相互作用を示す有向エッジ: - - **実線の矢印** はエージェント 間のハンドオフを表します。 - - **点線の矢印** はツール の呼び出しを表します。 - - **破線の矢印** は MCP サーバー の呼び出しを表します。 -- **終了ノード** ( `__end__` ) は実行の終了位置を示します。 + - エージェント間のハンドオフには ** 実線の矢印 **。 + - ツール呼び出しには ** 点線の矢印 **。 + - MCP サーバー呼び出しには ** 破線の矢印 **。 +- 実行の終了点を示す ** エンド ノード **（`__end__`）。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、 `draw_graph` はグラフをインライン表示します。グラフを別ウィンドウで表示するには、次のようにします: +デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、 `draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: +デフォルトでは、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index d3f29dcc2..df758a06d 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント ワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の書き起こし、音声の終了検知、適切なタイミングでのワークフロー呼び出し、さらにワークフローの出力を音声へ戻す処理までを引き受けます。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントのワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声に戻す処理を行います。 ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際には、次の項目を設定できます。 +パイプラインの作成時に、次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]。新しい音声が書き起こされるたびに実行されるコードです。 -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデルです。 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。次のような項目を設定できます。 - - モデルプロバイダー。モデル名をモデルに対応付けできます - - トレーシング。トレーシングの無効化可否、音声ファイルのアップロード可否、ワークフロー名、トレース ID など - - TTS と STT モデルの設定（使用するプロンプト、言語、データ型など） +1. 新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル +3. 次のような設定が可能な [`config`][agents.voice.pipeline_config.VoicePipelineConfig] + - モデル名をモデルにマッピングできるモデルプロバイダー + - トレーシング（トレーシングの無効化、音声ファイルのアップロード可否、ワークフロー名、トレース ID など） + - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） ## パイプラインの実行 パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の書き起こしがあり、その結果だけを生成したい場合に使います。話者の発話終了を検知する必要がない状況、たとえば事前録音の音声がある場合や、ユーザーの発話終了が明確な push-to-talk アプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検知する必要がある場合に使います。検出された音声チャンクを逐次プッシュでき、音声パイプラインが 「activity detection」 と呼ばれる処理により適切なタイミングでエージェントのワークフローを自動実行します。 +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 d1067f32b..bad5568eb 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,19 +6,19 @@ search: ## 前提条件 -まず、 Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。次に、 SDK から音声用のオプション依存関係をインストールします: +Agents SDK の基本 [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' ``` -## 概念 +## コンセプト -主要な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、 3 段階のプロセスです: +主なコンセプトは [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 段階のプロセスです: -1. 音声認識 (speech-to-text) モデルを実行して、音声をテキストに変換します。 -2. 通常はエージェント的なワークフローであるご自身のコードを実行して、結果を生成します。 -3. テキスト読み上げ (text-to-speech) モデルを実行して、結果のテキストを音声に戻します。 +1. 音声をテキストに変換するために音声認識モデルを実行します。 +2. 通常はエージェント的なワークフローであるあなたのコードを実行して、結果を生成します。 +3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定します。これは、この SDK でエージェントを構築したことがある方にはおなじみのはずです。ここでは、 2 つのエージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。これは、この SDK でエージェントを作成したことがあれば見覚えがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使い、シンプルな音声パイプラインを設定します。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインをセットアップします。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## 統合 +## 全体の統合 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -このサンプルを実行すると、エージェントがあなたに話しかけます。[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) のサンプルで、エージェントと会話できるデモをご覧ください。 \ No newline at end of file +この例を実行すると、エージェントがあなたに話しかけます。自分でエージェントに話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 619ecd4c5..2e6dc3fe6 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -上記の [エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレースされます。 +[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] でパイプラインのトレーシングを構成できます。 +上記のトレーシングのドキュメントで基本的な情報を確認できますが、さらに [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを設定できます。 トレーシングに関連する主なフィールドは次のとおりです: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは、トレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の文字起こしなど、機密になり得るデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、お使いの Workflow 内で行われる処理には適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースワークフローの名前です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` です。複数のトレースを関連付けることができます。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしのような、機微な可能性のあるデータをトレースに含めるかどうかを制御します。これは音声パイプラインに特有の設定であり、ワークフロー内部で行われる処理には適用されません。 +- [`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