From f55e765d6a4c2b418715f762a459c30b1a6745bc Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 28 Jul 2025 23:58:29 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/agents.md | 46 ++++++++-------- docs/ja/config.md | 24 ++++----- docs/ja/context.md | 44 ++++++++-------- docs/ja/examples.md | 30 +++++------ docs/ja/guardrails.md | 40 +++++++------- docs/ja/handoffs.md | 36 ++++++------- docs/ja/index.md | 40 +++++++------- docs/ja/mcp.md | 58 ++++++++++---------- docs/ja/models/index.md | 82 +++++++++++++++-------------- docs/ja/models/litellm.md | 20 +++---- docs/ja/multi_agent.md | 42 +++++++-------- docs/ja/quickstart.md | 40 +++++++------- docs/ja/realtime/guide.md | 96 +++++++++++++++++----------------- docs/ja/realtime/quickstart.md | 48 ++++++++--------- docs/ja/release.md | 22 ++++---- docs/ja/repl.md | 8 +-- docs/ja/results.md | 42 +++++++-------- docs/ja/running_agents.md | 87 +++++++++++++++--------------- docs/ja/sessions.md | 34 ++++++------ docs/ja/streaming.md | 16 +++--- docs/ja/tools.md | 86 +++++++++++++++--------------- docs/ja/tracing.md | 90 ++++++++++++++++--------------- docs/ja/visualization.md | 31 ++++++----- docs/ja/voice/pipeline.md | 30 ++++++----- docs/ja/voice/quickstart.md | 18 +++---- docs/ja/voice/tracing.md | 18 +++---- 26 files changed, 565 insertions(+), 563 deletions(-) diff --git a/docs/ja/agents.md b/docs/ja/agents.md index edab75997..c2eba6300 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中心となる構成要素です。エージェントは、大規模言語モデル ( LLM ) を instructions とツールで設定したものです。 +エージェントは、アプリにおける中核的なビルディングブロックです。エージェントは、インストラクションとツールで構成された LLM です。 ## 基本設定 -エージェントで最もよく設定するプロパティは以下のとおりです。 +エージェントで最もよく設定するプロパティは次のとおりです: -- `name` : エージェントを識別する必須の文字列です。 -- `instructions` : developer メッセージまたは system prompt とも呼ばれます。 -- `model` : 使用する LLM を指定します。また、`temperature` 、`top_p` などのモデル調整パラメーターを設定する `model_settings` をオプションで指定できます。 -- `tools` : エージェントがタスクを達成するために使用できるツールです。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: 開発者メッセージ、または system prompt とも呼ばれます。 +- `model`: 使用する LLM を指定します。`model_settings` を併用すると temperature、top_p などのモデル調整パラメーターを設定できます。 +- `tools`: エージェントがタスク達成のために使用できるツールです。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型についてジェネリックです。コンテキストは依存性注入用のツールで、`Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、実行中の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入の仕組みで、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係と状態を格納する入れ物として機能します。コンテキストには任意の Python オブジェクトを指定できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト（つまり `str`）を出力します。特定の型で出力を受け取りたい場合は、`output_type` パラメーターを使用します。よく使われるのは Pydantic オブジェクトですが、Pydantic TypeAdapter でラップできる型であれば何でも対応しています。たとえば dataclasses 、lists 、TypedDict などです。 +既定では、エージェントはプレーンテキスト (つまり `str`) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用できます。よく使われるのは Pydantic オブジェクトですが、Pydantic の TypeAdapter でラップできる型 — dataclass、list、TypedDict など — であれば何でもサポートしています。 ```python from pydantic import BaseModel @@ -73,11 +73,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルに通常のプレーンテキストではなく structured outputs を使用するよう指示します。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答の代わりに structured outputs を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは必要に応じてそれらに処理を委任できます。これは、単一のタスクに特化したモジュール化されたエージェントをオーケストレーションする強力なパターンです。詳細は [handoffs](handoffs.md) ドキュメントを参照してください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、必要に応じてエージェントがそれらに処理を委譲できます。これは、単一タスクに特化したモジュール式のエージェントをオーケストレーションする強力なパターンです。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -96,9 +96,9 @@ triage_agent = Agent( ) ``` -## 動的 instructions +## 動的インストラクション -ほとんどの場合、エージェント作成時に instructions を指定できます。ただし、関数を通じて動的 instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数と `async` 関数の両方が使用可能です。 +通常はエージェント作成時にインストラクションを指定しますが、関数を介して動的に渡すこともできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が利用可能です。 ```python def dynamic_instructions( @@ -113,17 +113,17 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクルイベント（フック） -エージェントのライフサイクルを監視したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりしたい場合です。`hooks` プロパティを使用してエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、興味のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観察したい場合があります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータをプリフェッチしたりするケースです。そのようなときは `hooks` プロパティを使ってライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスを継承し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対してチェックやバリデーションを実行できます。たとえば、ユーザー入力の関連性をフィルタリングすることが可能です。詳細は [guardrails](guardrails.md) ドキュメントをご覧ください。 +ガードレールを使用すると、エージェントの実行と並行してユーザー入力のチェックやバリデーションを行えます。たとえば、ユーザー入力の関連性をスクリーニングできます。詳細は [guardrails](guardrails.md) ドキュメントを参照してください。 ## エージェントのクローン/コピー -`clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -140,15 +140,15 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、 LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツールの使用を強制できます。有効な値は次のとおりです。 +ツールのリストを指定しても、 LLM が必ずしもツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。指定可能な値は次のとおりです: -1. `auto` : LLM がツールを使用するかどうかを判断します。 -2. `required` : LLM にツール使用を必須とします（どのツールを使うかは LLM が判断します）。 -3. `none` : LLM にツールを使用しないよう要求します。 -4. 具体的な文字列を指定する（`my_tool` など）: LLM にそのツールを必ず使用させます。 +1. `auto` — LLM がツールを使うかどうかを判断します。 +2. `required` — LLM にツールの使用を必須とします (ただしどのツールを使うかは自動で判断)。 +3. `none` — LLM にツールを使用しないことを要求します。 +4. 具体的な文字列 (例: `my_tool`) — LLM にその特定のツールを使用させます。 !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に `auto` にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループとは、ツールの結果が LLM に送られ、その後 `tool_choice` により再びツール呼び出しが生成される、というサイクルが延々と続くことを指します。 + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この挙動は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、それにより `tool_choice` の設定でさらにツール呼び出しが生成される、というサイクルが延々と続くために発生します。 - ツール呼び出し後に auto モードで続行せず、完全に停止させたい場合は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定してください。ツール出力をそのまま最終応答として使用し、追加の LLM 処理を行いません。 \ No newline at end of file + ツール呼び出し後に (auto モードで続行するのではなく) エージェントを完全に停止させたい場合は、[`Agent.tool_use_behavior="stop_on_first_tool"`] を設定してください。これにより、ツールの出力をそのまま最終レスポンスとして使用し、追加の LLM 処理を行いません。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 4f628be35..bfaabb3a3 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポート直後に LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を参照します。アプリ起動前にこの環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 +デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -あるいは、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または前述のデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。これを変更したい場合は、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用してください。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数で指定された API キーまたは上記で設定したデフォルトキーを使って `AsyncOpenAI` インスタンスを生成します。 [set_default_openai_client()][agents.set_default_openai_client] 関数を使うことでこれを変更できます。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、利用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を使用しますが、[set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API に切り替えられます。 +最後に、使用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を使用しますが、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API に変更できます。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効になっています。使用される OpenAI API キーは前述の方法（環境変数または設定したデフォルトキー）と同じです。トレーシングで使用する API キーを個別に設定する場合は、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。デフォルトでは、上記セクションと同じ OpenAI API キー（環境変数または設定したデフォルトキー）を使用します。 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使ってトレーシングに使用する API キーを個別に設定できます。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化したい場合は、[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 +[`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用してトレーシングを完全に無効化することもできます。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグログ +## デバッグロギング -SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、警告とエラーは `stdout` に出力されますが、それ以外のログは抑制されます。 + SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは警告とエラーが `stdout` に出力され、その他のログは抑制されます。 -詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 +詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー・フィルター・フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python logging ガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python logging ガイド](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 9a17f605c..53a100b18 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語は多義的です。主に次の 2 種類のコンテキストがあります。 +コンテキストという語は多義的です。関心を持つ可能性があるコンテキストには、大きく 2 つの種類があります。 -1. ローカルでコードから参照できるコンテキスト: ツール関数が実行される際や `on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 -2. LLM が参照できるコンテキスト: レスポンスを生成するときに LLM が目にするデータです。 +1. コードからローカルに利用できるコンテキスト: ツール関数実行時、`on_handoff` などのコールバック、ライフサイクルフック内で必要になるデータや依存関係です。 +2. LLM から利用できるコンテキスト: LLM が応答を生成する際に参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表されます。動作の流れは以下のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスおよびその [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使うパターンが多いです。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使用します。 2. そのオブジェクトを各種 run メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 -3. すべてのツール呼び出しやライフサイクルフックには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はあなたのコンテキストオブジェクト型で、 `wrapper.context` からアクセスできます。 +3. すべてのツール呼び出しやライフサイクルフックには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。`T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -最も重要なポイント: 1 回のエージェント実行において、エージェント・ツール関数・ライフサイクルフックなどが使用するコンテキストは、必ず同じ “型” でなければなりません。 +**最も重要** な注意点: 同じエージェント実行内のすべてのエージェント、ツール関数、ライフサイクルフックは、同一 _型_ のコンテキストを使用しなければなりません。 -コンテキストでできることの例: +コンテキストは次のような用途に利用できます。 -- 実行時のコンテキストデータ（例: ユーザー名 / UID など ユーザー に関する情報） -- 依存関係（例: ロガーオブジェクト、データ取得用オブジェクトなど） -- ヘルパー関数 +- 実行に関するコンテキストデータ（例: ユーザー名 / uid など user に関する情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは LLM には送信されません。完全にローカルなオブジェクトであり、読み書きやメソッド呼び出しのみが可能です。 + コンテキストオブジェクトは **LLM へ送信されません**。純粋にローカルで読み書きやメソッド呼び出しを行うためのオブジェクトです。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。 -2. これはツールです。 `RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. エージェントにジェネリック型 `UserInfo` を指定することで、型チェッカーが誤りを検知できます（たとえば異なるコンテキスト型を取るツールを渡した場合など）。 -4. `run` 関数にコンテキストを渡します。 -5. エージェントはツールを正しく呼び出し、年齢を取得します。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型で構いません。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを読み取っています。 +3. エージェントをジェネリック型 `UserInfo` でマークすることで、型チェッカーが誤り（例: 異なるコンテキスト型のツールを渡した場合）を検出できます。 +4. `run` 関数にコンテキストを渡しています。 +5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント / LLM コンテキスト -LLM が呼び出される際に参照できるデータは、会話履歴に含まれるものだけです。そのため、新しいデータを LLM に利用させたい場合は、会話履歴に載せる形で提供する必要があります。主な方法は次のとおりです。 +LLM が呼び出される際、**唯一** 参照できるデータは会話履歴からのものです。そのため、新しいデータを LLM に利用させたい場合は、その履歴に組み込む形で提供しなければなりません。主な方法は次のとおりです。 -1. エージェントの `instructions` に追加する。これは “system prompt” や “developer message” とも呼ばれます。`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. function tools で公開する。オンデマンドのコンテキストに便利で、LLM が必要になったときにツールを呼び出してデータを取得させられます。 -4. Retrieval や Web 検索を使う。これらはファイルやデータベースから関連データを取得する retrieval、または Web から取得する Web 検索という特殊なツールです。関連するコンテキストデータに基づいて回答を “グラウンディング” したい場合に有用です。 \ No newline at end of file +1. エージェントの `instructions` に追加する。これは「system prompt」や「developer message」としても知られます。system prompt は静的文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。たとえば user の名前や現在の日付など、常に役立つ情報を提供する一般的な手法です。 +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. function tools を通じて公開する。必要に応じて LLM がデータを取得できるオンデマンド型のコンテキストに適しています。 +4. リトリーバルや Web 検索を利用する。これらはファイルやデータベースから関連データを取得する（リトリーバル）、または Web から取得する（Web 検索）特殊なツールです。関連するコンテキストデータで応答を「グラウンディング」したい場合に有効です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 7e2621773..5b4cf5d35 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,45 +4,41 @@ search: --- # コード例 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションには、 SDK のさまざまなサンプル実装が掲載されています。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 - +さまざまな sample implementation of the SDK は、[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションでご覧いただけます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[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 の基本機能を紹介するコード例です。例: - - - 動的な system prompt - - ストリーミング出力 + このカテゴリーのコード例では、 SDK の基礎的な機能を紹介しています。例： + - 動的なシステムプロンプト + - 出力のストリーミング - ライフサイクルイベント - **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索やファイル検索などの OpenAI がホストするツールを実装し、それらをエージェントに統合する方法を学べます。 + Web 検索やファイル検索など、OpenAI がホストするツールを実装し、エージェントに統合する方法を学べます。 - **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを SDK で使用する方法を探求できます。 + OpenAI 以外のモデルを SDK で利用する方法を紹介します。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフの実践的な例をご覧いただけます。 + エージェントのハンドオフの実践例をご覧ください。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP を使用してエージェントを構築する方法を学べます。 + MCP を用いてエージェントを構築する方法を学びます。 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 実際のアプリケーションを示す、さらに 2 つの充実したコード例 - + 実際のアプリケーションを示す、より作り込まれた 2 つのコード例 - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 - **research_bot**: シンプルなディープリサーチクローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを使用した音声エージェントの例をご覧ください。 + TTS と STT モデルを使った音声エージェントの例をご覧ください。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使用してリアルタイム体験を構築する方法を示すコード例。 \ No newline at end of file + SDK を使ってリアルタイム体験を構築する方法を示すコード例。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index 4e1e05647..1acd066b6 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並列_ に実行され、ユーザー入力のチェックとバリデーションを行えます。例えば、非常に賢い（その分、遅くて高価な）モデルを用いて顧客リクエストに対応するエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を手伝わせるようなことは避けたいでしょう。そこで、高速かつ低コストのモデルでガードレールを走らせることができます。ガードレールが不正利用を検知したら、即座にエラーを発生させ、高価なモデルの実行を停止して時間とコストを節約します。 +ガードレールはエージェントと _並列_ に実行され、ユーザー入力のチェックやバリデーションを行います。たとえば、顧客リクエストを支援するためにとても賢い（その分、遅く・高価な）モデルを使うエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせるような要求をしてほしくはありません。そのため、速く・安価なモデルでガードレールを実行できます。ガードレールが悪意ある使用を検出した場合、直ちにエラーを発生させ、高価なモデルの実行を停止し、時間とコストを節約できます。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. 入力ガードレール: 初回のユーザー入力に対して実行されます -2. 出力ガードレール: 最終的なエージェント出力に対して実行されます +1. 入力ガードレールは初期のユーザー入力で実行されます +2. 出力ガードレールは最終的なエージェント出力で実行されます ## 入力ガードレール -入力ガードレールは次の 3 ステップで動作します。 +入力ガードレールは 3 ステップで実行されます: 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が `true` かどうかを確認します。`true` の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるので、適切にユーザーへ応答したり例外処理を行ったりできます。 +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 @@ -95,9 +95,9 @@ async def main(): ``` 1. このエージェントをガードレール関数内で使用します。 -2. これがガードレール関数で、エージェントの入力／コンテキストを受け取り結果を返します。 -3. ガードレールの結果に追加情報を含めることもできます。 -4. これが実際にワークフローを定義するエージェントです。 +2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレール結果に追加情報を含めることができます。 +4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -154,5 +154,5 @@ async def main(): 1. これは実際のエージェントの出力型です。 2. これはガードレールの出力型です。 -3. これがエージェントの出力を受け取り結果を返すガードレール関数です。 -4. これが実際にワークフローを定義するエージェントです。 \ No newline at end of file +3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 +4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 303e0b046..15535e4a0 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # ハンドオフ -ハンドオフを使用すると、エージェントはタスクを別のエージェントに委任できます。これは、各エージェントが異なる分野を専門とするシナリオで特に便利です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などを個別に担当するエージェントがいる場合があります。 +ハンドオフを使用すると、エージェントはタスクを別のエージェントに委任できます。これは、異なるエージェントがそれぞれ特定の分野に特化しているシナリオで特に有用です。たとえば、カスタマーサポート アプリでは、注文状況、返金、FAQ などのタスクをそれぞれ担当するエージェントが存在する場合があります。 -ハンドオフは LLM に対してツールとして表現されます。そのため、`Refund Agent` へのハンドオフがある場合、ツール名は `transfer_to_refund_agent` となります。 +ハンドオフは LLM には tool として表現されます。そのため、`Refund Agent` というエージェントへのハンドオフであれば、tool 名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接指定するか、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡せます。 +すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントのほか、オーバーライドや入力フィルターをオプションで指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、各種オーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -以下はシンプルなハンドオフの作成例です。 +シンプルなハンドオフを作成する方法は次のとおりです: ```python from agents import Agent, handoff @@ -28,18 +28,18 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のようにエージェントを直接渡すことも、`handoff()` 関数を使用することもできます。 +1. `billing_agent` のようにエージェントを直接指定することも、`handoff()` 関数を利用することもできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][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()` で生成される既定の tool 説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが実行された瞬間にデータ取得を開始するなどの用途に便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで想定される入力の型です (省略可)。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は後述します。 ```python from agents import Agent, handoff, RunContextWrapper @@ -59,7 +59,7 @@ handoff_obj = handoff( ## ハンドオフ入力 -状況によっては、ハンドオフを呼び出す際に LLM からデータを受け取りたい場合があります。たとえば「エスカレーションエージェント」へのハンドオフでは、ログ用に理由を渡したいかもしれません。 +状況によっては、LLM がハンドオフを呼び出す際にデータを渡してほしい場合があります。たとえば「エスカレーション エージェント」へのハンドオフでは、理由を受け取り、それを記録したいことが考えられます。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を参照できます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定します。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] を受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、それまでの全履歴を閲覧できる状態になります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] を受け取り、新しい `HandoffInputData` を返す関数です。 -よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +一般的なパターン (たとえば履歴からすべての tool 呼び出しを削除するなど) は、[`agents.extensions.handoff_filters`][] に実装されています。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. `FAQ agent` が呼び出されると、履歴からツール呼び出しが自動的に削除されます。 +1. これにより `FAQ agent` が呼び出される際、履歴からすべての tool が自動的に除去されます。 ## 推奨プロンプト -LLM にハンドオフを正しく理解させるため、エージェントのプロンプトにハンドオフ情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、あるいは [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに自動で必要な情報を追加できます。 +LLM がハンドオフを正しく理解できるよう、エージェント内にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨されるプレフィックスを用意しているほか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出すことで、推奨事項を自動でプロンプトに追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 461efcf13..e0a58b1ac 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) の実装を、実運用向けにアップグレードしたものです。本 SDK には、ごく少数の基本コンポーネントが含まれます。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージにより、エージェント型 AI アプリケーションを構築できるようにします。これは、エージェントに関する以前の実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番環境向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 -- **エージェント** 、指示とツールを備えた LLM -- **ハンドオフ** 、特定タスクを他のエージェントに委任する仕組み -- **ガードレール** 、エージェントへの入力を検証する機能 -- **セッション** 、エージェント実行間で会話履歴を自動管理する仕組み +- **エージェント**： instructions と tools を備えた LLM です +- **ハンドオフ**：特定のタスクを他のエージェントに委任できます +- **ガードレール**：エージェントへの入力を検証できます +- **セッション**：エージェントの実行間で会話履歴を自動的に維持します -Python と組み合わせることで、これらのコンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに SDK には **トレーシング** が標準搭載されており、エージェントフローの可視化・デバッグに加え、評価やモデルのファインチューニングにも活用できます。 +Python と組み合わせることで、これらの基本コンポーネントは tools とエージェント間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに、SDK には組み込みの tracing が付属しており、エージェントのフローを可視化・デバッグできるほか、評価やモデルのファインチューニングにも活用できます。 -## Agents SDK の利点 +## Agents SDK を使用する理由 -本 SDK は、次の 2 つの設計原則に基づいています。 +SDK には 2 つの設計原則があります。 -1. 使用する価値のある十分な機能を備えつつ、学習が容易になるようコンポーネントを絞り込む。 -2. デフォルト設定で高い利便性を提供しつつ、必要に応じて挙動を細かくカスタマイズできる。 +1. 使う価値のある十分な機能を備えつつ、学習を早めるために基本コンポーネントは少なくする。 +2. デフォルトで優れた動作を提供しつつ、必要に応じて挙動を細かくカスタマイズできる。 -主な機能は次のとおりです。 +以下は SDK の主な機能です。 -- エージェントループ: ツール呼び出し、結果の LLM への送信、完了までのループ処理を自動化。 -- Python ファースト: 新しい抽象概念を覚える必要なく、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 2d4c99a0c..e0d188205 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,23 +4,23 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction)（通称 MCP）は、LLM にツールとコンテキストを提供する方法です。MCP ドキュメントからの引用: +[Model context protocol](https://modelcontextprotocol.io/introduction)（通称 MCP）は、LLM へツールとコンテキストを提供するための仕組みです。MCP ドキュメントからの引用です。 -> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションの USB-C ポートのようなものだと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLM へコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに標準的な方法で接続できるようにするのと同じく、MCP は AI モデルを異なるデータソースやツールに標準的な方法で接続できるようにします。 -Agents SDK は MCP をサポートしています。これにより、さまざまな MCP サーバーを使ってエージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを利用してエージェントへツールやプロンプトを提供できます。 ## MCP サーバー -現在、MCP 仕様では使用するトランスポートメカニズムに基づき、次の 3 種類のサーバーが定義されています。 +現在、MCP 仕様は使用するトランスポートメカニズムに基づき、次の 3 種類のサーバーを定義しています。 -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動作するイメージです。 -2. **HTTP over SSE** サーバー: リモートで動作し、URL で接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを用いてリモートで動作します。 +1. **stdio** サーバー: アプリケーションのサブプロセスとして実行され、ローカルで動作するイメージです。 +2. **HTTP over SSE** サーバー: リモートで実行され、URL で接続します。 +3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらのサーバーへは `MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp` クラスを用いて接続できます。 -例として、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を利用する場合は次のようになります。 +たとえば、公式 MCP ファイルシステムサーバーを使用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの使用 -MCP サーバーはエージェントに追加できます。Agents SDK はエージェント実行時に毎回 MCP サーバーの `list_tools()` を呼び出し、LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 +MCP サーバーはエージェントに追加できます。Agents SDK はエージェント実行時に毎回 MCP サーバーへ `list_tools()` を呼び出し、LLM に MCP サーバーのツールを認識させます。LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーへ `call_tool()` を実行します。 ```python @@ -52,13 +52,13 @@ agent=Agent( ) ``` -## ツールフィルタリング +## ツールのフィルタリング -MCP サーバーでツールフィルターを設定すると、エージェントで使用可能なツールを絞り込めます。SDK は静的フィルタリングと動的フィルタリングの両方をサポートします。 +MCP サーバーでツールフィルターを設定することで、エージェントが利用できるツールを制御できます。SDK は静的および動的なツールフィルタリングの両方をサポートしています。 ### 静的ツールフィルタリング -単純な許可 / ブロックリストの場合は、静的フィルタリングを使用します。 +単純な許可 / ブロックリストの場合は静的フィルタリングを使用できます。 ```python from agents.mcp import create_static_tool_filter @@ -87,15 +87,15 @@ server = MCPServerStdio( ``` -**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合、処理順序は以下のとおりです。** -1. まず `allowed_tool_names` (許可リスト) を適用し、指定したツールだけを残す -2. 次に `blocked_tool_names` (ブロックリスト) を適用し、残ったツールから指定したものを除外する +**`allowed_tool_names` と `blocked_tool_names` の両方が設定されている場合、処理順序は次のとおりです。** +1. まず `allowed_tool_names`（許可リスト）を適用し、指定されたツールだけを残します。 +2. 次に `blocked_tool_names`（ブロックリスト）を適用し、残ったツールから指定されたツールを除外します。 -たとえば、`allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、`read_file` と `write_file` だけが使用可能になります。 +例: `allowed_tool_names=["read_file", "write_file", "delete_file"]` と `blocked_tool_names=["delete_file"]` を設定すると、利用可能なのは `read_file` と `write_file` のみになります。 ### 動的ツールフィルタリング -より複雑なロジックが必要な場合は、関数を使った動的フィルターを使用できます。 +より複雑なフィルタリングロジックが必要な場合は、関数を使った動的フィルターを利用できます。 ```python from agents.mcp import ToolFilterContext @@ -134,21 +134,21 @@ server = MCPServerStdio( ) ``` -`ToolFilterContext` では以下にアクセスできます。 -- `run_context`: 現在の実行コンテキスト +`ToolFilterContext` でアクセスできる情報 +- `run_context`: 現在のランコンテキスト - `agent`: ツールを要求しているエージェント - `server_name`: MCP サーバー名 ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成するためのプロンプトも提供できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instruction テンプレートを作成できます。 +MCP サーバーはプロンプトも提供でき、これを使ってエージェントの instructions を動的に生成できます。これにより、パラメーターでカスタマイズ可能な再利用可能な instructions テンプレートを作成できます。 ### プロンプトの使用 -プロンプトをサポートする MCP サーバーは次の 2 つの主要メソッドを提供します。 +プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します。 -- `list_prompts()`: サーバー上の利用可能なすべてのプロンプトを一覧表示 -- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得 +- `list_prompts()`: サーバー上で利用可能なすべてのプロンプトを一覧表示します。 +- `get_prompt(name, arguments)`: オプションのパラメーター付きで特定のプロンプトを取得します。 ```python # List available prompts @@ -173,17 +173,17 @@ 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`、`MCPServerSse`、`MCPServerStreamableHttp` に `cache_tools_list=True` を渡します。ツール一覧が変更されないことが確実な場合のみ使用してください。 -キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。 -## エンドツーエンドの例 +## エンドツーエンドのコード例 -動作する完全な例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) を参照してください。 +動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 ## トレーシング -[Tracing](./tracing.md) は MCP の操作を自動でキャプチャします。対象は次のとおりです。 +[トレーシング](./tracing.md) は MCP 操作を自動的に取得します。対象は次のとおりです。 1. MCP サーバーへのツール一覧取得呼び出し 2. 関数呼び出しに関する MCP 情報 diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index cc51646cf..663c11ed0 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,52 +4,54 @@ search: --- # モデル - Agents SDK には、OpenAI モデルに対するサポートが 2 つの形態で最初から組み込まれています。 +Agents SDK には、OpenAI モデルを以下 2 種類でサポートしています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を用いて OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、[Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を用いて OpenAI API を呼び出します。 +- **推奨**: [`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 依存グループをインストールしてください: +ほとんどの非 OpenAI モデルは [LiteLLM 連携](./litellm.md) 経由で利用できます。まずは litellm の依存関係グループをインストールしてください。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します: +次に、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) を利用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使用するその他の方法 +### 非 OpenAI モデルを利用するその他の方法 -他の LLM プロバイダーは、さらに 3 通りの方法で統合できます（コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）: +他社 LLM プロバイダーを連携する方法は 3 つあります（[コード例はこちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 1. [`set_default_openai_client`][agents.set_default_openai_client] - `AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。LLM プロバイダーが OpenAI 互換の 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) に設定例があります。 + グローバルに `AsyncOpenAI` インスタンスを LLM クライアントとして利用したい場合に便利です。OpenAI 互換エンドポイントを持つプロバイダーで、`base_url` と `api_key` を設定できるケースに適しています。[examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) に設定例があります。 2. [`ModelProvider`][agents.models.interface.ModelProvider] - `Runner.run` レベルで使用します。「この実行内のすべてのエージェントでカスタムのモデルプロバイダーを使う」と宣言できます。[examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) に設定例があります。 + `Runner.run` レベルで指定できます。「この実行内のすべてのエージェントでカスタムモデルプロバイダーを使う」といった場合に利用します。[examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) をご覧ください。 3. [`Agent.model`][agents.agent.Agent.model] - 特定の `Agent` インスタンスでモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。[examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) に設定例があります。多くのモデルを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) が便利です。 + 個々のエージェントごとにモデルを指定できます。エージェントごとに異なるプロバイダーを組み合わせたい場合に便利です。[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 - これらの例では Chat Completions API / モデルを使用しています。ほとんどの LLM プロバイダーがまだ Responses API に対応していないためです。もし利用中の LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 + + これらのコード例では Chat Completions API／モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしご利用のプロバイダーが Responses API をサポートしている場合は、Responses の利用をお勧めします。 ## モデルの組み合わせ -1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、軽量で高速なモデルでトリアージを行い、より大きく高性能なモデルで複雑なタスクを処理するといった使い分けです。[`Agent`][agents.Agent] を設定する際には、以下の方法でモデルを選択できます。 +単一のワークフロー内でエージェントごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小型で高速なモデルを使い、複雑なタスクには高性能モデルを使う、といったケースです。[`Agent`][agents.Agent] を設定する際は、以下のいずれかでモデルを指定できます。 -1. モデル名を直接渡す -2. モデル名と、それを `Model` インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す -3. [`Model`][agents.models.interface.Model] 実装を直接渡す +1. モデル名を直接渡す。 +2. 任意のモデル名と、その名前を [`ModelProvider`][agents.models.interface.ModelProvider] が `Model` インスタンスへマッピングできるようにする。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、ワークフローごとに 1 つのモデル形状を使用することを推奨します。両モデル形状は利用できる機能やツールが異なるためです。ワークフローで両方を混在させる場合は、使用するすべての機能が両モデルで利用可能かを確認してください。 + + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、1 つのワークフローではどちらか 1 つのモデル形状を使うことを推奨します。両者は利用できる機能やツールが異なるためです。もし混在させる場合は、使用する機能が両モデルでサポートされていることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -82,10 +84,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI モデル名を直接指定 -2. [`Model`][agents.models.interface.Model] 実装を提供 +1. OpenAI モデル名を直接指定しています。 +2. [`Model`][agents.models.interface.Model] 実装を渡しています。 -エージェントに使用するモデルをさらに細かく設定したい場合は、`temperature` などのオプション設定を持つ [`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。 +エージェントで利用するモデルをさらに細かく設定したい場合は、`temperature` などのオプションを持つ [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -98,7 +100,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する際には、`user` や `service_tier` などの[追加パラメーター](https://platform.openai.com/docs/api-reference/responses/create) を指定できます。トップレベルで利用できない場合は、`extra_args` に渡してください。 +また、OpenAI の Responses API を利用する場合、`user` や `service_tier` など [追加のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) がいくつかあります。トップレベルで指定できない場合は、`extra_args` に渡してください。 ```python from agents import Agent, ModelSettings @@ -114,29 +116,29 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー利用時の一般的な問題 +## 他社 LLM プロバイダー使用時によくある問題 -### Tracing client error 401 +### トレーシングクライアントの 401 エラー -トレーシング関連のエラーが発生する場合、これはトレースが OpenAI サーバーへアップロードされるため、OpenAI の API キーがないことが原因です。以下のいずれかで解決できます。 +トレーシングは OpenAI サーバーへアップロードされるため、OpenAI API キーがないとエラーになります。解決策は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] - この API キーはトレースのアップロード専用で、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 -3. OpenAI 以外のトレースプロセッサーを使用する。詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシングを完全に無効にする — [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. トレーシング用の OpenAI キーを設定する — [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] + この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のキーである必要があります。 +3. OpenAI 以外のトレースプロセッサーを使用する — 詳細は [tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、ほとんどの他社 LLM プロバイダーはまだ対応していません。このため 404 エラーなどが発生する場合があります。以下のいずれかを試してください。 +SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーは未対応です。そのため 404 などのエラーが発生する場合があります。解決策は次の 2 つです。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す - `OPENAI_API_KEY` と `OPENAI_BASE_URL` を環境変数で設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する - [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にコード例があります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。 + これは環境変数 `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。 + [コード例はこちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) を参照してください。 ### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 ``` @@ -144,12 +146,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダーの制限で、JSON 出力には対応しているものの、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON Schema 出力をサポートするプロバイダーを利用することを推奨します。そうしないと、不正な JSON によりアプリが頻繁に壊れる可能性があります。 +これは一部プロバイダーの制限で、JSON 出力はサポートしていても `json_schema` を指定できないためです。現在修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーを利用することを推奨します。そうでない場合、JSON が不正でアプリが破損することが頻繁に起こります。 -## プロバイダーを跨いだモデルの組み合わせ +## プロバイダーをまたいだモデルの混在 -モデルプロバイダー間の機能差を理解しておかないと、エラーを招く可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホストされた file search / web search をサポートしていますが、多くの他社プロバイダーはこれらをサポートしていません。以下の制限に注意してください。 +プロバイダーごとにサポート機能が異なるため、注意が必要です。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search・web search をサポートしていますが、多くの他社プロバイダーは未対応です。以下の点にご注意ください。 -- 対応していないプロバイダーに `tools` を送らない -- テキストのみのモデルを呼び出す前にマルチモーダル入力を除去する -- structured JSON outputs をサポートしないプロバイダーでは、無効な JSON が返る場合があることを念頭に置く \ No newline at end of file +- 対応していない `tools` を理解できないプロバイダーに送らない +- テキスト専用モデルを呼び出す前にマルチモーダル入力を除外する +- structured JSON outputs をサポートしないプロバイダーでは無効な JSON が生成される可能性があることを理解する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 9523c35ea..5f4f923d0 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -6,29 +6,29 @@ search: !!! note - LiteLLM 連携はベータ版です。一部の小規模プロバイダーでは問題が発生する可能性があります。何か問題があれば、[Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応いたします。 + LiteLLM インテグレーションはベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。[Github issues](https://github.com/openai/openai-agents-python/issues) から問題を報告いただければ、迅速に対応します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK では LiteLLM 連携を追加することで、任意の AI モデルを使用できます。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK では LiteLLM インテグレーションを追加し、任意の AI モデルを使用できるようにしました。 ## セットアップ -`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで対応できます。 +`litellm` が利用可能であることを確認してください。これは、オプションの `litellm` 依存グループをインストールすることで実現できます。 ```bash pip install "openai-agents[litellm]" ``` -インストール後、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +インストール後は、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 -## 使用例 +## 例 -以下は完全に動作するコード例です。実行すると、モデル名と API キーの入力を求められます。たとえば、次のように入力できます。 +以下は完全に動作する例です。実行するとモデル名と API キーの入力を求められます。たとえば次のように入力できます。 -- モデルに `openai/gpt-4.1`、API キーにあなたの OpenAI API キー -- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーにあなたの Anthropic API キー -- その他 +- モデルに `openai/gpt-4.1`、API キーに OpenAI API キー +- モデルに `anthropic/claude-3-5-sonnet-20240620`、API キーに Anthropic API キー +- など -LiteLLM がサポートしているモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM でサポートされているモデルの全一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index dd49322d1..507416f10 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内でエージェントがどのように流れるかを指します。どのエージェントをいつ実行し、次に何をするかをどのように決定するのか、ということです。エージェントをオーケストレーションする主な方法は二つあります。 +オーケストレーションとは、アプリ内での エージェント のフローを指します。どの エージェント が実行されるのか、どの順序で実行されるのか、そして次に何を行うかをどのように判断するのかを決定します。エージェント をオーケストレーションする方法は主に 2 つあります: -1. LLM に意思決定させる: これは LLM の知性を利用して計画・推論を行い、それに基づいて次のステップを決定します。 -2. コードでオーケストレーションする: コードによってエージェントの流れを決定します。 +1. LLM に意思決定させる: LLM の知能を活用して計画・推論し、それに基づき次に取るステップを決定します。 +2. コードでオーケストレーションする: エージェント のフローをコードで制御します。 これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、 instructions、 tools、 handoffs を備えた LLM です。これにより、オープンエンドなタスクが与えられたとき、 LLM はタスクへの取り組み方を自律的に計画し、 tools を用いてアクションやデータ取得を行い、 handoffs によってサブエージェントへタスクを委譲できます。たとえば、リサーチ用エージェントには次のような tools を持たせることができます。 +エージェント とは、 instructions、 tools、 handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM は自律的にタスクへの取り組み方を計画し、 tools を使ってアクションを実行してデータを取得し、 handoffs を使ってサブエージェントへタスクを委譲できます。たとえば、リサーチ用の エージェント には次のような tools を装備できます: -- Web 検索でオンラインの情報を取得する -- ファイル検索と取得で自社データや接続先を調べる -- コンピュータ操作で PC 上のアクションを実行する -- コード実行でデータ分析を行う -- プランニングやレポート作成などが得意な専門エージェントへの handoffs +- Web 検索でオンライン情報を取得 +- ファイル検索 とリトリーバルで独自データや接続情報を検索 +- コンピュータ操作 でコンピュータ上のアクションを実行 +- コード実行でデータ分析を行う +- 優れた計画立案やレポート作成を行う専門 エージェント への handoffs -タスクがオープンエンドで LLM の知性に頼りたい場合、このパターンは非常に有用です。ここで重要な戦術は次のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知能に頼りたい場合に最適です。重要な戦術は次のとおりです: -1. 良いプロンプトに投資する。利用可能な tools、その使い方、そしてどのパラメーター内で動作すべきかを明確にします。 -2. アプリをモニタリングし、イテレーションを重ねる。問題が発生する箇所を確認し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえば、ループで実行して自己批評させる、あるいはエラーメッセージを渡して改善させるなどです。 -4. 何でもできる汎用エージェントではなく、特定のタスクに特化して優れた専門エージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを学習させて、タスクへの適性を向上させられます。 +1. 良いプロンプトに投資する。利用可能な tools とその使い方、そして守るべきパラメーターを明確にします。 +2. アプリをモニタリングして反復改善する。問題が起きた箇所を確認し、プロンプトを改善します。 +3. エージェント に内省と改善を許可する。たとえばループで実行し、自身を批評させたり、エラーメッセージを与えて改善させたりします。 +4. 何でもこなす汎用 エージェント ではなく、単一タスクに優れる専門 エージェント を用意します。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これにより エージェント を訓練し、タスク遂行能力を向上できます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードでオーケストレーションすると、速度・コスト・パフォーマンスの面でより決定論的かつ予測可能になります。ここでよく使われるパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードでオーケストレーションすると速度・コスト・性能面でより決定論的かつ予測可能になります。一般的なパターンは次のとおりです: -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用して、コードで検査できる適切な形式のデータを生成します。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択することができます。 -- 複数のエージェントをチェーンさせ、一方の出力を次の入力へ変換する。たとえばブログ記事の執筆というタスクを、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善という一連のステップに分解できます。 -- タスクを実行するエージェントと、それを評価してフィードバックを返すエージェントを `while` ループで回し、評価者が所定の基準を満たしたと判断するまで繰り返します。 -- 複数のエージェントを並列実行する。たとえば `asyncio.gather` のような Python の基本コンポーネントを使います。互いに依存しない複数タスクがある場合、速度向上に有効です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を用いて、コードで検査できる 適切な形式のデータ を生成する。たとえば エージェント にタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次の エージェント を選択します。 +- 複数の エージェント をチェーンし、1 つの出力を次の入力へ変換する。ブログ記事執筆のタスクを、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善という一連のステップに分解できます。 +- タスクを実行する エージェント を `while` ループで回し、別の エージェント が評価とフィードバックを行い、評価者が基準を満たしたと判断するまで繰り返します。 +- `asyncio.gather` など Python の basic components を使って複数の エージェント を並列実行する。互いに依存しない複数タスクがある場合に速度向上に有効です。 -コード例は [`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 7a6303f02..f86f3dd88 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -一度だけ実行すれば十分です。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初のエージェントの作成 +## 最初の エージェント を作成する -エージェントは `instructions`、名前、そして任意の設定（例: `model_config`）で定義します。 +エージェント は instructions、名前、任意の config（例: `model_config`）で定義されます。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## さらにエージェントを追加 +## さらに数個の エージェント を追加する -追加のエージェントも同じ方法で定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 +追加の エージェント も同じ方法で定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## ハンドオフの定義 +## ハンドオフを定義する -各エージェントでは、タスクを進める方法を選択する際に利用できる送信側ハンドオフオプションのインベントリを定義できます。 +各 エージェント では、タスクを進める方法を選択できるように、発信側ハンドオフオプションの一覧を定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ triage_agent = Agent( ) ``` -## エージェントオーケストレーションの実行 +## エージェント オーケストレーションを実行する -ワークフローが実行され、トリアージエージェントが 2 つの専門エージェント間で正しくルーティングするかを確認しましょう。 +ワークフローが実行され、トリアージ エージェント が 2 つのスペシャリスト エージェント 間で正しくルートすることを確認しましょう。 ```python from agents import Runner @@ -93,9 +93,9 @@ async def main(): print(result.final_output) ``` -## ガードレールの追加 +## ガードレールを追加する -入力または出力に対して実行するカスタムガードレールを定義できます。 +入力または出力に対して実行するカスタム ガードレール を定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてをまとめて実行 +## すべてを組み合わせる -ハンドオフと入力ガードレールを使用して、ワークフロー全体を実行してみましょう。 +ハンドオフと入力 ガードレール を使用して、すべてを組み合わせたワークフロー全体を実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの確認 +## トレースを確認する -エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してトレースを閲覧してください。 +エージェント 実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して実行トレースを表示してください。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう: +より複雑なエージェント フローの構築方法を学びましょう: -- [エージェントの設定方法](agents.md)について学ぶ -- [エージェントの実行](running_agents.md)について学ぶ -- [ツール](tools.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 d772a106f..40833e17b 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 のリアルタイム機能を使用して音声対応 AI エージェントを構築する方法を詳しく解説します。 !!! warning "Beta feature" -Realtime エージェントはベータ版です。今後の改善に伴い、破壊的変更が入る可能性があります。 +リアルタイム エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する対話フローを実現します。 OpenAI の Realtime API と永続的に接続を維持し、低レイテンシで自然な音声会話を行い、割り込みにも柔軟に対応できます。 +リアルタイム エージェントは、音声とテキスト入力をリアルタイムで処理し、リアルタイム音声で応答する会話フローを実現します。 OpenAI の Realtime API と永続的に接続することで、低レイテンシーかつ割り込みに強い自然な音声対話を提供します。 ## アーキテクチャ ### コアコンポーネント -リアルタイムシステムは以下の主要コンポーネントで構成されます。 +リアルタイム システムは次の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 -- **RealtimeRunner**: 設定を管理します。 `runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 1 回の対話セッション。ユーザーが会話を開始するたびに作成し、会話終了まで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース (通常は OpenAI の WebSocket 実装)。 +- **RealtimeAgent** : インストラクション、ツール、ハンドオフで構成された エージェント です。 +- **RealtimeRunner** : 設定を管理します。 `runner.run()` を呼び出して セッション を取得できます。 +- **RealtimeSession** : 1 つの対話セッションを表します。通常、 ユーザー が会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel** : 基盤となるモデル インターフェース (通常は OpenAI の WebSocket 実装) です。 ### セッションフロー -典型的なリアルタイムセッションは次のように進行します。 +典型的なリアルタイム セッションの流れは次のとおりです。 -1. **RealtimeAgent を作成**: instructions、tools、handoffs を設定します。 -2. **RealtimeRunner をセットアップ**: エージェントと設定オプションを渡します。 -3. **セッションを開始**: `await runner.run()` を実行し、 RealtimeSession を取得します。 -4. **音声またはテキストを送信**: `send_audio()` あるいは `send_message()` を使用します。 -5. **イベントを受信**: セッションをイテレートしてイベントを監視します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. **割り込みを処理**: ユーザーがエージェントの発話中に話し始めた場合、自動的に現在の音声生成を停止します。 +1. **RealtimeAgent** をインストラクション、ツール、ハンドオフ付きで作成します。 +2. その エージェント と設定オプションを使って **RealtimeRunner** をセットアップします。 +3. `await runner.run()` を呼び出して **セッションを開始** します。これにより RealtimeSession が返されます。 +4. `send_audio()` または `send_message()` を使用して **音声またはテキスト** をセッションへ送信します。 +5. セッションをイテレートして **イベントを受信** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーなどが含まれます。 +6. ユーザー が重ねて話した場合は **割り込み** を処理し、現在の音声生成を自動停止させます。 -セッションは会話履歴を保持し、リアルタイムモデルとの永続接続を管理します。 +セッションは会話履歴を保持し、リアルタイム モデルとの永続接続を管理します。 -## エージェント設定 +## エージェントの設定 -RealtimeAgent は通常の Agent クラスとほぼ同様ですが、いくつかの相違点があります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつか重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 -主な相違点: +主な違い: -- モデルの選択はエージェントではなくセッションで設定します。 -- structured outputs はサポートされません (`outputType` 非対応)。 -- 声色 (voice) はエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 -- tools、handoffs、instructions などその他の機能は同じように動作します。 +- モデルの選択は エージェント レベルではなくセッション レベルで設定します。 +- 適切な形式のデータ (structured outputs) はサポートされません (`outputType` は使用不可)。 +- 音声は エージェント 単位で設定できますが、最初の エージェント が話した後は変更できません。 +- ツール、ハンドオフ、インストラクションなどその他の機能は同じ方法で利用できます。 -## セッション設定 +## セッションの設定 ### モデル設定 -セッション設定では基盤となるリアルタイムモデルの挙動を制御できます。モデル名 (例: `gpt-4o-realtime-preview`) や音声 (alloy、echo、fable、onyx、nova、shimmer)、対応モダリティ (text / audio) を指定できます。入力・出力の音声フォーマットも設定でき、デフォルトは PCM16 です。 +セッション設定では基盤となるリアルタイム モデルの動作を制御できます。モデル名 (例: `gpt-4o-realtime-preview`)、音声 (alloy, echo, fable, onyx, nova, shimmer) の選択、対応モダリティ (テキスト / 音声) を指定できます。入力・出力ともに音声フォーマットを設定でき、デフォルトは PCM16 です。 -### 音声設定 +### オーディオ設定 -音声設定では音声入力と出力の扱いを制御します。 Whisper などのモデルを使用した音声文字起こし、言語設定、専門用語の認識精度を高めるための transcription prompts を設定できます。ターン検出では、音声活動検出の閾値、無音継続時間、検出された発話前後のパディングなどを調整できます。 +音声設定では、セッションが音声入出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、ドメイン固有用語の精度向上のための文字起こしプロンプトを指定できます。ターン検出では、音声活動検出のしきい値、無音時間、検出された音声前後のパディングなどを調整できます。 -## ツールと Functions +## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、リアルタイムエージェントは会話中に実行される function tools をサポートします。 +通常の エージェント と同様に、リアルタイム エージェントでも会話中に実行される 関数ツール をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフを使うと、会話を専門化されたエージェント間で引き継ぐことができます。 +ハンドオフにより、会話を専門化された エージェント 間で移譲できます。 ```python from agents.realtime import realtime_handoff @@ -119,40 +119,40 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーム配信します。セッションオブジェクトをイテレートしてイベントを受信してください。主なイベントは以下のとおりです。 +セッションはイベントを ストリーミング し、セッション オブジェクトをイテレートして受信できます。主なイベントは以下のとおりです。 -- **audio**: エージェントの応答からの raw 音声データ -- **audio_end**: エージェントの発話終了 -- **audio_interrupted**: ユーザーによる割り込み -- **tool_start/tool_end**: ツール実行の開始・終了 -- **handoff**: エージェントのハンドオフ発生 -- **error**: 処理中に発生したエラー +- **audio** : エージェント 応答の raw 音声データ +- **audio_end** : エージェント が話し終えたことを示します +- **audio_interrupted** : ユーザー による割り込み +- **tool_start/tool_end** : ツール実行の開始 / 終了 +- **handoff** : エージェント ハンドオフが発生 +- **error** : 処理中にエラーが発生 -完全なイベント仕様は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +完全なイベント一覧は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -リアルタイムエージェントでサポートされるガードレールは出力時のみです。パフォーマンス低下を防ぐためにデバウンス処理が行われ、毎単語ではなく一定間隔で評価されます。既定のデバウンス長は 100 文字ですが、変更可能です。 +リアルタイム エージェントでは出力ガードレールのみサポートされます。パフォーマンス低下を避けるためデバウンス処理が行われ、リアルタイム生成中に毎語ではなく定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定で変更可能です。 -ガードレールがトリガーされると `guardrail_tripped` イベントが発生し、エージェントの現在の応答を割り込むことがあります。テキストエージェントと異なり、リアルタイムエージェントではガードレール発動時に Exception は発生しません。 +ガードレールが発火すると `guardrail_tripped` イベントが生成され、 エージェント の現在の応答を割り込むことがあります。テキスト エージェント と異なり、リアルタイム エージェントではガードレール発火時に例外は送出されません。 -## 音声処理 +## オーディオ処理 -音声を送信するには [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio]、テキストを送信するには [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使って音声を、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使ってテキストを送信できます。 -音声出力を受信するには `audio` イベントを監視し、任意の音声ライブラリで再生してください。ユーザーが割り込んだ際には `audio_interrupted` イベントを検知して即座に再生を停止し、キューに残っている音声をクリアする必要があります。 +音声出力を扱うには `audio` イベントを受信して任意のオーディオ ライブラリで再生してください。 ユーザー が割り込んだ際には `audio_interrupted` イベントを検知し、再生を即座に停止してキューにある音声をクリアする必要があります。 -## 直接モデルアクセス +## モデルへの直接アクセス -低レベルの制御やカスタムリスナーを追加したい場合は、基盤モデルに直接アクセスできます。 +下位レベルの制御が必要な場合、基盤となるモデルにアクセスしてカスタム リスナーを追加したり高度な操作を実行できます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、高度なユースケース向けに [`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスでき、接続をより細かく制御できます。 -## 例 +## コード例 -動作する完全なコード例は、 UI あり / なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file +動作する完全な例については、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 UI コンポーネントあり・なしのデモが含まれています。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 8271023b1..692d18e17 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 エージェントとの音声会話を実現します。本ガイドでは、最初の Realtime 音声エージェントを作成する方法を説明します。 -!!! warning "Beta feature" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が入る可能性があります。 +!!! warning "ベータ版機能" +Realtime エージェントは現在ベータ版です。実装を改善する過程で破壊的変更が発生する可能性があります。 ## 前提条件 - Python 3.9 以上 - OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- OpenAI Agents SDK への基本的な理解 ## インストール -まだインストールしていない場合は、OpenAI Agents SDK をインストールします: +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## 最初の Realtime エージェントを作成する +## 最初の 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(): @@ -79,9 +79,9 @@ async def main(): asyncio.run(main()) ``` -## 完全な例 +## 完全なコード例 -以下は動作する完全な例です: +以下に完全に動作するコード例を示します: ```python import asyncio @@ -139,40 +139,40 @@ if __name__ == "__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`) +- `input_audio_format`: 入力オーディオのフォーマット（`pcm16`, `g711_ulaw`, `g711_alaw`） - `output_audio_format`: 出力オーディオのフォーマット - `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声アクティビティの閾値 (0.0-1.0) +- `type`: 検出方法（`server_vad`, `semantic_vad`） +- `threshold`: 音声活動のしきい値（0.0–1.0） - `silence_duration_ms`: ターン終了を検出する無音時間 - `prefix_padding_ms`: 発話前のオーディオパディング ## 次のステップ -- [Realtime エージェントについて詳しく学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーの動作するコード例を確認する -- エージェントに tools を追加する +- [Realtime エージェントについてさらに学ぶ](guide.md) +- [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 2dbcb4834..5acd129f3 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` 形式を用いた semantic versioning を若干修正したルールを採用しています。先頭の `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] に `run_context` と `agent` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承しているクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` の 2 つの新しいパラメーターが追加されました。`MCPServer` を継承するクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index f8866b16e..2765fe092 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` はループでユーザー入力を促し、ターン間の会話履歴を保持します。 -デフォルトでは、生成され次第モデル出力をストリーミングします。 -ループを終了するには `quit` または `exit` と入力するか、（ Ctrl-D ）を押してください。 \ No newline at end of file +`run_demo_loop` はループ内でユーザー入力を受け付け、ターン間で会話履歴を保持します。 +デフォルトでは、生成されたモデル出力をストリーミング表示します。 +ループを終了するには `quit` または `exit` と入力するか、 Ctrl-D を押してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index 47b6660db..1638d0f9e 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 結果 -`Runner.run` メソッドを呼び出すと、戻り値は次のいずれかになります。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返されます。 -- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] -- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult] — `run` または `run_sync` を呼び出した場合 +- [`RunResultStreaming`][agents.result.RunResultStreaming] — `run_streamed` を呼び出した場合 -これらはどちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、有用な情報のほとんどはここに含まれます。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行された エージェント の最終出力が入ります。内容は次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が入ります。内容は次のいずれかです。 -- 最後の エージェント に `output_type` が定義されていない場合は `str` -- エージェント に `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト +- `str` 型 — 最後のエージェントに `output_type` が設定されていない場合 +- `last_agent.output_type` 型のオブジェクト — エージェントに `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` を保存しておけば、次に ユーザー がメッセージを送ったときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されます。アプリケーションによっては、次回ユーザーが入力した際にこれを再利用すると便利です。たとえば、一次受付のエージェントが言語別エージェントへハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にメッセージを送った際に再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] でラップされています。RunItem は LLM が生成した raw アイテムを包むものです。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが入ります。アイテムは [`RunItem`][agents.items.RunItem] でラップされており、 raw アイテムは 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 アイテムは生成された推論です。 +- [`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 9ff76d641..343e231c0 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,14 @@ 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 +26,55 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) をご覧ください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の run メソッドを使用すると、開始エージェントと入力を渡します。入力は文字列 (ユーザー メッセージと見なされます) か、OpenAI Responses API のアイテムである input item のリストのいずれかです。 +`Runner` の run メソッドを使用する際は、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。 -ランナーは次のループを実行します: +Runner は次のループを実行します。 -1. 現在のエージェントに対し、現在の入力で LLM を呼び出します。 +1. 現在のエージェントに対して現在の入力を用い、LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 + 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらを実行し結果を追加してループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し結果を追加して、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM 出力が「final output」と見なされるルールは、所定の型のテキスト出力でツール呼び出しが含まれていない場合です。 + LLM 出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、ツール呼び出しが存在しない場合です。 ## ストリーミング -ストリーミングを使用すると、LLM 実行中のストリーミング イベントを受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行の完全な情報 (生成されたすべての新しい出力を含む) が格納されます。`.stream_events()` を呼び出してストリーミング イベントを取得できます。詳細は [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングを使用すると、LLM 実行中のストリーミング イベントを受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行に関する完全な情報（新しく生成されたすべての出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミング イベントを取得できます。詳細は [ストリーミング ガイド](streaming.md) を参照してください。 -## Run 設定 +## 実行設定 -`run_config` パラメーターでは、エージェント実行の全体設定を行えます: +`run_config` パラメーターでは、エージェント実行のグローバル設定を指定できます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、使用するグローバル LLM モデルを指定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデル プロバイダー。デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバル `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力／出力ガードレールのリスト。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに個別のフィルターがない場合に適用されるグローバル入力フィルター。新しいエージェントに渡す入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] を参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化します。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入力／出力など、機微なデータをトレースに含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレースに使用するワークフロー名、トレース ID、グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は複数実行にまたがるトレースをリンクする際に使用できます。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 +- [`model`][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` を設定することを推奨します。`group_id` は任意で、複数の実行間でトレースを関連付ける際に使用します。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに付与するメタデータです。 -## 会話／チャットスレッド +## 会話 / チャットスレッド -いずれの run メソッドを呼び出しても、1 つ以上のエージェント (したがって 1 つ以上の LLM 呼び出し) が実行されますが、チャット会話上は 1 つの論理ターンを表します。例: +いずれかの run メソッド呼び出しにより、1 つ以上のエージェントが実行され（つまり 1 回以上の LLM 呼び出しが行われ）ますが、チャット会話における 1 つの論理ターンとして扱われます。例: 1. ユーザーターン: ユーザーがテキストを入力 -2. Runner 実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフ。2 つ目のエージェントがさらにツールを実行し、最終出力を生成。 +2. Runner 実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ。2 番目のエージェントがさらにツールを実行し、出力を生成。 -エージェント実行の最後に、ユーザーへ何を表示するかを選択できます。たとえば、エージェントが生成したすべての新しいアイテムを表示するか、最終出力のみを表示するかを選べます。いずれにしても、ユーザーがフォローアップ質問をする場合は再度 run メソッドを呼び出します。 +エージェント実行の終了時に、ユーザーへ何を表示するかを選択できます。たとえば、エージェントが生成したすべての新規アイテムを表示するか、最終出力のみを表示するかを決められます。いずれの場合でも、ユーザーが追質問を行ったら、再度 run メソッドを呼び出せます。 -### 手動での会話管理 +### 会話の手動管理 -[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して、次ターンの入力を取得し、会話履歴を手動で管理できます: +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して次ターンの入力を取得し、会話履歴を手動で管理できます。 ```python async def main(): @@ -91,9 +94,9 @@ async def main(): # California ``` -### Sessions による自動会話管理 +### Sessions での自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動管理できます: +より簡単な方法として、[Sessions](sessions.md) を利用すると `.to_input_list()` を手動で呼び出さずに会話履歴を自動管理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -116,20 +119,20 @@ async def main(): # California ``` -Sessions は自動で以下を行います: +Sessions は以下を自動で行います。 -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- 異なる session ID ごとに個別の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新規メッセージを保存 +- 異なるセッション ID ごとに個別の会話を維持 -詳細は [Sessions ドキュメント](sessions.md) を参照してください。 +詳細は [Sessions のドキュメント](sessions.md) を参照してください。 ## 例外 -SDK は特定の状況で例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです: +SDK は特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException] — SDK で送出されるすべての例外の基底クラス。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] — 実行が `max_turns` を超えた場合に送出されます。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError] — モデルが無効な出力 (例: 形成不良の JSON や存在しないツールの使用) を生成した場合に送出されます。 -- [`UserError`][agents.exceptions.UserError] — SDK の使用方法に誤りがある場合に送出されます。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] — [ガードレール](guardrails.md) がトリップした際に送出されます。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラス。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 実行が run メソッドに渡した `max_turns` を超えた場合に送出。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: モデルが不正な出力（壊れた JSON や存在しないツールの使用など）を生成した場合に送出。 +- [`UserError`][agents.exceptions.UserError]: SDK を使用する際に開発者が誤った使い方をした場合に送出。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: [ガードレール](guardrails.md) が発動した場合に送出。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 4fcab6fac..c88f840af 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()` を手動で扱う必要がありません。 -Sessions は特定のセッションの会話履歴を保存し、明示的なメモリ管理を行わなくてもエージェントがコンテキストを保持できるようにします。チャットアプリケーションや、エージェントに過去のやり取りを覚えさせたいマルチターン対話を構築する際に特に便利です。 +セッションは特定のセッションごとに会話履歴を保存し、明示的にメモリを管理しなくてもエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に便利です。 ## クイックスタート @@ -49,11 +49,11 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリを有効にすると、以下のように動作します。 +セッションメモリを有効にすると、次のように動作します。 -1. **各実行前**: Runner はそのセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）がすべて自動的にセッションへ保存されます。 -3. **コンテキスト保持**: 同じセッションでの後続の実行には、完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 +1. **実行前**: Runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）はすべて、自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションで次回以降の実行を行うと、完全な会話履歴が入力に含まれるため、エージェントはコンテキストを維持できます。 これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 @@ -61,7 +61,7 @@ print(result.final_output) # "Approximately 39 million" ### 基本操作 -Sessions では、会話履歴を管理するためのさまざまな操作がサポートされています。 +セッションは会話履歴を管理するためのいくつかの操作をサポートしています。 ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 修正のための pop_item の使用 +### pop_item を使った修正 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり、修正したりしたい場合に特に役立ちます。 +`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に特に便利です。 ```python from agents import Agent, Runner, SQLiteSession @@ -230,15 +230,15 @@ Use meaningful session IDs that help you organize conversations: ### Session management ```python -# 会話をリセットしたい場合はセッションをクリア +# Clear a session when conversation should start fresh await session.clear_session() -# 異なるエージェントが同じセッションを共有可能 +# Different agents can share the same session support_agent = Agent(name="Support") billing_agent = Agent(name="Billing") session = SQLiteSession("user_123") -# 両方のエージェントが同じ会話履歴を参照 +# Both agents will see the same conversation history result1 = await Runner.run( support_agent, "Help me with my account", @@ -261,19 +261,19 @@ from agents import Agent, Runner, SQLiteSession async def main(): - # エージェントを作成 + # Create an agent agent = Agent( name="Assistant", instructions="Reply very concisely.", ) - # 複数回の実行で保持されるセッションインスタンスを作成 + # Create a session instance that will persist across runs session = SQLiteSession("conversation_123", "conversation_history.db") print("=== Sessions Example ===") print("The agent will remember previous messages automatically.\n") - # 1 ターン目 + # First turn print("First turn:") print("User: What city is the Golden Gate Bridge in?") result = await Runner.run( @@ -284,7 +284,7 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # 2 ターン目 - エージェントは前回の会話を覚えています + # Second turn - the agent will remember the previous conversation print("Second turn:") print("User: What state is it in?") result = await Runner.run( @@ -295,7 +295,7 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # 3 ターン目 - 会話を継続 + # Third turn - continuing the conversation print("Third turn:") print("User: What's the population of that state?") result = await Runner.run( diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 2728efd57..2f29e0135 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、エージェント実行の進行に合わせてアップデートを購読できます。これにより、エンドユーザーへ進捗状況や途中経過のレスポンスを表示するのに役立ちます。 +ストリーミングを利用すると、エージェント実行の進行に合わせて更新を購読できます。これにより、 エンドユーザー に進捗状況や部分的なレスポンスを表示するのに役立ちます。 -ストリーミングを行うには、 `Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。さらに `result.stream_events()` を呼び出すと、後述する `StreamEvent` オブジェクトの非同期ストリームを取得できます。 +ストリーミングを行うには、 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 -## raw レスポンスイベント +## Raw response イベント -`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 と data が含まれます。生成されたメッセージを即座に ユーザー にストリーミングしたい場合に便利です。 -例えば、次のコードは LLM が生成したテキストをトークンごとに出力します。 +たとえば、以下のコードは LLM が生成するテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 実行アイテムイベントとエージェントイベント +## Run item イベント と エージェント イベント -`RunItemStreamEvent` は、より高レベルのイベントです。アイテムが完全に生成されたときに通知を受け取れます。これにより、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗を伝えられます。同様に、 `AgentUpdatedStreamEvent` はハンドオフの結果などで現在のエージェントが変更された際にアップデートを提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] はより高レベルのイベントで、アイテムが完全に生成されたタイミングを通知します。これにより、各トークンではなく「メッセージ生成完了」「ツール実行完了」などのレベルで進捗を ユーザー に送信できます。同様に、 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] はハンドオフの結果などで現在のエージェントが変更された際に通知を行います。 -例えば、次のコードは raw イベントを無視し、ユーザーにアップデートのみをストリーミングします。 +たとえば、以下のコードは raw イベントを無視し、 ユーザー へ更新のみをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index d5d7d99e4..0c7425dfa 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,20 +4,20 @@ search: --- # ツール -ツールは エージェント にアクションを実行させます。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにコンピュータの利用などです。 Agents SDK には 3 種類のツールクラスがあります。 +ツールを利用することで エージェント は、データの取得、コードの実行、外部 API の呼び出し、さらには コンピュータ操作 までも行えます。 Agents SDK には 3 種類のツールがあります： -- ホスト済みツール: これらは AI モデルと同じ LLM サーバー上で実行されます。 OpenAI はリトリーバル、 Web 検索、コンピュータ操作をホスト済みツールとして提供しています。 -- Function calling: 任意の Python 関数をツールとして使用できます。 -- エージェントをツールとして利用: エージェント をツールとして扱い、ハンドオフせずに他の エージェント を呼び出せます。 +- ホスト型ツール: これらは LLM サーバー上で AI モデルと並行して実行されます。OpenAI は retrieval、 Web 検索、 コンピュータ操作 をホスト型ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして利用できます。 +- エージェントをツールとして使用: これにより、ハンドオフせずに エージェント 同士を呼び出すことができます。 -## ホスト済みツール +## ホスト型ツール - OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際、いくつかの組み込みツールを提供しています。 +[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際、OpenAI にはいくつかの組み込みツールがあります: -- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web 検索 を実行させます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI Vector Stores から情報を取得します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web 検索 を行わせます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストア から情報を取得します。 - [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は サンドボックス環境でコードを実行します。 - [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 - [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## Function tools +## 関数ツール -任意の Python 関数をツールとして使用できます。 Agents SDK が自動的に設定を行います。 +任意の Python 関数をツールとして利用できます。 Agents SDK が自動的に設定を行います: -- ツール名は Python 関数名になります (または任意で指定可能)。 -- ツールの説明は関数の docstring から取得されます (または任意で指定可能)。 -- 関数入力のスキーマは関数の引数から自動生成されます。 -- 各入力の説明は、無効化しない限り docstring から取得されます。 +- ツール名には Python 関数名が使用されます（または自分で指定可能） +- ツールの説明は関数の docstring から取得されます（または自分で指定可能） +- 関数入力のスキーマは関数の引数から自動生成されます +- 各入力の説明は docstring から取得されます（無効化も可能） -Python の `inspect` モジュールで関数シグネチャを抽出し、 docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ生成には `pydantic` を使用しています。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを生成しています。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、同期関数・非同期関数のどちらでも構いません。 -2. docstring が存在する場合、説明および引数の説明を取得します。 -3. 関数はオプションで `context` (最初の引数) を受け取れます。またツール名や説明、 docstring スタイルなどのオーバーライドも可能です。 -4. デコレートした関数をツールのリストに渡すだけで利用できます。 +1. 関数は同期・非同期のどちらでも良く、引数には任意の Python 型を使用できます。 +2. docstring があれば、ツール説明や引数説明を取得します。 +3. 関数は任意で `context`（先頭の引数）を受け取れます。ツール名や説明、docstring スタイルなどをオーバーライドすることもできます。 +4. デコレートした関数をツールのリストに渡してください。 -??? note "Expand to see output" +??? note "出力を確認するには展開" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### カスタム function ツール +### カスタム関数ツール -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 文字列) を受け取り、ツール出力を文字列で返す非同期関数 +- `params_json_schema`（引数の JSON スキーマ） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数 JSON 文字列を受け取り、文字列としてツールの出力を返す async 関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを自動解析してツールのスキーマを生成し、 docstring を解析してツールおよび各引数の説明を抽出します。ポイントは次のとおりです。 +前述のとおり、関数シグネチャを自動解析してツールのスキーマを生成し、docstring からツール説明や各引数の説明を抽出します。ポイントは以下の通りです: -1. シグネチャ解析は `inspect` モジュールを使用します。型アノテーションで引数の型を把握し、動的に Pydantic モデルを構築して全体のスキーマを表現します。 Python プリミティブ型、 Pydantic モデル、 TypedDict などほとんどの型をサポートします。 -2. `griffe` で docstring を解析します。サポートフォーマットは `google`、`sphinx`、`numpy` です。フォーマットは自動検出を試みますがベストエフォートのため、 `function_tool` 呼び出し時に明示的に指定できます。`use_docstring_info` を `False` にすると docstring 解析を無効化できます。 +1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を把握し、動的に Pydantic モデルを作成します。Python の基本型、Pydantic モデル、TypedDict など大半の型をサポートします。 +2. `griffe` で docstring を解析します。対応フォーマットは `google`, `sphinx`, `numpy` です。フォーマットは自動検出を試みますが、`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 @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### 出力のカスタム抽出 -場合によっては、ツール化した エージェント の出力を中央 エージェント に返す前に加工したいことがあります。たとえば次のようなケースです。 +場合によっては、ツール エージェント の出力を中央 エージェント に返す前に加工したいことがあります。たとえば、以下のようなケースです: -- サブエージェントのチャット履歴から特定の情報 (例: JSON ペイロード) を抽出したい。 -- エージェントの最終回答を変換・再フォーマットしたい (例: Markdown をプレーンテキストや CSV に変換)。 -- 出力を検証し、エージェントの応答が欠落または不正な場合にフォールバック値を提供したい。 +- サブ エージェント のチャット履歴から特定の情報（例: JSON ペイロード）だけを抽出する。 +- エージェント の最終回答を変換・再フォーマットする（例: Markdown をプレーンテキストや CSV に変換）。 +- エージェント の応答が欠落している、または不正な場合に検証やフォールバック値を提供する。 -その場合は `as_tool` メソッドに `custom_output_extractor` 引数を渡してください。 +その場合は `as_tool` メソッドに `custom_output_extractor` 引数を渡してください: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -315,12 +315,12 @@ json_tool = data_agent.as_tool( ) ``` -## function ツールでのエラー処理 +## 関数ツールでのエラー処理 -`@function_tool` で function ツールを作成する際、`failure_error_function` を渡せます。これはツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを返す関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡すことができます。これはツール呼び出しがクラッシュしたときに LLM にエラーレスポンスを返す関数です。 -- 既定では (何も渡さない場合)、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 -- 独自のエラー関数を渡すと、その関数が実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡すとツール呼び出しのエラーが再スローされます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーのコードがクラッシュした場合は `UserError` などが発生し得ます。 +- 何も渡さない場合は既定の `default_tool_error_function` が実行され、LLM にエラーが発生したことを知らせます。 +- 独自のエラーファンクションを渡すと、それが実行され、LLM にそのレスポンスが送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しエラーは再スローされます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、自分のコードがクラッシュした場合は `UserError` などになります。 -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 内でエラー処理を行う必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index b72393258..c42dd6efe 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,11 +4,11 @@ search: --- # トレーシング - Agents SDK にはビルトインのトレーシング機能が含まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントまでを包括的に記録します。 [Traces ダッシュボード](https://platform.openai.com/traces) を使うことで、開発中や本番環境でワークフローをデバッグ・可視化・モニタリングできます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生する LLM 生成、tool 呼び出し、handoffs、guardrail、カスタムイベントなどの包括的な記録を収集します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時および本番環境でワークフローをデバッグ・可視化・監視できます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。 + Tracing はデフォルトで有効になっています。無効化する方法は 2 つあります。 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する 2. 単一の実行で無効化する場合は [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する @@ -17,39 +17,39 @@ search: ## トレースとスパン -- **トレース** は 1 つの「ワークフロー」のエンドツーエンドの操作を表し、複数のスパンで構成されます。主なプロパティは以下のとおりです。 - - `workflow_name` : 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 - - `trace_id` : トレース固有の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id` : 省略可能なグループ ID。複数のトレースを同じ会話にひも付ける際に使用します。たとえばチャットスレッド ID など。 - - `disabled` : `True` の場合、このトレースは記録されません。 - - `metadata` : トレースに付随するメタデータ (任意)。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。主なプロパティは以下のとおりです。 - - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを表す `trace_id` +- **トレース (Trace)** は 1 回のワークフローのエンドツーエンドの操作を表します。トレースは複数のスパンで構成され、以下のプロパティを持ちます。 + - `workflow_name`: 論理的なワークフローまたはアプリ名。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意 ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` でなければなりません。 + - `group_id`: 会話内の複数トレースを関連付ける任意のグループ ID。たとえばチャットスレッド ID など。 + - `disabled`: True の場合、このトレースは記録されません。 + - `metadata`: トレースに付与する任意のメタデータ。 +- **スパン (Span)** は開始時刻と終了時刻を持つ操作を表します。スパンは以下を持ちます。 + - `started_at` と `ended_at` タイムスタンプ + - 所属するトレースを示す `trace_id` - 親スパンを指す `parent_id` (存在する場合) - - スパンに関する情報を持つ `span_data` 。例: `AgentSpanData` はエージェント情報、 `GenerationSpanData` は LLM 生成情報など。 + - スパン情報を保持する `span_data`。例として `AgentSpanData` はエージェント情報を、`GenerationSpanData` は LLM 生成情報を保持します。 ## デフォルトのトレーシング -デフォルトでは SDK が以下をトレースします。 +デフォルトでは SDK が次をトレースします。 -- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ -- エージェント実行ごとに `agent_span()` でラップ -- LLM 生成を `generation_span()` でラップ -- 関数ツール呼び出しを `function_span()` でラップ -- ガードレールを `guardrail_span()` でラップ -- ハンドオフを `handoff_span()` でラップ -- 音声入力 (speech-to-text) を `transcription_span()` でラップ -- 音声出力 (text-to-speech) を `speech_span()` でラップ -- 関連する音声スパンは `speech_group_span()` の下にまとめられる場合があります +- `Runner.{run, run_sync, run_streamed}()` 全体を `trace()` でラップ +- エージェント実行ごとに `agent_span()` でラップ +- LLM 生成を `generation_span()` でラップ +- function tool 呼び出しを `function_span()` でラップ +- guardrail を `guardrail_span()` でラップ +- handoffs を `handoff_span()` でラップ +- 音声入力 (speech-to-text) を `transcription_span()` でラップ +- 音声出力 (text-to-speech) を `speech_span()` でラップ +- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります -デフォルトではトレース名は「Agent workflow」です。 `trace` を使用してこの名前を設定することも、 [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 +デフォルトのトレース名は "Agent workflow" です。`trace` を使用して名前を設定するか、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定できます。 -さらに、 [カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、トレースを別の宛先へ送信（置換または追加）することも可能です。 +さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定し、別の送信先へトレースをプッシュすることも可能です (置換または追加先として)。 ## 上位レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースに含めたい場合は、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -64,52 +64,50 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `with trace()` で 2 回の `Runner.run` 呼び出しをラップしているため、個別にトレースを作成せず、全体が 1 つのトレースになります。 +1. `Runner.run` への 2 回の呼び出しが `with trace()` に包まれているため、個別のトレースを作成せず 1 つのトレース内に含まれます。 ## トレースの作成 -[`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()` は function 呼び出しの入出力を保存します。機微データを含む可能性があるため、[`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] を設定して音声データの記録を無効化できます。 +同様に、Audio スパンはデフォルトで入出力音声の 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] - デフォルトのプロセッサを置き換えて独自のトレースプロセッサを設定します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を用いて **追加** のトレースプロセッサを登録します。これにより OpenAI バックエンドへの送信に加えて独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を用いて既定のプロセッサを **置換** します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含めてください。 ## 外部トレースプロセッサ一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 70b970012..462c2fdb4 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,13 +2,13 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェント可視化を使用すると、 ** Graphviz ** を用いてエージェントとその関係を構造的に図示できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化を利用すると、 **Graphviz** を使ってエージェントとそれらの関係を構造化したグラフィカル表現として生成できます。これにより、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用しているかを理解しやすくなります。 ## インストール -オプションの `viz` 依存グループをインストールします: +オプションの `viz` 依存関係グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -16,11 +16,11 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は、有向グラフを作成し、次のように表現します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックス。 -- **ツール** は緑色の楕円。 -- **ハンドオフ** は一方のエージェントから別のエージェントへの有向エッジ。 +- **エージェント** は黄色いボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへ向かう有向エッジとして表されます。 ### 使用例 @@ -54,32 +54,31 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、 ** triage agent ** の構造とサブエージェントおよびツールへの接続を視覚的に表現したグラフが生成されます。 - +これにより、 **triage agent** の構造とサブエージェントおよびツールとの接続を視覚的に表したグラフが生成されます。 ## 可視化の理解 -生成されたグラフには次の要素が含まれます: +生成されたグラフには次が含まれます: -- エントリーポイントを示す **スタートノード** (`__start__`)。 +- エントリポイントを示す **start node** (`__start__`)。 - 黄色で塗りつぶされた **長方形** で表されるエージェント。 - 緑色で塗りつぶされた **楕円** で表されるツール。 - 相互作用を示す有向エッジ: - - エージェント間のハンドオフを示す **実線矢印**。 - - ツール呼び出しを示す **点線矢印**。 -- 実行が終了する場所を示す **エンドノード** (`__end__`)。 + - エージェント間のハンドオフには **実線の矢印**。 + - ツール呼び出しには **点線の矢印**。 +- 実行が終了する場所を示す **end node** (`__end__`)。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。別ウィンドウで表示するには、次のように記述します: +既定では `draw_graph` はグラフをインラインで表示します。別ウィンドウでグラフを表示するには次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します: +既定では `draw_graph` はグラフをインラインで表示します。ファイルとして保存するにはファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 2d3fd60c1..4884bf3c7 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,34 +34,34 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際、次の項目を設定できます。 +パイプラインを作成する際には、以下を設定できます。 1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] 新しい音声が文字起こしされるたびに実行されるコードです。 -2. [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] の各モデル +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル 3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - これにより以下のような設定が可能です。 - - モデルプロバイダー：モデル名をモデルにマッピングします - - トレーシング：トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など - - TTS と STT モデルの設定：プロンプト、言語、使用するデータ型 など + 次のような項目を設定できます。 + - モデルプロバイダー：モデル名をモデルにマッピングします + - トレーシング：トレーシングの有効 / 無効、音声ファイルのアップロード有無、ワークフロー名、トレース ID など + - TTS・STT モデルの設定：プロンプト、言語、データタイプなど ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行します。音声入力は次の 2 つの形式を渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は 2 つの形式で渡せます。 1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声ファイルがあり、その文字起こし結果だけからレスポンスを生成したい場合に使用します。話者が話し終わるタイミングを検知する必要がない、録音済み音声やプッシュ・トゥー・トークアプリなどで便利です。 + 完全な音声が既にあり、その文字起こしに対して結果を生成したい場合に使用します。例えば、事前録音音声やプッシュトゥトークで発話終了が明確なアプリで便利です。 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] エラーイベントです。 @@ -83,4 +83,8 @@ 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 b7e959b5a..187c1dbaa 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK のベース [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。次に、 SDK からオプションの音声依存関係をインストールします。 +OpenAI Agents SDK の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。その後、SDK から音声用のオプション依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -覚えておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、 3 段階のプロセスです。 +押さえておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、次の 3 段階で構成されます。 -1. 音声をテキストへ変換する speech-to-text モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。 -3. 結果テキストを音声へ戻す text-to-speech モデルを実行します。 +1. Speech-to-Text モデルで音声をテキストに変換する +2. 通常はエージェント的なワークフローであるコードを実行して結果を生成する +3. Text-to-Speech モデルで結果のテキストを音声に変換する ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まずはエージェントをいくつか設定しましょう。この SDK でエージェントを構築したことがあれば、見覚えがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず、エージェントをいくつか設定します。本 SDK でエージェントを構築した経験があれば、見覚えのある手順です。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```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) の code examples を確認してください。 \ 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 8a3e808a8..47e85d15e 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントのトレーシング方法](../tracing.md) と同様に、 voice パイプラインも自動的にトレーシングされます。 +[エージェントのトレーシング](../tracing.md) と同様に、voice パイプラインも自動でトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントをご覧いただけますが、パイプラインのトレーシングは [`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]: トレースに音声の書き起こしなどの機微データを含めるかどうかを制御します。これは特に voice パイプライン向けで、ユーザーの Workflow 内で行われる処理には影響しません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースの Workflow 名です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースをリンクさせるための `group_id` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに追加するメタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: オーディオの書き起こしなど、機微なデータをトレースに含めるかどうかを制御します。これは voice パイプライン専用で、Workflow 内部で行われる処理には影響しません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: オーディオ データをトレースに含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース workflow の名前です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` で、複数のトレースをリンクできます。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加メタデータです。 \ No newline at end of file