From 72bd289f6046393895c6380c854a7d7004872e4d Mon Sep 17 00:00:00 2001 From: Rohan Mehta Date: Thu, 17 Jul 2025 14:46:02 -0400 Subject: [PATCH 01/10] [realtime] Add direct access to model layer from session (#1172) --- docs/realtime/guide.md | 11 +++++++++++ src/agents/realtime/session.py | 5 +++++ uv.lock | 2 +- 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/realtime/guide.md b/docs/realtime/guide.md index 9ea2525cf..cefa5d688 100644 --- a/docs/realtime/guide.md +++ b/docs/realtime/guide.md @@ -138,6 +138,17 @@ Send audio to the session using [`session.send_audio(audio_bytes)`][agents.realt For audio output, listen for `audio` events and play the audio data through your preferred audio library. Make sure to listen for `audio_interrupted` events to stop playback immediately and clear any queued audio when the user interrupts the agent. +## Direct model access + +You can access the underlying model to add custom listeners or perform advanced operations: + +```python +# Add a custom listener to the model +session.model.add_listener(my_custom_listener) +``` + +This gives you direct access to the [`RealtimeModel`][agents.realtime.model.RealtimeModel] interface for advanced use cases where you need lower-level control over the connection. + ## Examples For complete working examples, check out the [examples/realtime directory](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) which includes demos with and without UI components. diff --git a/src/agents/realtime/session.py b/src/agents/realtime/session.py index 83e56d5fc..82ff924b8 100644 --- a/src/agents/realtime/session.py +++ b/src/agents/realtime/session.py @@ -107,6 +107,11 @@ def __init__( self._guardrail_tasks: set[asyncio.Task[Any]] = set() + @property + def model(self) -> RealtimeModel: + """Access the underlying model for adding listeners or other direct interaction.""" + return self._model + async def __aenter__(self) -> RealtimeSession: """Start the session by connecting to the model. After this, you will be able to stream events from the model and send messages and audio to the model. diff --git a/uv.lock b/uv.lock index 2e14dd804..bcd61fe4a 100644 --- a/uv.lock +++ b/uv.lock @@ -1482,7 +1482,7 @@ wheels = [ [[package]] name = "openai-agents" -version = "0.2.1" +version = "0.2.2" source = { editable = "." } dependencies = [ { name = "griffe" }, From fdbc618b2cb8833fb1df66d739f3ac19779ab3f1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 18 Jul 2025 07:20:04 +0900 Subject: [PATCH 02/10] Update all translated document pages (#1173) Automated update of translated documentation Co-authored-by: github-actions[bot] --- docs/ja/agents.md | 43 ++--- docs/ja/config.md | 30 ++-- docs/ja/context.md | 46 ++--- docs/ja/examples.md | 34 ++-- docs/ja/guardrails.md | 40 ++--- docs/ja/handoffs.md | 36 ++-- docs/ja/index.md | 34 ++-- docs/ja/mcp.md | 157 ++++++++++++++-- docs/ja/models/index.md | 79 ++++----- docs/ja/models/litellm.md | 20 +-- docs/ja/multi_agent.md | 44 ++--- docs/ja/quickstart.md | 30 ++-- docs/ja/realtime/guide.md | 158 +++++++++++++++++ docs/ja/realtime/quickstart.md | 179 +++++++++++++++++++ docs/ja/release.md | 32 ++++ docs/ja/repl.md | 7 +- docs/ja/results.md | 36 ++-- docs/ja/running_agents.md | 111 ++++++++---- docs/ja/sessions.md | 315 +++++++++++++++++++++++++++++++++ docs/ja/streaming.md | 14 +- docs/ja/tools.md | 113 +++++++----- docs/ja/tracing.md | 132 +++++++------- docs/ja/visualization.md | 36 ++-- docs/ja/voice/pipeline.md | 36 ++-- docs/ja/voice/quickstart.md | 18 +- docs/ja/voice/tracing.md | 18 +- 26 files changed, 1332 insertions(+), 466 deletions(-) create mode 100644 docs/ja/realtime/guide.md create mode 100644 docs/ja/realtime/quickstart.md create mode 100644 docs/ja/release.md create mode 100644 docs/ja/sessions.md diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 828b36355..c7c65fd75 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,15 +4,16 @@ search: --- # エージェント -エージェントはアプリの主要な構成ブロックです。エージェントは、大規模言語モデル ( LLM ) に instructions と tools を設定したものです。 +エージェントは、アプリにおける中核の構成要素です。エージェントとは、 instructions と tools で設定された大規模言語モデル（ LLM ）です。 ## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +エージェントで最もよく設定するプロパティは次のとおりです。 +- `name`: エージェントを識別する必須の文字列。 - `instructions`: 開発者メッセージまたは system prompt とも呼ばれます。 -- `model`: 使用する LLM と、temperature や top_p などのモデル調整パラメーターを指定する任意の `model_settings`。 -- `tools`: エージェントがタスクを達成するために利用できるツール。 +- `model`: 使用する LLM と、 temperature や top_p などのモデル調整パラメーターを指定する省略可能な `model_settings`。 +- `tools`: エージェントがタスクを遂行するために利用できるツールの一覧。 ```python from agents import Agent, ModelSettings, function_tool @@ -31,7 +32,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型について汎用的です。コンテキストは依存性注入の手段で、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。 +エージェントは汎用的に `context` 型を取ります。コンテキストは依存性インジェクション用ツールであり、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。 ```python @dataclass @@ -49,7 +50,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型で出力させたい場合は `output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを利用しますが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型であれば何でも対応します。たとえば dataclass、list、TypedDict などです。 +既定では、エージェントはプレーンテキスト（つまり `str` ）を出力します。エージェントに特定の型の出力を生成させたい場合は、 `output_type` パラメーターを使用します。よく使われるのは [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型 ― dataclass、リスト、TypedDict など ― であれば何でもサポートしています。 ```python from pydantic import BaseModel @@ -70,11 +71,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡しておくと、エージェントは必要に応じてそれらに処理を委譲できます。これにより、単一のタスクに特化したモジュール式エージェントを編成できる強力なパターンが実現します。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すと、関連性がある場合にエージェントがそれらへ委任できます。これは、単一タスクに特化したモジュール型エージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -95,7 +96,7 @@ triage_agent = Agent( ## 動的 instructions -通常はエージェント作成時に instructions を指定しますが、関数を介して動的に instructions を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数と `async` 関数の両方に対応しています。 +多くの場合、エージェント作成時に instructions を指定できますが、関数を介して動的に渡すことも可能です。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数も `async` 関数も使用できます。 ```python def dynamic_instructions( @@ -110,17 +111,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( @@ -137,15 +138,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 にツール使用を必須化します ( ただし使用するツールは自動選択 )。 -3. `none` — LLM にツールを使用しないことを要求します。 -4. 特定の文字列 ( 例: `my_tool` ) — その特定のツールを LLM に使用させます。 +1. `auto` : LLM がツールを使用するかどうかを判断します。 +2. `required` : LLM にツール使用を必須にします（ただし使用するツールは自動選択）。 +3. `none` : LLM にツールを使用しないことを必須にします。 +4. 文字列（例 `my_tool` ）を指定すると、その特定のツールを必ず使用させます。 !!! 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"`] を設定してください。これにより、ツールの出力を LL M の追加処理なしにそのまま最終応答として返します。 \ No newline at end of file + ツール呼び出し後にエージェントを完全に停止させたい場合（自動モードを続行しない）、 [`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 bf76b9fb6..80a7e656e 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -4,9 +4,9 @@ search: --- # SDK の設定 -## API キーとクライアント +## API keys と clients -デフォルトでは、 SDK はインポートされた時点で LLM リクエストとトレーシングに使用する `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にこの環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を利用してキーを設定できます。 +デフォルトでは、 SDK はインポートされた時点で LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を参照します。アプリが起動する前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを構成することも可能です。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用してください。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -さらに、使用する OpenAI API をカスタマイズすることもできます。既定では OpenAI Responses API を利用します。これを Chat Completions API に変更するには、 [set_default_openai_api()][agents.set_default_openai_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 @@ -32,9 +32,9 @@ from agents import set_default_openai_api set_default_openai_api("chat_completions") ``` -## トレーシング +## Tracing -トレーシングはデフォルトで有効になっています。前述の OpenAI API キー（環境変数または設定したデフォルトキー）が自動的に使用されます。トレーシングで使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。デフォルトでは前述の OpenAI API キー（環境変数、またはあなたが設定したデフォルトキー）が使用されます。トレーシングで使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化するには、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を呼び出します。 +トレーシングを完全に無効化したい場合は、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグログ +## Debug logging - SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `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 ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることも可能です。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログに含まれる機微情報 +### ログ内の機密データ -特定のログには機微情報（たとえば ユーザー データ）が含まれる場合があります。この情報が記録されるのを防ぎたい場合は、次の環境変数を設定してください。 +一部のログには機密データ（例: ユーザー データ）が含まれる場合があります。これらのデータをログに残さないようにするには、次の環境変数を設定してください。 -LLM の入力および出力のログを無効にする: +LLM の入力および出力のログを無効化する場合: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力および出力のログを無効にする: +ツールの入力および出力のログを無効化する場合: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 72c0938cf..43285a4b2 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,29 @@ 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 オブジェクトを使用します。 -2. そのオブジェクトを各種 run メソッド（例: `Runner.run(..., **context=whatever** )`）に渡します。 -3. すべてのツール呼び出しやライフサイクルフックには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使うパターンが多いです。 +2. そのオブジェクトを各種 run メソッド (例: `Runner.run(..., **context=whatever**)`) に渡します。 +3. すべてのツール呼び出しやライフサイクルフックでは、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。`T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -**最重要ポイント**: あるエージェントの実行において、エージェント・ツール関数・ライフサイクルフックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 +**最も重要な点**: 1 回のエージェント実行において、エージェント・ツール関数・ライフサイクルフックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 -コンテキストでは次のような用途が考えられます。 +コンテキストは次のような用途に利用できます: -- 実行に関するデータ（例: ユーザー名 / uid やその他のユーザー情報） -- 依存オブジェクト（例: ロガー、データフェッチャーなど） -- ヘルパー関数 +- 実行のためのコンテキストデータ (例: ユーザー名や UID など ユーザー に関する情報) +- 依存関係 (例: ロガーオブジェクトやデータフェッチャーなど) +- ヘルパー関数 !!! danger "Note" - - コンテキストオブジェクトは LLM には送信されません。あくまでローカルのオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは **LLM には送信されません**。あくまでローカルオブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -42,7 +41,8 @@ class UserInfo: # (1)! @function_tool async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str: # (2)! - return f"User {wrapper.context.name} is 47 years old" + """Fetch the age of the user. Call this function to get user's age information.""" + return f"The user {wrapper.context.name} is 47 years old" async def main(): user_info = UserInfo(name="John", uid=123) @@ -65,17 +65,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使用できます。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、どのような型でも構いません。 2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. エージェントにジェネリック `UserInfo` を付与することで、型チェッカーが誤りを検出できます（たとえば別のコンテキスト型を受け取るツールを渡した場合など）。 +3. ジェネリック型 `UserInfo` をエージェントに指定することで、型チェッカーが誤り (異なるコンテキスト型を取るツールを渡すなど) を検出できます。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM コンテキスト +## エージェント／LLM コンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴に含まれるものだけです。したがって、新しいデータを LLM に渡したい場合は、そのデータを履歴に含める形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できる **唯一** のデータは会話履歴だけです。したがって、新しいデータを LLM に与えたい場合は、そのデータを履歴に含める方法を取る必要があります。主な方法は次のとおりです: -1. Agent の `instructions` に追加する。いわゆる「system prompt」や「developer message」と呼ばれるものです。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的な関数でも構いません。ユーザー名や現在の日付など、常に有用な情報を渡す際によく使われます。 -2. `Runner.run` 呼び出し時の `input` に追加する。`instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位レイヤーにメッセージを配置できます。 -3. 関数ツール経由で公開する。オンデマンドで取得するコンテキストに適しており、LLM が必要に応じてツールを呼び出してデータを取得します。 -4. retrieval や web search を使う。これらは特別なツールで、ファイルやデータベースから関連データを取得する（retrieval）、もしくは Web から取得する（web search）ことができます。レスポンスを関連コンテキストで「グラウンディング」するのに有効です。 \ No newline at end of file +1. Agent の `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。`instructions` は静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。常に役立つ情報 (例: ユーザー名や現在の日付) を渡す一般的な手法です。 +2. `Runner.run` を呼び出す際に `input` に追加する。この方法は `instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できる点が異なります。 +3. 関数ツールを通じて公開する。これは _オンデマンド_ コンテキストに適しており、LLM が必要になったタイミングでツールを呼び出してデータを取得できます。 +4. Retrieval や Web 検索を使用する。これらはファイルやデータベースから関連データを取得する (retrieval) または Web から取得する (Web 検索) 特殊なツールです。関連するコンテキストデータで回答をグラウンディングするのに有効です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 00f634ec1..be118b0fa 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,42 +4,42 @@ search: --- # コード例 -リポジトリの [examples セクション](https://github.com/openai/openai-agents-python/tree/main/examples) には、 SDK のさまざまなサンプル実装が用意されています。これらの例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +リポジトリの [examples セクション](https://github.com/openai/openai-agents-python/tree/main/examples) では、SDK のさまざまなサンプル実装をご覧いただけます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例では、一般的なエージェント設計パターンを紹介しています。 - + このカテゴリーでは、以下のような一般的なエージェント設計パターンを示します。 - 決定論的ワークフロー - - ツールとしてのエージェント + - エージェントをツールとして利用 - エージェントの並列実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - SDK の基礎的な機能を示す例です。 - - - 動的なシステムプロンプト + SDK の基礎的な機能を紹介します。 + - 動的な system prompt - ストリーミング出力 - ライフサイクルイベント - **[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 で利用する方法を探ります。 +- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK で利用する方法を紹介します。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフを実践的に示す例です。 + エージェントのハンドオフの実践例をご覧いただけます。 - **[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 つの例です。 - - - **customer_service**: 航空会社向けカスタマーサービスシステムの例 - - **research_bot**: シンプルなディープリサーチクローン + 実際のアプリケーションを想定した、より完成度の高い 2 つの例です。 + - **customer_service**: 航空会社向けカスタマーサービスシステムの例。 + - **research_bot**: シンプルなディープリサーチ クローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを用いた音声エージェントの例をご覧ください。 \ No newline at end of file + TTS と STT モデルを用いた音声エージェントの例をご覧いただけます。 + +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK を使用してリアルタイム体験を構築する方法を示す例です。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index b67bb8bad..1858914a7 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは エージェント と _並行して_ 実行され、ユーザー入力のチェックとバリデーションを行えます。例えば、とても賢い（つまり遅く/高価な）モデルを使用してカスタマーリクエストを処理するエージェントがあるとします。悪意のある ユーザー がモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、速く/安価なモデルで動くガードレールを実行できます。ガードレールが悪意のある利用を検知すると、直ちにエラーを送出して高価なモデルの実行を停止し、時間とコストを節約できます。 +ガードレールはエージェントと _並列で_ 実行され、ユーザー入力のチェックとバリデーションを行います。たとえば、非常に賢い（そのため遅くて高コストな）モデルを使ってカスタマーリクエストを処理するエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、低コストかつ高速なモデルでガードレールを実行できます。もしガードレールが悪意ある使用を検知した場合、直ちにエラーを発生させることで高コストなモデルの実行を停止し、時間と費用を節約できます。 -ガードレールには 2 種類あります: +ガードレールには 2 種類あります。 -1. 入力ガードレール は初期 ユーザー 入力に対して実行されます -2. 出力ガードレール は最終的なエージェント出力に対して実行されます +1. Input ガードレールは最初のユーザー入力で実行されます +2. Output ガードレールは最終的なエージェント出力で実行されます ## 入力ガードレール -入力ガードレールは 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] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。 +3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの応答や例外処理を適切に行えます。 !!! Note - 入力ガードレールは ユーザー 入力に対して実行されることを意図しているため、ガードレールは *最初* のエージェントでのみ実行されます。「なぜ `guardrails` プロパティがエージェントにあり、`Runner.run` に渡さないのか」と疑問に思うかもしれません。これは、ガードレールが実際の エージェント と密接に関連していることが多いからです。異なるエージェントには異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントが *最初の* エージェントである場合にのみ実行されます。「guardrails」プロパティがエージェントにあるのに、なぜ `Runner.run` に渡さないのか疑問に思うかもしれません。これはガードレールが実際の Agent と密接に関連していることが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置いておくと可読性が向上するためです。 ## 出力ガードレール -出力ガードレールは 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] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。 +3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるため、ユーザーへの応答や例外処理を適切に行えます。 !!! Note - 出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、ガードレールは *最後* のエージェントでのみ実行されます。入力ガードレールの場合と同様、ガードレールが実際の エージェント と密接に関連していることが多いため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、エージェントが *最後の* エージェントである場合にのみ実行されます。入力ガードレールと同様、ガードレールは実際の Agent と密接に関連しているため、エージェントごとに異なるガードレールを実行することになり、コードを同じ場所に置いておくと可読性が向上します。 -## トリップワイヤー +## トリップワイヤ -入力または出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤーでそれを示すことができます。トリップワイヤーがトリガーされたガードレールを検知した時点で、直ちに `{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. こちらがワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. これは実際のエージェントの出力型です。 -2. これはガードレールの出力型です。 -3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file +1. こちらが実際のエージェントの出力型です。 +2. こちらがガードレールの出力型です。 +3. こちらがエージェントの出力を受け取り、結果を返すガードレール関数です。 +4. こちらがワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index c0e99556e..afde32dcb 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 からはツールとして表現されます。したがって `Refund Agent` という名前の エージェント へのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 すべての エージェント には [`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()` によるデフォルトのツール説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが発生した時点でデータ取得を開始する、といった用途に便利です。この関数は エージェント コンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで想定される入力の型（任意）。 +- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は後述します。 ```python from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフ入力 +## ハンドオフの入力 -場合によっては、 LLM がハンドオフを呼び出す際に追加のデータを渡してほしいことがあります。たとえば「Escalation エージェント」へのハンドオフでは、ログ用に理由を渡してもらいたいかもしれません。 +場合によっては、 LLM にハンドオフ呼び出し時にいくつかのデータを渡してほしいことがあります。たとえば「Escalation agent」へのハンドオフでは、その理由を一緒に受け取りログに残したい、というケースです。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を閲覧できる状態になります。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定してください。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] として渡される既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を見ることができます。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定します。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は [`agents.extensions.handoff_filters`][] に実装済みです。 +よくあるパターン（たとえば履歴からすべてのツール呼び出しを取り除くなど）は [`agents.extensions.handoff_filters`][] に実装されています。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. これにより `FAQ agent` が呼ばれた際に、履歴からすべてのツール呼び出しが自動で削除されます。 +1. これにより `FAQ agent` が呼び出された際、履歴からすべてのツールが自動的に削除されます。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるよう、エージェント にハンドオフに関する情報を含めることを推奨します。事前に用意したプレフィックス [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] を利用するか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨情報を自動で追加できます。 +LLM がハンドオフを正しく理解できるように、 エージェント にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスが用意されているほか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨データを自動で追加することもできます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 39692a166..93b0c3340 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,29 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化をほとんど排した軽量で使いやすいパッケージにより、エージェントベースの AI アプリを構築できるようにします。これは、以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) をプロダクションレベルへとアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 + OpenAI Agents SDK は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント指向の AI アプリを構築できます。これは、エージェントに関する以前の試験的プロジェクトである Swarm をプロダクションレベルにアップグレードしたものです。 Agents SDK には、ごく少数の基本コンポーネントがあります: -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: エージェントが特定タスクを他のエージェントへ委任するしくみ -- **ガードレール**: エージェントへの入力を検証する機能 +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できます +- **ガードレール**: エージェントへの入力を検証できます +- **セッション**: エージェント実行間で会話履歴を自動的に保持します -Python と組み合わせることで、これらのコンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実際のアプリケーションを構築できます。さらに SDK には、エージェントフローを可視化・デバッグできる **トレーシング** が標準搭載されており、評価やファインチューニングにも活用可能です。 + Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えながら実用的なアプリケーションを構築できます。さらに、SDK には組み込みの トレーシング があり、エージェントフローの可視化やデバッグ、評価、さらにはアプリ向けモデルのファインチューニングまで行えます。 -## Agents SDK を使用する理由 +## Agents SDK を使う理由 SDK には 2 つの設計原則があります。 -1. 使う価値のある十分な機能を備えつつ、学習が早いようコンポーネント数を絞る。 -2. すぐに使い始められる初期設定で動作しつつ、挙動を細かくカスタマイズできる。 +1. 使う価値があるだけの機能を備えつつ、学習が容易になるよう基本コンポーネントは少なく。 +2. すぐに使い始められる一方で、動作を細部までカスタマイズ可能に。 主な機能は次のとおりです。 -- エージェントループ: ツール呼び出し、結果を LLM に送信、LLM が完了するまでのループを自動で処理。 -- Python ファースト: 新しい抽象化を学ばずに、言語標準機能でエージェントをオーケストレーション。 -- ハンドオフ: 複数エージェント間の協調と委譲を実現する強力な機能。 -- ガードレール: エージェントと並列で入力バリデーションを実行し、失敗時に早期終了。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic での検証を提供。 -- トレーシング: フローの可視化・デバッグ・モニタリングに加え、OpenAI の評価・ファインチューニング・蒸留ツールを利用可能。 +- エージェントループ: ツール呼び出し、結果を LLM へ送信、 LLM が完了するまでループ処理を自動で行います。 +- Python ファースト: 新しい抽象概念を学ばずに、言語本来の機能でエージェントをオーケストレーションしチェーン化できます。 +- ハンドオフ: 複数エージェント間での調整と委譲を実現する強力な機能です。 +- ガードレール: エージェントと並行して入力バリデーションやチェックを行い、失敗時には早期終了します。 +- セッション: エージェント実行間の会話履歴を自動で管理し、手動での状態管理を排除します。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic による検証を提供します。 +- トレーシング: フローの可視化・デバッグ・モニタリングが可能で、 OpenAI の評価、ファインチューニング、蒸留ツールとも連携します。 ## インストール @@ -34,7 +36,7 @@ SDK には 2 つの設計原則があります。 pip install openai-agents ``` -## Hello World の例 +## Hello World 例 ```python from agents import Agent, Runner @@ -49,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 1e394a5e6..33f6b08c3 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 is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. -Agents SDK は MCP をサポートしており、これにより幅広い MCP サーバーをエージェントにツールとして追加できます。 + Agents SDK は MCP をサポートしています。これにより、さまざまな MCP サーバーを使用してエージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、MCP 仕様では使用するトランスポート方式に基づき 3 種類のサーバーが定義されています。 +現在、 MCP 仕様では利用するトランスポートメカニズムに基づき、3 種類のサーバーを定義しています: -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動かすイメージです。 -2. **HTTP over SSE** サーバー: リモートで動作し、 URL 経由で接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様に定義された Streamable HTTP トランスポートを使用してリモートで動作します。 +1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動いていると考えてください。 +2. **HTTP over SSE** サーバー: リモートで実行され、URL を介して接続します。 +3. **Streamable HTTP** サーバー: MCP 仕様で定義されている Streamable HTTP トランスポートを使用してリモートで実行されます。 -これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使用して接続できます。 +これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスで接続できます。 -たとえば、[公式 MCP filesystem サーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)を利用する場合は次のようになります。 +たとえば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -31,9 +31,9 @@ async with MCPServerStdio( "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], } ) as server: - # 注意：実際には通常は MCP サーバーをエージェントに追加し、 - # フレームワークがツール一覧の取得を自動的に処理するようにします。 - # list_tools() への直接呼び出しには run_context と agent パラメータが必要です。 + # Note: In practice, you typically add the server to an Agent + # and let the framework handle tool listing automatically. + # Direct calls to list_tools() require run_context and agent parameters. run_context = RunContextWrapper(context=None) agent = Agent(name="test", instructions="test") tools = await server.list_tools(run_context, agent) @@ -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()` を呼び出し、 MCP サーバーのツールを LLM に認識させます。 LLM が MCP サーバーのツールを呼び出すと、SDK はそのサーバーの `call_tool()` を実行します。 ```python @@ -52,21 +52,140 @@ agent=Agent( ) ``` +## ツールのフィルタリング + + MCP サーバーにツールフィルターを設定して、エージェントで利用可能なツールを制限できます。 SDK は静的および動的フィルタリングの両方をサポートしています。 + +### 静的なツールフィルタリング + +単純な許可 / ブロックリストの場合は、静的フィルタリングを利用できます: + +```python +from agents.mcp import create_static_tool_filter + +# Only expose specific tools from this server +server = MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + }, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"] + ) +) + +# Exclude specific tools from this server +server = MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + }, + tool_filter=create_static_tool_filter( + blocked_tool_names=["delete_file"] + ) +) + +``` + +**`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` だけになります。 + +### 動的なツールフィルタリング + +より複雑なフィルタリングロジックには、関数を用いた動的フィルターを利用できます: + +```python +from agents.mcp import ToolFilterContext + +# Simple synchronous filter +def custom_filter(context: ToolFilterContext, tool) -> bool: + """Example of a custom tool filter.""" + # Filter logic based on tool name patterns + return tool.name.startswith("allowed_prefix") + +# Context-aware filter +def context_aware_filter(context: ToolFilterContext, tool) -> bool: + """Filter tools based on context information.""" + # Access agent information + agent_name = context.agent.name + + # Access server information + server_name = context.server_name + + # Implement your custom filtering logic here + return some_filtering_logic(agent_name, server_name, tool) + +# Asynchronous filter +async def async_filter(context: ToolFilterContext, tool) -> bool: + """Example of an asynchronous filter.""" + # Perform async operations if needed + result = await some_async_check(context, tool) + return result + +server = MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + }, + tool_filter=custom_filter # or context_aware_filter or async_filter +) +``` + +`ToolFilterContext` では以下へアクセスできます: +- `run_context`: 現在の実行コンテキスト +- `agent`: ツールを要求しているエージェント +- `server_name`: MCP サーバー名 + +## プロンプト + + MCP サーバーはプロンプトも提供でき、パラメーター付きで動的にエージェントの instructions を生成できます。これにより再利用可能なインストラクションテンプレートを作成し、パラメーターでカスタマイズできます。 + +### プロンプトの使用 + +プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します: + +- `list_prompts()`: サーバー上の利用可能なプロンプトを列挙します +- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得します + +```python +# List available prompts +prompts_result = await server.list_prompts() +for prompt in prompts_result.prompts: + print(f"Prompt: {prompt.name} - {prompt.description}") + +# Get a specific prompt with parameters +prompt_result = await server.get_prompt( + "generate_code_review_instructions", + {"focus": "security vulnerabilities", "language": "python"} +) +instructions = prompt_result.messages[0].content.text + +# Use the prompt-generated instructions with an Agent +agent = Agent( + name="Code Reviewer", + instructions=instructions, # Instructions from MCP prompt + mcp_servers=[server] +) +``` + ## キャッシュ -エージェントが実行されるたびに、MCP サーバーへ `list_tools()` が呼び出されます。サーバーがリモートの場合は特にレイテンシが発生します。ツール一覧を自動でキャッシュしたい場合は、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の各クラスに `cache_tools_list=True` を渡してください。ツール一覧が変更されないと確信できる場合のみ使用してください。 +エージェントが実行されるたびに、 MCP サーバーの `list_tools()` が呼ばれます。サーバーがリモートの場合、これはレイテンシの原因になります。ツール一覧を自動でキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないことが確実な場合のみ使用してください。 -キャッシュを無効化したい場合は、サーバーで `invalidate_tools_cache()` を呼び出します。 +キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 ## エンドツーエンドのコード例 -完全な動作例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 ## トレーシング -[トレーシング](./tracing.md) は MCP の操作を自動的にキャプチャします。具体的には次の内容が含まれます。 +[トレーシング](./tracing.md) は以下を含む MCP 操作を自動的にキャプチャします: -1. ツール一覧取得のための MCP サーバー呼び出し -2. 関数呼び出しに関する MCP 情報 +1. ツール一覧取得のための MCP サーバーへの呼び出し +2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 410c01676..b2fcd1525 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK は OpenAI モデルを 2 つの形態で即利用できます。 + Agents SDK には、OpenAI モデルをすぐに利用できる 2 つの形態が用意されています: -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい [Responses API](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`] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 +- [`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", ...) @@ -26,30 +26,29 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 非 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) にあります。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] - `Runner.run` レベルでカスタムモデルプロバイダーを指定できます。これにより「この run のすべてのエージェントでカスタムプロバイダーを使う」と宣言できます。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) にあります。 -3. [`Agent.model`][agents.agent.Agent.model] - 特定のエージェントインスタンスにモデルを指定できます。エージェントごとに異なるプロバイダーを組み合わせることが可能です。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) にあります。ほとんどのモデルを簡単に利用する方法として [LiteLLM インテグレーション](./litellm.md) を利用できます。 +1. [`set_default_openai_client`] は、`AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケースに適しています。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 +2. [`ModelProvider`] は `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`] では、特定のエージェントインスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定可能な例は [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 - これらの例では、Responses API をまだサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 + + これらの例では、ほとんどの LLM プロバイダーが Responses API をまだサポートしていないため、Chat Completions API/モデルを使用しています。ご使用の LLM プロバイダーが Responses API をサポートしている場合は、Responses を使うことをおすすめします。 ## モデルの組み合わせ -1 つのワークフロー内でエージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小さく高速なモデルを、複雑なタスクには大きく高性能なモデルを使用するといったケースです。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法でモデルを選択できます。 + 1 つのワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小型で高速なモデルを使用し、複雑なタスクには大型で高性能なモデルを使う、といった形です。[`Agent`] を設定する際、次のいずれかで特定のモデルを選択できます: -1. モデル名を直接指定する -2. 任意のモデル名と、その名前を Model インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を指定する -3. [`Model`][agents.models.interface.Model] 実装を直接渡す +1. モデル名を直接渡す。 +2. 任意のモデル名と、それをモデルインスタンスにマッピングできる [`ModelProvider`] を渡す。 +3. [`Model`] 実装を直接提供する。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両形態をサポートしていますが、各ワークフローで 1 つのモデル形態に統一することを推奨します。2 つの形態はサポートする機能とツールが異なるためです。混在させる場合は、使用する機能が双方で利用可能かを必ず確認してください。 + + SDK は [`OpenAIResponsesModel`] と [`OpenAIChatCompletionsModel`] の両方の形態をサポートしていますが、ワークフローごとに単一のモデル形態を使用することを推奨します。両モデル形態は利用できる機能やツールのセットが異なるためです。ワークフローでモデル形態を混在させる必要がある場合は、使用するすべての機能が両形態で利用可能かをご確認ください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -82,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接設定 -2. [`Model`][agents.models.interface.Model] 実装を提供 +1. OpenAI のモデル名を直接設定します。 +2. [`Model`] 実装を提供します。 -エージェントで使用するモデルをさらに構成したい場合は、`temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 + エージェントで使用するモデルをさらに詳細に設定したい場合は、`temperature` などのオプションパラメーターを含む [`ModelSettings`] を渡すことができます。 ```python from agents import Agent, ModelSettings @@ -98,7 +97,7 @@ english_agent = Agent( ) ``` -OpenAI の Responses API を使用する場合、`user` や `service_tier` など[その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、`extra_args` で渡してください。 + また、OpenAI の Responses API を使用する際には、`user` や `service_tier` など、[その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで利用できない場合は、`extra_args` を使って渡してください。 ```python from agents import Agent, ModelSettings @@ -116,27 +115,25 @@ english_agent = Agent( ## 他の LLM プロバイダー使用時の一般的な問題 -### Tracing クライアントの 401 エラー +### Tracing クライアント エラー 401 -Tracing 関連のエラーが発生する場合、トレースは OpenAI サーバーへアップロードされるため、OpenAI API キーが必要です。対応方法は次の 3 つです。 + トレーシングに関連したエラーが発生する場合、トレースが OpenAI サーバーにアップロードされるため、OpenAI API キーが設定されていないことが原因です。解決方法は次の 3 つです: -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. トレース用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key] - この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) で取得したものが必要です。 -3. OpenAI 以外のトレースプロセッサーを使用する。詳細は [tracing のドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`] +2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`] + この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) から取得したものである必要があります。 +3. 非 OpenAI のトレースプロセッサーを使用する。詳細は [tracing docs](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、ほとんどの LLM プロバイダーはまだ非対応です。その結果、404 などのエラーが発生することがあります。対処方法は次の 2 つです。 + 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")`] を呼び出す。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`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 +141,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部プロバイダーの制限で、JSON 出力自体はサポートしていても `json_schema` を指定できないことが原因です。修正に向けて取り組んでいますが、JSON スキーマ出力をサポートしているプロバイダーを使用することをお勧めします。そうでないと、不正な JSON が返されてアプリが頻繁に壊れる可能性があります。 + これは一部のプロバイダーの制限によるもので、JSON 出力には対応していても、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON スキーマ出力をサポートしているプロバイダーを利用することを推奨します。さもないと、アプリが不正な JSON により頻繁に失敗するおそれがあります。 -## プロバイダーを跨いだモデルの組み合わせ +## プロバイダー間でのモデルの組み合わせ -モデルプロバイダーごとの機能差に注意しないと、エラーが発生します。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型の file search や web search をサポートしていますが、多くの他プロバイダーは非対応です。以下の制限に留意してください。 + モデルプロバイダーごとの機能差に注意しないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search や web search をサポートしていますが、多くの他プロバイダーはこれらをサポートしていません。次の制限に注意してください: -- 対応していないプロバイダーには未サポートの `tools` を送らない -- テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしていないプロバイダーでは、不正な JSON が返ることがある点に注意する \ No newline at end of file +- サポートしていない `tools` を理解しないプロバイダーには送信しない +- テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する +- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがある点に注意 \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 651d7a51b..c51bc0eab 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM 経由でのモデル利用 +# LiteLLM を通じた任意モデルの利用 !!! note - LiteLLM との統合は現在ベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題を見つけた場合は、[GitHub Issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応いたします。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題を見つけた場合は、[GitHub issues](https://github.com/openai/openai-agents-python/issues) に報告してください。迅速に対応いたします。 -[LiteLLM](https://docs.litellm.ai/docs/) は、1 つのインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK では LiteLLM との統合により、任意の AI モデルを使用できます。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK では 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` をモデル名に、OpenAI API キーを入力 -- `anthropic/claude-3-5-sonnet-20240620` をモデル名に、Anthropic API キーを入力 -- その他 +- `openai/gpt-4.1` をモデルとして指定し、OpenAI API キーを入力 +- `anthropic/claude-3-5-sonnet-20240620` をモデルとして指定し、Anthropic API キーを入力 +- など -LiteLLM でサポートされているモデルの全リストは、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM でサポートされているモデルの一覧は、[litellm 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 a179fed36..45d62c2b2 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内でエージェントがどのように流れるかを指します。どのエージェントが、どの順序で実行され、その後どう決定するかを制御します。エージェントをオーケストレーションする主な方法は次の 2 つです。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを実行するか、実行順序、そして次に何を行うかをどのように決定するかということです。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に判断させる: LLM の知能を活用し、計画・推論を行い、その結果に基づいて次のステップを決定します。 -2. コードでオーケストレーションする: コード側でエージェントの流れを定義します。 +1. LLM に意思決定を任せる: これは LLM の知能を活用して計画・推論を行い、その結果に基づいて次のステップを決定させる方法です。 +2. コードによるオーケストレーション: コードでエージェントの流れを制御する方法です。 -これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使用できます。それぞれにメリットとデメリットがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、 instructions、ツール、ハンドオフを備えた LLM です。オープンエンドなタスクが与えられた場合、 LLM はタスクをどのように進めるかを自律的に計画し、ツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントへタスクを委譲できます。たとえば、リサーチエージェントには次のようなツールを装備できます。 +エージェントとは、 instructions、 tools、 handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM はツールを使ってアクションを実行しデータを取得し、 handoffs でサブエージェントにタスクを委任しながら、自律的にタスクをこなす計画を立てられます。たとえば、リサーチエージェントには次のようなツールを装備できます。 -- Web 検索でオンライン情報を取得する -- ファイル検索で独自データや接続を調べる -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画立案やレポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索によりオンライン情報を取得 +- ファイル検索と取得による社内データや接続先の検索 +- コンピュータ操作でコンピュータ上のアクションを実行 +- コード実行でデータ分析を実施 +- 計画立案やレポート作成などに優れた専門エージェントへの handoffs -このパターンはタスクがオープンエンドで、 LLM の知能に頼りたい場合に最適です。重要な戦術は次のとおりです。 +このパターンはタスクがオープンエンドで、 LLM の知能に依存したい場合に最適です。重要な戦略は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、使い方、守るべきパラメーターを明確に示します。 -2. アプリを監視し、改善を繰り返す。問題が起きた箇所を特定し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえばループで実行し自己批評させたり、エラーメッセージを渡して修正させたりします。 -4. 何でもこなす汎用エージェントより、特定タスクに特化したエージェントを用意します。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスク性能を向上できます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、および動作パラメーターを明確に記述します。 +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) を使って、コードで検査可能な適切な形式のデータを生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに応じて次のエージェントを選択する。 +- 複数エージェントを連鎖させ、一方の出力を次の入力に変換する。ブログ記事執筆タスクをリサーチ → アウトライン作成 → 記事執筆 → クリティーク → 改善という一連のステップに分解するなど。 +- タスクを実行するエージェントを `while` ループで動かし、その出力を評価しフィードバックを返すエージェントと組み合わせ、評価者が基準を満たしたと判断するまで繰り返す。 +- `asyncio.gather` のような Python の基本コンポーネントを使って複数エージェントを並列実行する。互いに依存しない複数タスクを高速に処理したい場合に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には多数のコード例があります。 \ No newline at end of file +`examples/agent_patterns` ディレクトリーに複数のコード例があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 30c3219d7..77cced861 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ行えば十分です。 +一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -14,9 +14,9 @@ cd my_project python -m venv .venv ``` -### 仮想環境の有効化 +### 仮想環境のアクティブ化 -新しいターミナルセッションを開始するたびに実行してください。 +新しいターミナル セッションを開始するたびに実行してください。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions 、名前、`model_config` などのオプション設定で定義します。 +エージェントは instructions、名前、そして `model_config` などのオプション設定で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## さらにエージェントを追加 +## エージェントを追加 -追加のエージェントも同様の方法で定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを決定するための追加コンテキストを提供します。 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各エージェントに対して、タスクを進める際に選択できるハンドオフ先の一覧を定義できます。 +各エージェントでは、タスクを進める方法を決定する際に選択できるハンドオフの選択肢（インベントリ）を定義できます。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## エージェントオーケストレーションの実行 -ワークフローが実行され、トリアージエージェントが 2 つの専門エージェント間で正しくルーティングすることを確認しましょう。 +ワークフローが実行され、トリアージ エージェントが 2 つのスペシャリスト エージェント間で正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -95,7 +95,7 @@ async def main(): ## ガードレールの追加 -入力または出力に対して実行されるカスタムガードレールを定義できます。 +入力または出力に対して実行するカスタム ガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -120,9 +120,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## すべてをまとめる +## すべてを組み合わせる -ハンドオフと入力ガードレールを組み合わせて、ワークフロー全体を実行してみましょう。 +これらをすべて組み合わせ、ハンドオフと入力ガードレールを利用してワークフロー全体を実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -182,12 +182,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェントの実行内容を確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してトレースを閲覧してください。 +エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動し、実行トレースを表示します。 ## 次のステップ -より複雑なエージェントフローの構築方法を学びましょう。 +より複雑なエージェント フローの構築方法を学びましょう。 -- [エージェント](agents.md) の設定方法を学ぶ。 +- [Agents](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 new file mode 100644 index 000000000..20fd588fe --- /dev/null +++ b/docs/ja/realtime/guide.md @@ -0,0 +1,158 @@ +--- +search: + exclude: true +--- +# ガイド + +このガイドでは、OpenAI Agents SDK の realtime 機能を使って音声対応の AI エージェントを構築する方法を詳しく解説します。 + +!!! warning "ベータ機能" +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 + +## 概要 + +Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する会話フローを実現します。OpenAI の Realtime API と永続的に接続を保ち、低レイテンシで自然な音声対話を可能にし、割り込みにもスムーズに対応します。 + +## アーキテクチャ + +### 主要コンポーネント + +realtime システムは、以下の主要コンポーネントで構成されています。 + +- **RealtimeAgent**: instructions、tools、handoffs で設定されるエージェント。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッション。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装）。 + +### セッションフロー + +典型的な realtime セッションは次のように進行します。 + +1. **RealtimeAgent** を instructions、tools、handoffs で作成します。 +2. **RealtimeRunner** をエージェントと設定オプションでセットアップします。 +3. `await runner.run()` で **セッションを開始** し、RealtimeSession を受け取ります。 +4. `send_audio()` または `send_message()` で **音声またはテキスト** をセッションへ送信します。 +5. セッションを反復処理して **イベントを受信** します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどが含まれます。 +6. ユーザーがエージェントの発話を **割り込んだ場合**、現在の音声生成が自動で停止します。 + +セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 + +## エージェント設定 + +RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつか重要な違いがあります。API の詳細は [`RealtimeAgent`](agents.realtime.agent.RealtimeAgent) リファレンスをご覧ください。 + +主な違い: + +- モデルの選択はエージェントではなくセッションで設定します。 +- structured outputs（`outputType`）はサポートされません。 +- 声質はエージェントごとに設定できますが、最初のエージェントが発話した後に変更できません。 +- tools、handoffs、instructions などの他の機能は同じ方法で利用できます。 + +## セッション設定 + +### モデル設定 + +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、声質（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text と/または audio）を指定可能です。音声フォーマットは入力と出力で設定でき、デフォルトは PCM16 です。 + +### 音声設定 + +音声設定では、音声入力と出力の扱いを制御します。Whisper などのモデルで入力音声を文字起こししたり、言語を指定したり、専門用語の精度向上のため transcription プロンプトを提供したりできます。ターン検出では、音声検出閾値、無音時間、検出された音声の前後パディングなどを調整して、エージェントがいつ応答を開始・停止すべきかを制御します。 + +## Tools と Functions + +### ツールの追加 + +通常のエージェントと同様に、realtime エージェントも会話中に実行される function tools をサポートします。 + +```python +from agents import function_tool + +@function_tool +def get_weather(city: str) -> str: + """Get current weather for a city.""" + # Your weather API logic here + return f"The weather in {city} is sunny, 72°F" + +@function_tool +def book_appointment(date: str, time: str, service: str) -> str: + """Book an appointment.""" + # Your booking logic here + return f"Appointment booked for {service} on {date} at {time}" + +agent = RealtimeAgent( + name="Assistant", + instructions="You can help with weather and appointments.", + tools=[get_weather, book_appointment], +) +``` + +## ハンドオフ + +### ハンドオフの作成 + +ハンドオフを使うことで、会話を専門エージェント間で引き継げます。 + +```python +from agents.realtime import realtime_handoff + +# Specialized agents +billing_agent = RealtimeAgent( + name="Billing Support", + instructions="You specialize in billing and payment issues.", +) + +technical_agent = RealtimeAgent( + name="Technical Support", + instructions="You handle technical troubleshooting.", +) + +# Main agent with handoffs +main_agent = RealtimeAgent( + name="Customer Service", + instructions="You are the main customer service agent. Hand off to specialists when needed.", + handoffs=[ + realtime_handoff(billing_agent, tool_description="Transfer to billing support"), + realtime_handoff(technical_agent, tool_description="Transfer to technical support"), + ] +) +``` + +## イベント処理 + +セッションはイベントをストリーム配信します。セッションオブジェクトを反復処理してイベントを受信してください。主なイベントは次のとおりです。 + +- **audio**: エージェントの応答音声データ +- **audio_end**: エージェントの発話終了 +- **audio_interrupted**: ユーザーによる割り込み +- **tool_start/tool_end**: tool 実行の開始と終了 +- **handoff**: エージェント間の handoff +- **error**: 処理中に発生したエラー + +詳細は [`RealtimeSessionEvent`](agents.realtime.events.RealtimeSessionEvent) を参照してください。 + +## ガードレール + +Realtime エージェントでは出力ガードレールのみサポートされます。パフォーマンス低下を防ぐため、ガードレールはデバウンスされ、（1 文字ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 + +ガードレールが発火すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答が中断されることがあります。テキストエージェントと違い、Realtime エージェントではガードレール発火時に Exception は発生しません。 + +## 音声処理 + +[`session.send_audio(audio_bytes)`](agents.realtime.session.RealtimeSession.send_audio) で音声を、[`session.send_message()`](agents.realtime.session.RealtimeSession.send_message) でテキストを送信できます。 + +音声出力を扱う際は `audio` イベントを受信し、任意の音声ライブラリで再生してください。ユーザーが割り込んだ場合は `audio_interrupted` イベントを検知して、即座に再生を停止し、キューにある音声をクリアする必要があります。 + +## 直接モデルアクセス + +基盤モデルにアクセスして、カスタムリスナーを追加したり高度な操作を行ったりできます。 + +```python +# Add a custom listener to the model +session.model.add_listener(my_custom_listener) +``` + +これにより、低レベルで接続を制御したい高度なユースケース向けに [`RealtimeModel`](agents.realtime.model.RealtimeModel) インターフェースへ直接アクセスできます。 + +## コード例 + +完全な動作例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。UI あり・なしのデモを含みます。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md new file mode 100644 index 000000000..7146c4020 --- /dev/null +++ b/docs/ja/realtime/quickstart.md @@ -0,0 +1,179 @@ +--- +search: + exclude: true +--- +# クイックスタート + +Realtime エージェントを使用すると、OpenAI の Realtime API を介して AI エージェントと音声で対話できます。本ガイドでは、最初の Realtime 音声エージェントを作成する方法を説明します。 + +!!! warning "ベータ機能" +Realtime エージェントは現在ベータ版です。今後の改良に伴い、破壊的変更が発生する可能性があります。 + +## 前提条件 + +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 + +## インストール + +まだインストールしていない場合は、OpenAI Agents SDK をインストールします: + +```bash +pip install openai-agents +``` + +## 最初の Realtime エージェントの作成 + +### 1. 必要なコンポーネントをインポート + +```python +import asyncio +from agents.realtime import RealtimeAgent, RealtimeRunner +``` + +### 2. Realtime エージェントを作成 + +```python +agent = RealtimeAgent( + name="Assistant", + instructions="You are a helpful voice assistant. Keep your responses conversational and friendly.", +) +``` + +### 3. Runner を設定 + +```python +runner = RealtimeRunner( + starting_agent=agent, + config={ + "model_settings": { + "model_name": "gpt-4o-realtime-preview", + "voice": "alloy", + "modalities": ["text", "audio"], + } + } +) +``` + +### 4. セッションを開始 + +```python +async def main(): + # Start the realtime session + session = await runner.run() + + async with session: + # Send a text message to start the conversation + await session.send_message("Hello! How are you today?") + + # The agent will stream back audio in real-time (not shown in this example) + # Listen for events from the session + async for event in session: + if event.type == "response.audio_transcript.done": + print(f"Assistant: {event.transcript}") + elif event.type == "conversation.item.input_audio_transcription.completed": + print(f"User: {event.transcript}") + +# Run the session +asyncio.run(main()) +``` + +## 完全な例 + +以下に動作する完全な例を示します: + +```python +import asyncio +from agents.realtime import RealtimeAgent, RealtimeRunner + +async def main(): + # Create the agent + agent = RealtimeAgent( + name="Assistant", + instructions="You are a helpful voice assistant. Keep responses brief and conversational.", + ) + + # Set up the runner with configuration + runner = RealtimeRunner( + starting_agent=agent, + config={ + "model_settings": { + "model_name": "gpt-4o-realtime-preview", + "voice": "alloy", + "modalities": ["text", "audio"], + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 200 + } + } + } + ) + + # Start the session + session = await runner.run() + + async with session: + print("Session started! The agent will stream audio responses in real-time.") + + # Process events + async for event in session: + if event.type == "response.audio_transcript.done": + print(f"Assistant: {event.transcript}") + elif event.type == "conversation.item.input_audio_transcription.completed": + print(f"User: {event.transcript}") + elif event.type == "error": + print(f"Error: {event.error}") + break + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## 設定オプション + +### モデル設定 + +- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-4o-realtime-preview`) +- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストおよび/または音声を有効にします (`["text", "audio"]`) + +### オーディオ設定 + +- `input_audio_format`: 入力音声のフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力音声のフォーマット +- `input_audio_transcription`: 文字起こしの構成 + +### ターン検出 + +- `type`: 検出方法 (`server_vad`, `semantic_vad`) +- `threshold`: 音声アクティビティのしきい値 (0.0–1.0) +- `silence_duration_ms`: ターン終了を検出するための無音時間 +- `prefix_padding_ms`: 発話前の音声パディング + +## 次のステップ + +- [Realtime エージェントについて詳しく学ぶ](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作する code examples をご覧ください +- エージェントに tools を追加する +- エージェント間の handoffs を実装する +- 安全のための guardrails を設定する + +## 認証 + +OpenAI API キーが環境変数に設定されていることを確認してください: + +```bash +export OPENAI_API_KEY="your-api-key-here" +``` + +または、セッション作成時に直接渡すこともできます: + +```python +session = await runner.run(model_config={"api_key": "your-api-key"}) +``` \ No newline at end of file diff --git a/docs/ja/release.md b/docs/ja/release.md new file mode 100644 index 000000000..ca1b1bab7 --- /dev/null +++ b/docs/ja/release.md @@ -0,0 +1,32 @@ +--- +search: + exclude: true +--- +# リリースプロセス/変更ログ + +本プロジェクトでは、`0.Y.Z` 形式を用いた、やや変更されたセマンティック バージョニングを採用しています。先頭の `0` は SDK が急速に進化中であることを示します。各コンポーネントの増分ルールは次のとおりです。 + +## マイナー (`Y`) バージョン + +ベータでない公開インターフェースに **破壊的変更** が入る場合、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新に破壊的変更が含まれる可能性があります。 + +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定して使用することをおすすめします。 + +## パッチ (`Z`) バージョン + +非破壊的変更の場合は `Z` を増やします。 + +- バグ修正 +- 新機能 +- プライベート インターフェースの変更 +- ベータ機能の更新 + +## 破壊的変更の変更ログ + +### 0.2.0 + +このバージョンでは、以前 `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 diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 108c12b90..cf88e6d08 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,19 +4,18 @@ search: --- # REPL ユーティリティ -`run_demo_loop` を使うと、ターミナルから手軽にエージェントを試せます。 +SDK には、対話的なテストを素早く行うための `run_demo_loop` が用意されています。 ```python import asyncio from agents import Agent, run_demo_loop async def main() -> None: - agent = Agent(name="Assistant", instructions="あなたは親切なアシスタントです") + agent = Agent(name="Assistant", instructions="You are a helpful assistant.") await run_demo_loop(agent) if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` は入力を繰り返し受け取り、会話履歴を保持したままエージェントを実行します。既定ではストリーミング出力を表示します。 -`quit` または `exit` と入力するか `Ctrl-D` を押すと終了します。 +`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 cedd92402..d80dff6b6 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] -これらはどちらも [`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` が定義されていない場合は `str` - `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフが発生する可能性があるため、静的に型付けできません。ハンドオフが発生すると、どのエージェントでも最後になり得るため、可能性のある出力型を静的に特定できないのです。 + `final_output` の型は `Any` です。ハンドオフが発生する可能性があるため、静的型付けはできません。ハンドオフが起こると、どのエージェントが最後になるかは不定であり、可能な出力型の集合を静的に特定できないからです。 -## 次のターンへの入力 +## 次ターンの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用すると、エージェント実行中に生成されたアイテムを元の入力に連結した入力リストへ変換できます。これにより、あるエージェント実行の出力を別の実行へ渡したり、ループで実行して毎回新しいユーザー入力を追加したりすることが容易になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用すると、渡した元の入力とエージェント実行中に生成されたアイテムを結合した input list に変換できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするときに便利です。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されています。アプリケーションによっては、次回ユーザーが入力する際にこれが役立つことがよくあります。例えば、フロントラインのトリアージ エージェントが言語専用のエージェントにハンドオフする場合、最後のエージェントを保存しておき、ユーザーが次にメッセージを送ったときに再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されています。アプリケーションによっては、これは次回ユーザーが入力する際に役立つことがよくあります。たとえば、一次受付のエージェントが言語別のエージェントへハンドオフする場合、最後のエージェントを保存しておき、次にユーザーからメッセージが来た際に再利用できます。 ## 新しいアイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。これらのアイテムは [`RunItem`][agents.items.RunItem] です。RunItem は、 LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。`RunItem` は LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] — LLM からのメッセージを示します。 raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] — LLM がハンドオフ ツールを呼び出したことを示します。 raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] — ハンドオフが発生したことを示します。 raw アイテムはハンドオフ ツール呼び出しに対するツール応答です。また、アイテムから送信元 / 送信先エージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] — LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] — ツールが呼び出されたことを示します。 raw アイテムはツール応答です。また、アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] — LLM からの推論アイテムを示します。 raw アイテムは生成された推論内容です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツールレスポンスです。アイテムからソース / ターゲットエージェントも取得できます。 +- [`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 83d5bec64..bdfc8aeae 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,12 +4,11 @@ search: --- # エージェントの実行 -`Runner` クラス [`Runner`][agents.run.Runner] を使用して エージェント を実行できます。方法は 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。方法は 3 つあります: -1. 非同期で実行し、[`RunResult`][agents.result.RunResult] を返す [`Runner.run()`][agents.run.Runner.run] -2. 同期メソッドで、内部的には `.run()` を呼び出す [`Runner.run_sync()`][agents.run.Runner.run_sync] -3. 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返す [`Runner.run_streamed()`][agents.run.Runner.run_streamed] - 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 @@ -24,52 +23,55 @@ async def main(): # Infinite loop's dance. ``` -詳細は [結果ガイド](results.md) を参照してください。 +詳細は [結果ガイド](results.md) をご覧ください。 ## エージェントループ -`Runner` の run メソッドを使用する際は、開始 エージェント と入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または入力項目のリスト（OpenAI Responses API の項目）です。 +`Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）を指定できます。 -Runner は以下のループを実行します。 +Runner は次のループを実行します: -1. 現在の エージェント と現在の入力で LLM を呼び出します。 +1. 現在のエージェントと入力を使って LLM を呼び出します。 2. LLM が出力を生成します。 - 1. `final_output` が返された場合、ループを終了して結果を返します。 - 2. ハンドオフ が発生した場合、現在の エージェント と入力を更新し、ループを再実行します。 - 3. ツール呼び出し がある場合、それらを実行し、結果を追加してループを再実行します。 -3. 指定した `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 1. `final_output` を返した場合はループを終了し、結果を返します。 + 2. ハンドオフがある場合は現在のエージェントと入力を更新し、ループを再実行します。 + 3. ツール呼び出しがある場合はツールを実行し、その結果を追加してループを再実行します。 +3. 渡された `max_turns` を超えた場合は [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力であり、ツール呼び出しがないことです。 + + LLM の出力が「最終出力」と見なされる条件は、求められた型のテキスト出力があり、かつツール呼び出しが存在しないことです。 ## ストリーミング -ストリーミング を使用すると、LLM の実行中に ストリーミング イベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には実行に関する完全な情報（新しく生成されたすべての出力を含む）が格納されます。`.stream_events()` を呼び出して ストリーミング イベントを取得できます。詳しくは [ストリーミングガイド](streaming.md) をご覧ください。 +ストリーミングを利用すると、LLM 実行中にストリーミングイベントを受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行の完全な情報（新しい出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 + +## 実行設定 -## Run 設定 +`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` を設定することを推奨します。`group_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 つ目のエージェントがさらにツールを実行し、最終的な出力を生成。 -1. ユーザーターン: ユーザー がテキストを入力 -2. Runner 実行: 最初の エージェント が LLM を呼び出し、ツールを実行し、2 番目の エージェント へハンドオフ。2 番目の エージェント がさらにツールを実行し、最終出力を生成。 +エージェントの実行終了後、ユーザーに何を表示するかは自由です。エージェントが生成したすべての新しいアイテムを見せてもよいですし、最終出力だけを見せてもかまいません。いずれにせよ、ユーザーが続けて質問した場合は再度 run メソッドを呼び出します。 -エージェント実行の終了時に、ユーザー に何を表示するかは自由です。たとえば、エージェント が生成したすべての新しい項目を表示する、または最終出力のみを表示する等です。いずれの場合でも、ユーザー がフォローアップ質問をしたら、再度 run メソッドを呼び出せます。 +### 手動での会話管理 -次ターンの入力は、基底クラス [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用して取得できます。 +次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して会話履歴を手動で管理できます: ```python async def main(): @@ -88,12 +90,45 @@ async def main(): # California ``` +### Sessions による自動会話管理 + +より簡単な方法として、[Sessions](sessions.md) を使用すれば `.to_input_list()` を手動で呼び出さなくても会話履歴を自動で扱えます: + +```python +from agents import Agent, Runner, SQLiteSession + +async def main(): + agent = Agent(name="Assistant", instructions="Reply very concisely.") + + # Create session instance + session = SQLiteSession("conversation_123") + + with trace(workflow_name="Conversation", group_id=thread_id): + # First turn + result = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session) + print(result.final_output) + # San Francisco + + # Second turn - agent automatically remembers previous context + result = await Runner.run(agent, "What state is it in?", session=session) + print(result.final_output) + # California +``` + +Sessions は自動で以下を行います: + +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なる session ID ごとに個別の会話を維持 + +詳細は [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] — 実行が `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 new file mode 100644 index 000000000..8fae9068c --- /dev/null +++ b/docs/ja/sessions.md @@ -0,0 +1,315 @@ +--- +search: + exclude: true +--- +# セッション + +Agents SDK は、組み込みのセッションメモリーを提供しており、複数回のエージェント実行にわたって会話履歴を自動的に保持します。そのため、ターンごとに手動で `.to_input_list()` を扱う必要がありません。 + +Sessions は特定のセッションに対して会話履歴を保存し、明示的な手動メモリー管理なしにコンテキストを維持できるようにします。これは、エージェントが過去の対話を記憶してほしいチャットアプリケーションやマルチターンの会話を構築する際に特に便利です。 + +## クイックスタート + +```python +from agents import Agent, Runner, SQLiteSession + +# Create agent +agent = Agent( + name="Assistant", + instructions="Reply very concisely.", +) + +# Create a session instance with a session ID +session = SQLiteSession("conversation_123") + +# First turn +result = await Runner.run( + agent, + "What city is the Golden Gate Bridge in?", + session=session +) +print(result.final_output) # "San Francisco" + +# Second turn - agent automatically remembers previous context +result = await Runner.run( + agent, + "What state is it in?", + session=session +) +print(result.final_output) # "California" + +# Also works with synchronous runner +result = Runner.run_sync( + agent, + "What's the population?", + session=session +) +print(result.final_output) # "Approximately 39 million" +``` + +## 仕組み + +セッションメモリーを有効にすると、次のように動作します。 + +1. **各実行の前**: Runner は自動的にそのセッションの会話履歴を取得し、入力アイテムの先頭に追加します。 +2. **各実行の後**: 実行中に生成された新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出しなど) がすべて自動的にセッションに保存されます。 +3. **コンテキスト保持**: 同じセッションでの次回以降の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 + +これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 + +## メモリー操作 + +### 基本操作 + +Sessions では会話履歴を管理するために次の操作が利用できます。 + +```python +from agents import SQLiteSession + +session = SQLiteSession("user_123", "conversations.db") + +# Get all items in a session +items = await session.get_items() + +# Add new items to a session +new_items = [ + {"role": "user", "content": "Hello"}, + {"role": "assistant", "content": "Hi there!"} +] +await session.add_items(new_items) + +# Remove and return the most recent item +last_item = await session.pop_item() +print(last_item) # {"role": "assistant", "content": "Hi there!"} + +# Clear all items from a session +await session.clear_session() +``` + +### pop_item の利用による訂正 + +`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に特に有用です。 + +```python +from agents import Agent, Runner, SQLiteSession + +agent = Agent(name="Assistant") +session = SQLiteSession("correction_example") + +# Initial conversation +result = await Runner.run( + agent, + "What's 2 + 2?", + session=session +) +print(f"Agent: {result.final_output}") + +# User wants to correct their question +assistant_item = await session.pop_item() # Remove agent's response +user_item = await session.pop_item() # Remove user's question + +# Ask a corrected question +result = await Runner.run( + agent, + "What's 2 + 3?", + session=session +) +print(f"Agent: {result.final_output}") +``` + +## メモリーオプション + +### メモリーなし (デフォルト) + +```python +# Default behavior - no session memory +result = await Runner.run(agent, "Hello") +``` + +### SQLite メモリー + +```python +from agents import SQLiteSession + +# In-memory database (lost when process ends) +session = SQLiteSession("user_123") + +# Persistent file-based database +session = SQLiteSession("user_123", "conversations.db") + +# Use the session +result = await Runner.run( + agent, + "Hello", + session=session +) +``` + +### 複数セッション + +```python +from agents import Agent, Runner, SQLiteSession + +agent = Agent(name="Assistant") + +# Different sessions maintain separate conversation histories +session_1 = SQLiteSession("user_123", "conversations.db") +session_2 = SQLiteSession("user_456", "conversations.db") + +result1 = await Runner.run( + agent, + "Hello", + session=session_1 +) +result2 = await Runner.run( + agent, + "Hello", + session=session_2 +) +``` + +## カスタムメモリー実装 + +独自のセッションメモリーを実装する場合は、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します。 + +````python +from agents.memory import Session +from typing import List + +class MyCustomSession: + """Custom session implementation following the Session protocol.""" + + def __init__(self, session_id: str): + self.session_id = session_id + # Your initialization here + + async def get_items(self, limit: int | None = None) -> List[dict]: + """Retrieve conversation history for this session.""" + # Your implementation here + pass + + async def add_items(self, items: List[dict]) -> None: + """Store new items for this session.""" + # Your implementation here + pass + + async def pop_item(self) -> dict | None: + """Remove and return the most recent item from this session.""" + # Your implementation here + pass + + async def clear_session(self) -> None: + """Clear all items for this session.""" + # Your implementation here + pass + +# Use your custom session +agent = Agent(name="Assistant") +result = await Runner.run( + agent, + "Hello", + session=MyCustomSession("my_session") +) + +## Session management + +### Session ID naming + +Use meaningful session IDs that help you organize conversations: + +- User-based: `"user_12345"` +- Thread-based: `"thread_abc123"` +- Context-based: `"support_ticket_456"` + +### Memory persistence + +- Use in-memory SQLite (`SQLiteSession("session_id")`) for temporary conversations +- Use file-based SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) for persistent conversations +- Consider implementing custom session backends for production systems (Redis, PostgreSQL, etc.) + +### Session management + +```python +# 会話をリセットしたいときにセッションをクリア +await session.clear_session() + +# 異なるエージェントが同じセッションを共有可能 +support_agent = Agent(name="Support") +billing_agent = Agent(name="Billing") +session = SQLiteSession("user_123") + +# 両方のエージェントが同じ会話履歴を参照 +result1 = await Runner.run( + support_agent, + "Help me with my account", + session=session +) +result2 = await Runner.run( + billing_agent, + "What are my charges?", + session=session +) +```` + +## Complete example + +Here's a complete example showing session memory in action: + +```python +import asyncio +from agents import Agent, Runner, SQLiteSession + + +async def main(): + # エージェントを作成 + agent = Agent( + name="Assistant", + instructions="Reply very concisely.", + ) + + # 実行間で保持されるセッションインスタンスを作成 + session = SQLiteSession("conversation_123", "conversation_history.db") + + print("=== Sessions Example ===") + print("The agent will remember previous messages automatically.\n") + + # 1 ターン目 + print("First turn:") + print("User: What city is the Golden Gate Bridge in?") + result = await Runner.run( + agent, + "What city is the Golden Gate Bridge in?", + session=session + ) + print(f"Assistant: {result.final_output}") + print() + + # 2 ターン目 ― エージェントは前回の会話を記憶 + print("Second turn:") + print("User: What state is it in?") + result = await Runner.run( + agent, + "What state is it in?", + session=session + ) + print(f"Assistant: {result.final_output}") + print() + + # 3 ターン目 ― 会話を継続 + print("Third turn:") + print("User: What's the population of that state?") + result = await Runner.run( + agent, + "What's the population of that state?", + session=session + ) + print(f"Assistant: {result.final_output}") + print() + + print("=== Conversation Complete ===") + print("Notice how the agent remembered the context from previous turns!") + print("Sessions automatically handles conversation history.") + + +if __name__ == "__main__": + asyncio.run(main()) \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index a8a46cca8..1570b8076 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、 エージェント の実行が進行するにつれて発生する更新を購読できます。これにより、エンド ユーザーに進捗状況や部分的な応答を表示するのに役立ちます。 +ストリーミングを使用すると、エージェントの実行が進行するにつれて更新を購読できます。これは、エンドユーザーに進捗状況や部分的なレスポンスを表示する際に役立ちます。 -ストリーミングを行うには、 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、後述する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 +ストリーミングを行うには、`Runner.run_streamed()` を呼び出します。これにより `RunResultStreaming` が返されます。`result.stream_events()` を呼び出すと、非同期で `StreamEvent` オブジェクトのストリームを取得できます。これらは後述します。 ## raw response イベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、 LLM から直接渡される raw なイベントです。これらは OpenAI Responses API 形式であり、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。生成されたメッセージを即座にユーザーへストリーミングしたい場合に便利です。 +`RawResponsesStreamEvent` は、LLM から直接渡される raw なイベントです。OpenAI Responses API フォーマットで提供されるため、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。生成されたレスポンスメッセージをすぐにユーザーへストリーミングしたい場合に便利です。 -たとえば、以下のコードは LLM が生成したテキストをトークンごとに出力します。 +例えば、これを実行すると、生成されたテキストを LLM がトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Run item イベントと エージェント イベント +## Run item イベントと agent イベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルなイベントです。アイテムが完全に生成されたタイミングを通知するため、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗をプッシュできます。同様に、 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] はハンドオフなどで現在の エージェント が変わった際に更新を提供します。 +`RunItemStreamEvent` は、より高レベルなイベントで、アイテムが完全に生成されたタイミングを通知します。これにより、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗をユーザーへ伝えられます。同様に、`AgentUpdatedStreamEvent` は、ハンドオフの結果などで現在のエージェントが変化した際に更新を提供します。 -たとえば、以下のコードは raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 +例えば、この例では raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index cd80092d5..d7d7146e5 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールはエージェントがアクションを実行できるようにします。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などです。Agents SDK には次の 3 種類のツールがあります。 +ツールはエージェントがデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作などのアクションを実行できるようにします。Agents SDK には 3 種類のツールがあります: -- ホストツール: これらは LLM サーバー上で AI モデルと一緒に実行されます。OpenAI は retrieval、Web 検索、コンピュータ操作をホストツールとして提供しています。 -- 関数呼び出し: 任意の Python 関数をツールとして利用できます。 -- ツールとしてのエージェント: ハンドオフせずに、エージェントから他のエージェントを呼び出すことができます。 +- Hosted ツール: LLM サーバー上で AI モデルと並行して実行されるツールです。OpenAI は retrieval、Web 検索、コンピュータ操作を Hosted ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして利用できます。 +- Agents as tools: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せるようにします。 -## ホストツール +## Hosted ツール -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。 +[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用すると、OpenAI がいくつかの組み込みツールを提供します: -- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルから直接利用できるようにします。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントによる Web 検索を可能にします。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 +- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## 関数ツール +## Function ツール -任意の Python 関数をツールとして使用できます。Agents SDK が自動的に設定を行います。 +任意の Python 関数をツールとして使用できます。Agents SDK がツールの設定を自動で行います: -- ツールの名前は Python 関数の名前になります（任意で名前を指定することも可能です） -- ツールの説明は関数の docstring から取得されます（任意で説明を指定することも可能です） -- 関数の引数から自動的に入力スキーマを生成します -- 各入力の説明は、無効化しない限り docstring から取得されます +- ツール名は Python 関数名になります (任意で名前を指定可能) +- ツールの説明は関数の docstring から取得されます (任意で説明を指定可能) +- 関数の引数から入力スキーマを自動生成します +- 各入力の説明は、無効化しない限り docstring から取得します -Python の `inspect` モジュールを使用して関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成します。 +Python の `inspect` モジュールで関数シグネチャを取得し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成します。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、同期・非同期どちらの関数も利用できます。 -2. docstring が存在する場合、ツールと引数の説明を取得します。 -3. 関数はオプションで `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring のスタイルなどを上書き設定することも可能です。 -4. デコレートされた関数をツールのリストに渡してください。 +1. 関数の引数には任意の Python 型を使用でき、同期・非同期どちらでも構いません。 +2. Docstring があれば、ツールおよび各引数の説明を取得します。 +3. 関数の最初の引数として `context` を受け取ることができます。また、ツール名や説明、docstring スタイルなどを上書き設定できます。 +4. デコレートした関数をツールのリストに渡します。 -??? note "展開して出力を確認" +??? 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`（context と引数の JSON 文字列を受け取り、ツールの出力を文字列で返す async 関数） +- `name` +- `description` +- `params_json_schema` — 引数の JSON スキーマ +- `on_invoke_tool` — [`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列の引数を受け取り、ツール出力の文字列を返す async 関数 ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを自動解析してツールのスキーマを生成し、docstring を解析してツールおよび個別引数の説明を抽出します。主な注意点は次のとおりです。 +前述のとおり、関数シグネチャを解析してツールのスキーマを抽出し、docstring からツールおよび個々の引数の説明を取得します。主なポイントは以下のとおりです: -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションを用いて引数の型を認識し、Pydantic モデルを動的に構築して全体のスキーマを表現します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 -2. `griffe` を使用して docstring を解析します。対応する docstring 形式は `google`、`sphinx`、`numpy` です。形式は自動検出を試みますが、`function_tool` 呼び出し時に明示的に指定することもできます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 +1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を把握し、Pydantic モデルを動的に生成して全体のスキーマを表現します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。対応している docstring 形式は `google`, `sphinx`, `numpy` です。自動的に形式を推測しますが、`function_tool` 呼び出し時に明示的に指定することもできます。`use_docstring_info` を `False` に設定すれば docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## ツールとしてのエージェント +## エージェントをツールとして使用 -一部のワークフローでは、ハンドオフせずに中央のエージェントが複数の専門エージェントをオーケストレーションしたい場合があります。そのような場合、エージェントをツールとしてモデル化できます。 +一部のワークフローでは、制御を委譲せずに中央のエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。その際はエージェントをツールとしてモデル化できます。 ```python from agents import Agent, Runner @@ -269,12 +269,12 @@ async def main(): ### ツールエージェントのカスタマイズ -`agent.as_tool` 関数はエージェントを簡単にツール化するためのヘルパーです。ただし、すべての設定に対応しているわけではありません（例: `max_turns` は設定不可）。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください。 +`agent.as_tool` はエージェントを簡単にツール化するための便利メソッドですが、すべての設定をサポートしているわけではありません (たとえば `max_turns` は設定できません)。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください: ```python @function_tool async def run_my_agent() -> str: - """A tool that runs the agent with custom configs". + """A tool that runs the agent with custom configs""" agent = Agent(name="My agent", instructions="...") @@ -288,12 +288,39 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -## 関数ツールでのエラー処理 +### カスタム出力抽出 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これはツール呼び出しが失敗した場合に LLM へ返すエラーレスポンスを生成する関数です。 +場合によっては、ツールエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば以下のようなケースです: -- 何も指定しない場合、`default_tool_error_function` が実行され、LLM にエラー発生を伝えます。 -- 独自のエラー関数を渡した場合はそちらが実行され、そのレスポンスが LLM へ送信されます。 -- 明示的に `None` を渡すと、ツール呼び出し時のエラーは再送出されます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになります。 +- サブエージェントのチャット履歴から特定の情報 (例: JSON ペイロード) を抽出する +- エージェントの最終回答を変換または再フォーマットする (例: Markdown をプレーンテキストや CSV に変換) +- 出力を検証し、不足または不正な場合にフォールバック値を提供する + +そのような場合は `as_tool` メソッドに `custom_output_extractor` 引数を渡します: + +```python +async def extract_json_payload(run_result: RunResult) -> str: + # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call. + for item in reversed(run_result.new_items): + if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"): + return item.output.strip() + # Fallback to an empty JSON object if nothing was found + return "{}" + + +json_tool = data_agent.as_tool( + tool_name="get_data_json", + tool_description="Run the data agent and return only its JSON payload", + custom_output_extractor=extract_json_payload, +) +``` + +## Function ツールでのエラー処理 + +`@function_tool` でツールを作成する際、`failure_error_function` を指定できます。この関数はツール呼び出しでクラッシュが発生した場合に LLM へ返すエラー応答を生成します。 + +- 何も渡さなかった場合、デフォルトで `default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 +- 独自のエラー関数を渡した場合は、その関数が実行され、その応答が LLM に送信されます。 +- 明示的に `None` を渡すと、ツール呼び出しのエラーが再スローされ、呼び出し元で処理できます。たとえば、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになります。 `FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index d67200ce4..3ef44165f 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはビルトインのトレーシング機能があり、エージェントの実行中に発生するイベント―― LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにカスタムイベントまで――を網羅的に記録します。開発時と本番環境の両方で [Traces dashboard](https://platform.openai.com/traces) を使用すると、ワークフローをデバッグ・可視化・モニタリングできます。 +Agents SDK には、エージェント実行中に発生するイベント ( LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベント) を網羅的に記録する組み込みのトレーシング機能が含まれています。 [Traces dashboard](https://platform.openai.com/traces) を使用すると、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は次の 2 つです: + トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。 - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する - 2. 単一の実行に対しては [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化する + 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する -***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングを利用できません。*** +***OpenAI の API を使用し Zero Data Retention ( ZDR ) ポリシーの下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 1 度のワークフロー全体を表します。複数のスパンで構成され、次のプロパティを持ちます: - - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 - - `trace_id`: トレースを一意に識別する ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: オプションのグループ ID。会話内の複数トレースを関連付けます。たとえばチャットスレッド ID など。 - - `disabled`: `True` の場合、このトレースは記録されません。 - - `metadata`: トレースに付随する任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ個々の処理を表します。スパンは以下を保持します: - - `started_at` と `ended_at` タイムスタンプ - - 所属トレースを示す `trace_id` - - 親スパンを指す `parent_id` (存在する場合) - - スパンに関する情報を格納する `span_data`。たとえば `AgentSpanData` にはエージェント情報が、`GenerationSpanData` には LLM 生成情報が含まれます。 +- **トレース** は 1 つのワークフローにおけるエンドツーエンドの操作を表します。複数のスパンで構成され、以下のプロパティを持ちます。 + - `workflow_name` : 論理的なワークフローまたはアプリ名。例: 「コード生成」や「カスタマー サービス」 + - `trace_id` : トレースの一意 ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id` : 省略可。会話内の複数トレースをリンクするグループ ID。たとえばチャットスレッド ID などに利用できます。 + - `disabled` : `True` の場合、このトレースは記録されません。 + - `metadata` : 省略可のメタデータ。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次のものがあります。 + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id` (存在する場合) + - スパンに関する情報を含む `span_data` 。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など ## デフォルトのトレーシング -デフォルトで SDK は以下をトレースします: +デフォルトでは、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_span()` でラップ +- ガードレールを `guardrail_span()` でラップ +- ハンドオフを `handoff_span()` でラップ +- 音声入力 ( speech-to-text ) を `transcription_span()` でラップ +- 音声出力 ( text-to-speech ) を `speech_span()` でラップ +- 関連する音声スパンは `speech_group_span()` の下に配置される場合があります -トレース名はデフォルトで「Agent trace」です。`trace` を使用して指定したり、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定できます。 +デフォルトのトレース名は「Agent trace」です。`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,60 +64,60 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `with trace()` で 2 つの `Runner.run` 呼び出しをラップしているため、それぞれが個別のトレースを作成せず、全体で 1 つのトレースになります。 +1. `with trace()` で 2 回の `Runner.run` をラップしているため、それぞれの実行は個別にトレースを作成せず、全体トレースに含まれます。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。開始と終了が必要で、方法は 2 つあります。 +トレースは [`trace()`][agents.tracing.trace] 関数で作成できます。開始と終了が必要で、方法は 2 つあります。 -1. **推奨**: `with trace(...) as my_trace` のようにコンテキストマネージャーとして使用する。開始と終了が自動で行われます。 -2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 +1. **推奨**: コンテキストマネージャとして使用する ( 例: `with trace(...) as my_trace` ) 。これにより、トレースの開始と終了が自動で行われます。 +2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されているため、並行処理でも自動で機能します。手動で開始／終了する場合は `start()`／`finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新してください。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理に自動対応します。トレースを手動で開始／終了する場合は、`start()` / `finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新してください。 ## スパンの作成 -各種 [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。一般的には手動で作成する必要はありません。カスタム情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も利用できます。 +各種 [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。通常、スパンを手動で作成する必要はありませんが、カスタム情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も用意されています。 -スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これも Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されています。 +スパンは自動で現在のトレースに属し、最も近い現在のスパンの下にネストされます。この情報も Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 -## 機密データ +## 機微なデータ -一部のスパンでは機密データが収集される可能性があります。 +一部のスパンでは機微なデータを取得する可能性があります。 -`generation_span()` には LLM の入力と出力、`function_span()` には関数呼び出しの入力と出力が保存されます。これらに機密データが含まれる場合、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使用して記録を無効化できます。 +`generation_span()` は LLM 生成の入力／出力を、`function_span()` は関数呼び出しの入力／出力を保存します。これらに機微なデータが含まれる場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使って取得を無効化できます。 -同様に、音声スパンにはデフォルトで base64 エンコードされた PCM 音声データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して音声データの記録を無効化できます。 +同様に、オーディオ スパンには入力／出力オーディオの base64 エンコード PCM データがデフォルトで含まれます。これを無効にする場合は、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定してください。 -## カスタムトレーシングプロセッサー +## カスタム トレース プロセッサ -トレーシングの高レベル構成は次のとおりです。 +トレーシングの高レベル アーキテクチャは以下のとおりです。 -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースを生成。 -- `TraceProvider` は [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を用いてスパン／トレースをバッチ送信し、[`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] が OpenAI バックエンドへバッチでエクスポートします。 +- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を生成し、トレースの作成を担当します。 +- `TraceProvider` は [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を使用してトレース／スパンをバッチ送信し、[`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] が 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) -- [MLflow (self‑hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu‑Monocle](https://github.com/monocle2ai/monocle) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow ( self-hosted / OSS )](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow ( Databricks hosted )](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 9093bb659..0a2e54e0a 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,11 +4,11 @@ search: --- # エージェントの可視化 -エージェントの可視化を使用すると、 ** Graphviz ** を用いてエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、handoffs がどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化を使用すると、**Graphviz** を利用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これにより、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを把握しやすくなります。 ## インストール -オプションの `viz` 依存関係グループをインストールします: +オプションの `viz` 依存グループをインストールします: ```bash pip install "openai-agents[viz]" @@ -16,11 +16,11 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は有向グラフを作成し、以下のように表現します。 +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **handoffs** はエージェント間の有向エッジで示されます。 +- **エージェント** は黄色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジで示されます。 ### 使用例 @@ -54,34 +54,34 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、 **triage agent** の構造と、それがサブエージェントやツールとどのようにつながっているかを視覚的に表すグラフが生成されます。 +これにより、**triage agent** の構造とサブエージェント、ツールとの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されたグラフには次の要素が含まれます。 +生成されたグラフには次の要素が含まれます: -- エントリーポイントを示す **start node** (`__start__`) -- 黄色の塗りつぶしを持つ **矩形** のエージェント -- 緑色の塗りつぶしを持つ **楕円** のツール -- 相互作用を示す有向エッジ - - エージェント間の handoffs には **実線の矢印** - - ツール呼び出しには **破線の矢印** -- 実行が終了する位置を示す **end node** (`__end__`) +- エントリポイントを示す **start ノード** (`__start__`) +- 黄色で塗りつぶされた **長方形** のエージェント +- 緑色で塗りつぶされた **楕円** のツール +- 相互作用を示す有向エッジ + - エージェント間のハンドオフには **実線の矢印** + - ツール呼び出しには **点線の矢印** +- 実行が終了する場所を示す **end ノード** (`__end__`) ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。別ウィンドウでグラフを表示するには、次のように記述します。 +デフォルトでは `draw_graph` はグラフをインライン表示します。別ウィンドウで表示したい場合は、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します: +デフォルトでは `draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") ``` -これにより、作業ディレクトリに `agent_graph.png` が生成されます。 +これにより、作業ディレクトリに `agent_graph.png` が生成されます。 \ No newline at end of file diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index d52fb77f7..97d13a0ea 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -2,9 +2,9 @@ search: exclude: true --- -# パイプラインと ワークフロー +# パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント的なワークフローを音声アプリに簡単に変換できるクラスです。ワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ変換する処理を担当します。 +`VoicePipeline` は、 エージェント ワークフローを音声アプリへ簡単に変換できるクラスです。実行したいワークフローを渡すだけで、パイプラインが入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理を自動で行います。 ```mermaid graph LR @@ -34,31 +34,33 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際に、以下を設定できます。 +パイプラインを作成するときには、次の項目を設定できます。 -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] ‐ 新しい音声が文字起こしされるたびに実行されるコード -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] ‐ 以下のような内容を設定可能 - - モデルプロバイダー。モデル名をモデルにマッピングします - - トレーシング。トレーシングの無効化、音声ファイルのアップロード可否、ワークフロー名、トレース ID など - - TTS と STT モデルの設定。プロンプト、言語、使用するデータ型など +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase] + 新しい音声が文字起こしされるたびに実行されるコードです。 +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] モデル +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig] + 以下のような内容を構成できます。 + - モデルプロバイダー（モデル名をモデルにマッピングできます） + - トレーシング（トレーシングの無効化、音声ファイルのアップロード可否、ワークフロー名、トレース ID など） + - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は次の 2 形式で渡せます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。音声入力は次の 2 つの形式で渡せます。 1. [`AudioInput`][agents.voice.input.AudioInput] - 完全な音声トランスクリプトがある場合に使用し、その結果だけを生成したいときに便利です。話者の発話終了を検知する必要がないケース、たとえば録音済み音声やプッシュトゥートーク型アプリのようにユーザーが話し終えたタイミングが明確な場合に向いています。 + 完全な音声トランスクリプトがある場合に使用し、そのまま結果を生成したいときに便利です。話者が話し終えるタイミングを検知する必要がない、たとえば事前録音された音声やプッシュトゥトーク方式のアプリでユーザーが話し終えるタイミングが明確な場合に適しています。 2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] - ユーザーの発話終了検知が必要な場合に使用します。検出された音声チャンクを順次プッシュでき、音声パイプラインが「アクティビティ検知」と呼ばれるプロセスを通じて適切なタイミングでエージェント ワークフローを自動的に実行します。 + ユーザーが話し終えたかどうかを検知する必要がある場合に使用します。音声チャンクを検出次第プッシュでき、パイプラインが「アクティビティ検知」により適切なタイミングでエージェント ワークフローを自動実行します。 ## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは発生したイベントをストリーミングで受け取れるオブジェクトです。いくつかの [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、主なものは次のとおりです。 +音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これはイベントをストリーム配信できるオブジェクトで、いくつかの [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] が含まれます。 -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] ‐ 音声チャンクを含みます -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] ‐ ターンの開始や終了などのライフサイクルイベントを通知します -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] ‐ エラーイベントです +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] — 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] — ターンの開始・終了などライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] — エラーイベントです。 ```python @@ -78,4 +80,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現在 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対して、組み込みの割り込み処理をサポートしていません。そのため、検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視できます。`turn_started` は新しいターンが文字起こしされ、処理が開始されたことを示します。`turn_ended` は該当ターンのすべての音声が送信された後にトリガーされます。たとえば、モデルがターンを開始した際にスピーカーのマイクをミュートし、そのターンに関連する音声をすべて送信し終えた後にアンミュートするといった制御に、これらのイベントを利用できます。 \ No newline at end of file +Agents SDK には現時点で [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートがありません。検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内部で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が始まったことを示し、`turn_ended` は該当ターンの音声がすべて送信された後に発火します。これらのイベントを利用して、モデルがターンを開始した際に話者のマイクをミュートし、そのターンに関する音声をすべて出力し終えたらアンミュートする、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 291b9882a..2e7facbfe 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -まずは [クイックスタート手順](../quickstart.md) に従って Agents SDK をセットアップし、仮想環境を作成してください。その後、SDK の音声関連のオプション依存関係をインストールします: + Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。その後、SDK の音声オプション依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## コンセプト -押さえておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは次の 3 ステップから成るプロセスです。 +理解しておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、次の 3 ステップを実行します。 -1. speech-to-text モデルを実行して音声をテキストに変換します。 +1. 音声をテキストに変換する speech-to-text モデルを実行します。 2. 通常はエージェント的ワークフローであるあなたのコードを実行し、結果を生成します。 -3. text-to-speech モデルを実行して結果のテキストを再び音声に変換します。 +3. 結果のテキストを再び音声に変換する text-to-speech モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかの エージェント をセットアップしましょう。この SDK でエージェントを構築したことがあれば、見覚えがあるはずです。ここでは複数の エージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントを設定しましょう。すでにこの SDK でエージェントを構築したことがある場合は、おなじみのはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -90,9 +90,9 @@ agent = Agent( ) ``` -## 音声パイプライン +## Voice パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして、シンプルな音声パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな Voice パイプラインを構築します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめて実行 +## まとめて実行する ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけます。実際にエージェントと会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file +この例を実行すると、エージェントがあなたに向かって話します。自分でエージェントと会話できるデモは [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) にありますので、ぜひご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 21f4788f9..f2d1093e2 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 +[エージェントがトレーシングされる方法](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントを参照してください。さらに、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] でパイプラインのトレーシング設定を行えます。 +基本的なトレーシング情報については上記のドキュメントを参照できますが、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを追加で設定することも可能です。 -主なトレーシング関連フィールドは次のとおりです。 +トレーシングに関連する主なフィールドは次のとおりです: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：トレースに音声テキストなどの機微なデータを含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内部で発生する処理には影響しません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]：トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]：トレース 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]: トレースに音声の書き起こしなどの機微情報を含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われる処理には影響しません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース ワークフローの名前です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための `group_id` です。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに追加するメタデータです。 \ No newline at end of file From bc32b99b0121ab753f8da9ce267c8a427272e500 Mon Sep 17 00:00:00 2001 From: MUHAMMAD SALMAN HUSSAIN <160324527+mshsheikh@users.noreply.github.com> Date: Fri, 18 Jul 2025 05:05:25 +0500 Subject: [PATCH 03/10] Correct a few typos in docs (#1128) --- docs/running_agents.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/running_agents.md b/docs/running_agents.md index 6898f5101..7d8f80851 100644 --- a/docs/running_agents.md +++ b/docs/running_agents.md @@ -16,7 +16,7 @@ async def main(): print(result.final_output) # Code within the code, # Functions calling themselves, - # Infinite loop's dance. + # Infinite loop's dance ``` Read more in the [results guide](results.md). @@ -40,7 +40,7 @@ The runner then runs a loop: ## Streaming -Streaming allows you to additionally receive streaming events as the LLM runs. Once the stream is done, the [`RunResultStreaming`][agents.result.RunResultStreaming] will contain the complete information about the run, including all the new outputs produces. You can call `.stream_events()` for the streaming events. Read more in the [streaming guide](streaming.md). +Streaming allows you to additionally receive streaming events as the LLM runs. Once the stream is done, the [`RunResultStreaming`][agents.result.RunResultStreaming] will contain the complete information about the run, including all the new outputs produced. You can call `.stream_events()` for the streaming events. Read more in the [streaming guide](streaming.md). ## Run config @@ -73,6 +73,7 @@ You can manually manage conversation history using the [`RunResultBase.to_input_ async def main(): agent = Agent(name="Assistant", instructions="Reply very concisely.") + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?") From 23404e8ff246fb9dc076d85241fc22a2a4e45c5c Mon Sep 17 00:00:00 2001 From: kobol Date: Sat, 19 Jul 2025 00:10:49 +0800 Subject: [PATCH 04/10] fix: ensure ResponseUsage token fields are int, not None (fixes #1179) (#1181) ### Problem When using streaming responses, some models or API endpoints may return `usage` fields (`prompt_tokens`, `completion_tokens`, `total_tokens`) as `None` or omit them entirely. The current implementation passes these values directly to the `ResponseUsage` Pydantic model, which expects integers. This causes a validation error: 3 validation errors for ResponseUsage input_tokens Input should be a valid integer [type=int_type, input_value=None, input_type=NoneType] output_tokens Input should be a valid integer [type=int_type, input_value=None, input_type=NoneType] total_tokens Input should be a valid integer [type=int_type, input_value=None, input_type=NoneType] ### Solution This PR ensures that all token fields passed to `ResponseUsage` are always integers. If any of the fields are `None` or missing, they default to `0`. This is achieved by using `or 0` and explicit `is not None` checks for nested fields. **Key changes:** - All `input_tokens`, `output_tokens`, `total_tokens` fields use `or 0` fallback. ### Impact - Fixes Pydantic validation errors for streaming responses with missing/None usage fields. - Improves compatibility with OpenAI and third-party models. - No breaking changes; only adds robustness. fixes #1179 Co-authored-by: thomas --- src/agents/models/chatcmpl_stream_handler.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/agents/models/chatcmpl_stream_handler.py b/src/agents/models/chatcmpl_stream_handler.py index 6133af344..eab4c291b 100644 --- a/src/agents/models/chatcmpl_stream_handler.py +++ b/src/agents/models/chatcmpl_stream_handler.py @@ -493,9 +493,9 @@ async def handle_stream( final_response.output = outputs final_response.usage = ( ResponseUsage( - input_tokens=usage.prompt_tokens, - output_tokens=usage.completion_tokens, - total_tokens=usage.total_tokens, + input_tokens=usage.prompt_tokens or 0, + output_tokens=usage.completion_tokens or 0, + total_tokens=usage.total_tokens or 0, output_tokens_details=OutputTokensDetails( reasoning_tokens=usage.completion_tokens_details.reasoning_tokens if usage.completion_tokens_details From 90465776fc445ef54beabeb3681afda8093fdbfb Mon Sep 17 00:00:00 2001 From: slubbers-openai Date: Fri, 18 Jul 2025 09:11:14 -0700 Subject: [PATCH 05/10] Add missing guardrail exception import to quickstart (#1161) docs: add missing InputGuardrailTripwireTriggered import to quickstart example Fixes NameError when handling guardrail exceptions by including the required import in the docs. --- docs/quickstart.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 213d16e5d..b5bc7177d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -97,6 +97,7 @@ You can define custom guardrails to run on the input or output. from agents import GuardrailFunctionOutput, Agent, Runner from pydantic import BaseModel + class HomeworkOutput(BaseModel): is_homework: bool reasoning: str @@ -122,6 +123,7 @@ Let's put it all together and run the entire workflow, using handoffs and the in ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner +from agents.exceptions import InputGuardrailTripwireTriggered from pydantic import BaseModel import asyncio @@ -166,11 +168,19 @@ triage_agent = Agent( ) async def main(): - result = await Runner.run(triage_agent, "who was the first president of the united states?") - print(result.final_output) - - result = await Runner.run(triage_agent, "what is life") - print(result.final_output) + # Example 1: History question + try: + result = await Runner.run(triage_agent, "who was the first president of the united states?") + print(result.final_output) + except InputGuardrailTripwireTriggered as e: + print("Guardrail blocked this input:", e) + + # Example 2: General/philosophical question + try: + result = await Runner.run(triage_agent, "What is the meaning of life?") + print(result.final_output) + except InputGuardrailTripwireTriggered as e: + print("Guardrail blocked this input:", e) if __name__ == "__main__": asyncio.run(main()) From 4b8f40ecea50348d1bf7d584826a8126d0288252 Mon Sep 17 00:00:00 2001 From: Roman Khan <160168703+romankhan26@users.noreply.github.com> Date: Fri, 18 Jul 2025 21:11:30 +0500 Subject: [PATCH 06/10] fix: fallback to function name for unnamed output_guardrail decorators (#1133) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Overview:** This PR improves the output_guardrail behavior by ensuring a valid name is always assigned to the guardrail, even when the decorator is used without parentheses or without explicitly providing a name. **Problem:** Previously, when the decorator @output_guardrail was used without a name (and without parentheses), the name attribute of the guardrail remained None. This resulted in issues during runtime — specifically, the guardrail name did not appear in result.input_guardrail_results, making it harder to trace or debug guardrail outputs. While the OutputGuardrail.get_name() method correctly defaults to the function name when name is None, this method is not used inside the decorator. Hence, unless a name is provided explicitly, the OutputGuardrail instance holds None for its name internally. **Solution:** This PR updates the decorator logic to: Automatically fallback to the function name if the name parameter is not provided. Ensure that the guardrail always has a meaningful identifier, which improves downstream behavior such as logging, debugging, and result tracing. **Example Behavior Before:** @output_guardrail def validate_output(...): Name remains None **Example Behavior After:** @output_guardrail def validate_output(...): Name becomes "validate_output" automatically **Why it matters:** This small change avoids hidden bugs or inconsistencies in downstream systems (like guardrail_results) that rely on guardrail names being defined. It also brings consistent behavior whether or not parentheses are used in the decorator. --- src/agents/guardrail.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/agents/guardrail.py b/src/agents/guardrail.py index 2bb0f014e..630c6f5d4 100644 --- a/src/agents/guardrail.py +++ b/src/agents/guardrail.py @@ -314,7 +314,11 @@ async def my_async_guardrail(...): ... def decorator( f: _OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co], ) -> OutputGuardrail[TContext_co]: - return OutputGuardrail(guardrail_function=f, name=name) + return OutputGuardrail( + guardrail_function=f, + # Guardrail name defaults to function name when not specified (None). + name=name if name else f.__name__, + ) if func is not None: # Decorator was used without parentheses From 4a31bb61091975cb44278e5050d31112fc68bf3c Mon Sep 17 00:00:00 2001 From: tconley1428 Date: Fri, 18 Jul 2025 09:14:23 -0700 Subject: [PATCH 07/10] Mark some dataclasses as pydantic dataclasses (#1131) This is the set of top level types used by Temporal for serialization across activity boundaries. In order to ensure that the models contained in these dataclasses are built prior to use, the dataclasses need to be `pydantic.dataclasses.dataclass` rather than `dataclasses.dataclass` This fixes issues where the types cannot be serialized if the contained types happen not to have been built. This happens particularly often when model logging is disabled, which happened to build the pydantic models as a side effect. --- src/agents/items.py | 3 ++- src/agents/model_settings.py | 3 ++- src/agents/usage.py | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/agents/items.py b/src/agents/items.py index 64797ad22..fd13031e2 100644 --- a/src/agents/items.py +++ b/src/agents/items.py @@ -5,6 +5,7 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union +import pydantic from openai.types.responses import ( Response, ResponseComputerToolCall, @@ -212,7 +213,7 @@ class MCPApprovalResponseItem(RunItemBase[McpApprovalResponse]): """An item generated by an agent.""" -@dataclass +@pydantic.dataclasses.dataclass class ModelResponse: output: list[TResponseOutputItem] """A list of outputs (messages, tool calls, etc) generated by the model""" diff --git a/src/agents/model_settings.py b/src/agents/model_settings.py index edb692960..5af83fe3e 100644 --- a/src/agents/model_settings.py +++ b/src/agents/model_settings.py @@ -2,7 +2,7 @@ import dataclasses from collections.abc import Mapping -from dataclasses import dataclass, fields, replace +from dataclasses import fields, replace from typing import Annotated, Any, Literal, Union from openai import Omit as _Omit @@ -10,6 +10,7 @@ from openai.types.responses import ResponseIncludable from openai.types.shared import Reasoning from pydantic import BaseModel, GetCoreSchemaHandler +from pydantic.dataclasses import dataclass from pydantic_core import core_schema from typing_extensions import TypeAlias diff --git a/src/agents/usage.py b/src/agents/usage.py index 843f62937..3639cf944 100644 --- a/src/agents/usage.py +++ b/src/agents/usage.py @@ -1,6 +1,7 @@ -from dataclasses import dataclass, field +from dataclasses import field from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails +from pydantic.dataclasses import dataclass @dataclass From de8accc36dc991123aba6a4680bb115b0fd46aac Mon Sep 17 00:00:00 2001 From: Hassan Abu Alhaj <136383052+habema@users.noreply.github.com> Date: Fri, 18 Jul 2025 19:19:38 +0300 Subject: [PATCH 08/10] fix: Apply strict JSON schema validation in FunctionTool constructor (#1041) ## Summary Fixes an issue where directly created `FunctionTool` objects fail with OpenAI's Responses API due to missing `additionalProperties: false` in the JSON schema, while the `@function_tool` decorator works correctly. ## Problem The documentation example for creating `FunctionTool` objects directly fails with: ``` Error code: 400 - {'error': {'message': "Invalid schema for function 'process_user': In context=(), 'additionalProperties' is required to be supplied and to be false.", 'type': 'invalid_request_error', 'param': 'tools[0].parameters', 'code': 'invalid_function_parameters'}} ``` This creates an inconsistency between `FunctionTool` and `@function_tool` behavior, both of which have `strict_json_schema=True` by default. ## Solution - Added `__post_init__` method to `FunctionTool` dataclass - Automatically applies `ensure_strict_json_schema()` when `strict_json_schema=True` - Makes behavior consistent with `@function_tool` decorator - Maintains backward compatibility ## Testing The fix can be verified by running the reproduction case from the issue: ```python from typing import Any from pydantic import BaseModel from agents import RunContextWrapper, FunctionTool, Agent, Runner class FunctionArgs(BaseModel): username: str age: int async def run_function(ctx: RunContextWrapper[Any], args: str) -> str: parsed = FunctionArgs.model_validate_json(args) return f"{parsed.username} is {parsed.age} years old" # This now works without manual ensure_strict_json_schema() call tool = FunctionTool( name="process_user", description="Processes extracted user data", params_json_schema=FunctionArgs.model_json_schema(), on_invoke_tool=run_function, ) agent = Agent( name="Test Agent", instructions="You are a test agent", tools=[tool] ) result = Runner.run_sync(agent, "Process user data for John who is 30 years old") ``` --- src/agents/tool.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/agents/tool.py b/src/agents/tool.py index b967e899b..16e149904 100644 --- a/src/agents/tool.py +++ b/src/agents/tool.py @@ -24,6 +24,7 @@ from .items import RunItem from .logger import logger from .run_context import RunContextWrapper +from .strict_schema import ensure_strict_json_schema from .tool_context import ToolContext from .tracing import SpanError from .util import _error_tracing @@ -92,6 +93,10 @@ class FunctionTool: and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool based on your context/state.""" + def __post_init__(self): + if self.strict_json_schema: + self.params_json_schema = ensure_strict_json_schema(self.params_json_schema) + @dataclass class FileSearchTool: From 7a8866f83a5ed65dc221f0b6d98671cc6ed79ddb Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Sat, 19 Jul 2025 01:36:26 +0900 Subject: [PATCH 09/10] Fix image_generator example error on Windows OS (#1180) Due to the method name typo, it does not work on the OS. --- examples/tools/image_generator.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tools/image_generator.py b/examples/tools/image_generator.py index fd6fcc6ba..747b9ce92 100644 --- a/examples/tools/image_generator.py +++ b/examples/tools/image_generator.py @@ -12,7 +12,7 @@ def open_file(path: str) -> None: if sys.platform.startswith("darwin"): subprocess.run(["open", path], check=False) # macOS elif os.name == "nt": # Windows - os.astartfile(path) # type: ignore + os.startfile(path) # type: ignore elif os.name == "posix": subprocess.run(["xdg-open", path], check=False) # Linux/Unix else: From f20aa40f56ec374841dfe6e4f3d6118c8e32fb2b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 19 Jul 2025 08:47:06 +0900 Subject: [PATCH 10/10] Update all translated document pages (#1184) Automated update of translated documentation Co-authored-by: github-actions[bot] --- docs/ja/agents.md | 46 ++++++------ docs/ja/config.md | 30 ++++---- docs/ja/context.md | 45 ++++++------ docs/ja/examples.md | 41 ++++++----- docs/ja/guardrails.md | 40 +++++----- docs/ja/handoffs.md | 38 +++++----- docs/ja/index.md | 38 +++++----- docs/ja/mcp.md | 68 ++++++++--------- docs/ja/models/index.md | 75 ++++++++++--------- docs/ja/models/litellm.md | 22 +++--- docs/ja/multi_agent.md | 44 +++++------ docs/ja/quickstart.md | 64 +++++++++------- docs/ja/realtime/guide.md | 88 +++++++++++----------- docs/ja/realtime/quickstart.md | 62 ++++++++-------- docs/ja/release.md | 22 +++--- docs/ja/repl.md | 4 +- docs/ja/results.md | 44 +++++------ docs/ja/running_agents.md | 81 ++++++++++---------- docs/ja/sessions.md | 46 ++++++------ docs/ja/streaming.md | 16 ++-- docs/ja/tools.md | 98 ++++++++++++------------- docs/ja/tracing.md | 130 ++++++++++++++++----------------- docs/ja/visualization.md | 35 ++++----- docs/ja/voice/pipeline.md | 34 +++++---- docs/ja/voice/quickstart.md | 18 ++--- docs/ja/voice/tracing.md | 14 ++-- 26 files changed, 631 insertions(+), 612 deletions(-) diff --git a/docs/ja/agents.md b/docs/ja/agents.md index c7c65fd75..4a6bc16ec 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントは、アプリにおける中核の構成要素です。エージェントとは、 instructions と tools で設定された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中心的な構成要素です。エージェントは、instructions と tools で設定された大規模言語モデル ( LLM ) です。 ## 基本設定 -エージェントで最もよく設定するプロパティは次のとおりです。 +エージェントでよく設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: 開発者メッセージまたは system prompt とも呼ばれます。 -- `model`: 使用する LLM と、 temperature や top_p などのモデル調整パラメーターを指定する省略可能な `model_settings`。 -- `tools`: エージェントがタスクを遂行するために利用できるツールの一覧。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: developer message（開発者メッセージ）または システムプロンプト とも呼ばれます。 +- `model`: 使用する LLM を指定します。また、temperature や top_p などのモデル調整パラメーターを設定する `model_settings` を任意で指定できます。 +- `tools`: エージェントがタスクを達成するために使用できる tools です。 ```python from agents import Agent, ModelSettings, function_tool @@ -32,7 +32,7 @@ agent = Agent( ## コンテキスト -エージェントは汎用的に `context` 型を取ります。コンテキストは依存性インジェクション用ツールであり、あなたが作成して `Runner.run()` に渡すオブジェクトです。このオブジェクトはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。 +エージェントは汎用的な `context` 型を取ります。コンテキストは依存性注入用のツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、tool、handoff などに渡され、実行時に必要な依存関係や状態を格納する入れ物として機能します。コンテキストには任意の Python オブジェクトを渡せます。 ```python @dataclass @@ -50,7 +50,7 @@ agent = Agent[UserContext]( ## 出力タイプ -既定では、エージェントはプレーンテキスト（つまり `str` ）を出力します。エージェントに特定の型の出力を生成させたい場合は、 `output_type` パラメーターを使用します。よく使われるのは [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップ可能な型 ― dataclass、リスト、TypedDict など ― であれば何でもサポートしています。 +デフォルトでは、エージェントはプレーンテキスト、つまり `str` を出力します。特定の型で出力させたい場合は、`output_type` パラメーターを使用します。一般的には [Pydantic](https://docs.pydantic.dev/) オブジェクトを使うことが多いですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる型であれば何でもサポートされています。たとえば dataclass、list、TypedDict などです。 ```python from pydantic import BaseModel @@ -71,11 +71,11 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示されます。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく structured outputs を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフのリストを渡すと、関連性がある場合にエージェントがそれらへ委任できます。これは、単一タスクに特化したモジュール型エージェントをオーケストレーションする強力なパターンです。詳細は [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは関連性がある場合にそれらへ委譲できます。これは、単一タスクに特化したモジュール型エージェントを編成する強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -96,7 +96,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を指定できますが、関数を介して動的に渡すことも可能です。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数も `async` 関数も使用できます。 +通常はエージェント作成時に instructions を渡しますが、関数を通じて動的に instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数でも `async` 関数でも利用可能です。 ```python def dynamic_instructions( @@ -111,17 +111,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( @@ -138,15 +138,15 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、必ずしも LLM がツールを使用するとは限りません。 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することでツール使用を強制できます。有効な値は以下のとおりです。 +tools のリストを渡しても、LLM が必ずツールを使用するわけではありません。`ModelSettings.tool_choice` を設定することでツール使用を強制できます。設定可能な値は次のとおりです。 -1. `auto` : LLM がツールを使用するかどうかを判断します。 -2. `required` : LLM にツール使用を必須にします（ただし使用するツールは自動選択）。 -3. `none` : LLM にツールを使用しないことを必須にします。 -4. 文字列（例 `my_tool` ）を指定すると、その特定のツールを必ず使用させます。 +1. `auto` : LLM がツールを使用するかどうかを判断します。 +2. `required` : LLM にツールの使用を必須とします (どのツールを使うかは LLM が判断)。 +3. `none` : LLM にツールを使用しないことを要求します。 +4. 特定の文字列 (例: `my_tool`) を設定すると、そのツールの使用を必須とします。 !!! 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` により再びツール呼び出しが生成されるというサイクルが続くためです。 - ツール呼び出し後にエージェントを完全に停止させたい場合（自動モードを続行しない）、 [`Agent.tool_use_behavior="stop_on_first_tool"`] を設定できます。この場合、ツールの出力をそのまま最終応答として使用し、追加の LLM 処理は行いません。 \ No newline at end of file + ツール呼び出し後に自動モードへ移行せず完全に処理を終了したい場合は、[`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 80a7e656e..193045490 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -4,9 +4,9 @@ search: --- # SDK の設定 -## API keys と clients +## API キーとクライアント -デフォルトでは、 SDK はインポートされた時点で LLM リクエストとトレーシングのために `OPENAI_API_KEY` 環境変数を参照します。アプリが起動する前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 +デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストとトレーシング用に `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを生成します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用してください。 +また、使用する OpenAIクライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更したい場合は、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用してください。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -さらに、利用する OpenAI API をカスタマイズすることも可能です。デフォルトでは OpenAI Responses API を使用しますが、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API に切り替えることができます。 +さらに、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用しますが、 [set_default_openai_api()][agents.set_default_openai_api] 関数を使用して Chat Completions API に切り替えることができます。 ```python from agents import set_default_openai_api @@ -32,9 +32,9 @@ from agents import set_default_openai_api set_default_openai_api("chat_completions") ``` -## Tracing +## トレーシング -トレーシングはデフォルトで有効になっています。デフォルトでは前述の OpenAI API キー（環境変数、またはあなたが設定したデフォルトキー）が使用されます。トレーシングで使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。上記セクションの OpenAI API キー (環境変数または設定済みのデフォルトキー) が自動的に使用されます。トレーシング専用の API キーを設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化したい場合は、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用します。 +トレーシングを完全に無効化したい場合は、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用できます。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## Debug logging +## デバッグログ -SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。デフォルトでは、警告とエラーが `stdout` に出力され、それ以外のログは抑制されます。 +SDK にはハンドラーが設定されていない 2 つの Python ロガーが用意されています。デフォルトでは、 warning と error は `stdout` に出力されますが、それ以外のログは抑制されます。 -詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数をお使いください。 +詳細なログを有効にするには、 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用してください。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることも可能です。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることも可能です。詳しくは [Python logging guide](https://docs.python.org/3/howto/logging.html) をご覧ください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機密データ +### ログに含まれる機密データ -一部のログには機密データ（例: ユーザー データ）が含まれる場合があります。これらのデータをログに残さないようにするには、次の環境変数を設定してください。 +ログの中には機密データ (例: ユーザーデータ) を含むものがあります。これらのデータを記録しないようにする場合は、次の環境変数を設定してください。 -LLM の入力および出力のログを無効化する場合: +LLM の入力および出力のロギングを無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力および出力のログを無効化する場合: +ツールの入力および出力のロギングを無効化する: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 43285a4b2..77eae1e81 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,29 +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 オブジェクトを使うパターンが多いです。 -2. そのオブジェクトを各種 run メソッド (例: `Runner.run(..., **context=whatever**)`) に渡します。 -3. すべてのツール呼び出しやライフサイクルフックでは、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。`T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを利用するパターンが多いです。 +2. そのオブジェクトを各種 `run` メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 +3. すべてのツール呼び出しやライフサイクル フックなどには、`RunContextWrapper[T]` というラッパー オブジェクトが渡されます。ここで `T` はコンテキスト オブジェクトの型で、`wrapper.context` からアクセスできます。 -**最も重要な点**: 1 回のエージェント実行において、エージェント・ツール関数・ライフサイクルフックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 +**最も重要な点**: ひとつのエージェント実行において、エージェント・ツール関数・ライフサイクル フックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 -コンテキストは次のような用途に利用できます: +コンテキストは次のような用途に利用できます。 -- 実行のためのコンテキストデータ (例: ユーザー名や UID など ユーザー に関する情報) -- 依存関係 (例: ロガーオブジェクトやデータフェッチャーなど) +- 実行に関するコンテキスト データ（例: ユーザー名 / UID などのユーザー情報） +- 依存関係（例: ロガー オブジェクト、データフェッチャーなど） - ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは **LLM には送信されません**。あくまでローカルオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + + コンテキスト オブジェクトは **LLM に送信されません**。あくまでローカル オブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -65,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、どのような型でも構いません。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. ジェネリック型 `UserInfo` をエージェントに指定することで、型チェッカーが誤り (異なるコンテキスト型を取るツールを渡すなど) を検出できます。 +1. これはコンテキスト オブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることが分かります。ツール実装はコンテキストからデータを読み取ります。 +3. エージェントにジェネリック型 `UserInfo` を指定し、型チェッカーがエラーを検出できるようにしています（例: 異なるコンテキスト型を取るツールを渡そうとした場合など）。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント／LLM コンテキスト +## エージェント / LLM コンテキスト -LLM が呼び出されるとき、LLM が参照できる **唯一** のデータは会話履歴だけです。したがって、新しいデータを LLM に与えたい場合は、そのデータを履歴に含める方法を取る必要があります。主な方法は次のとおりです: +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴からのみ取得されます。そのため、新しいデータを LLM に渡したい場合は、履歴に含める形で提供する必要があります。主な方法は以下のとおりです。 -1. Agent の `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。`instructions` は静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。常に役立つ情報 (例: ユーザー名や現在の日付) を渡す一般的な手法です。 -2. `Runner.run` を呼び出す際に `input` に追加する。この方法は `instructions` と似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できる点が異なります。 -3. 関数ツールを通じて公開する。これは _オンデマンド_ コンテキストに適しており、LLM が必要になったタイミングでツールを呼び出してデータを取得できます。 -4. Retrieval や Web 検索を使用する。これらはファイルやデータベースから関連データを取得する (retrieval) または Web から取得する (Web 検索) 特殊なツールです。関連するコンテキストデータで回答をグラウンディングするのに有効です。 \ No newline at end of file +1. エージェントの `instructions` に追加する。これは「system prompt」や「developer message」とも呼ばれます。システム プロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。ユーザー名や現在の日付など、常に有用な情報を渡す際によく使われます。 +2. `Runner.run` を呼び出す際の `input` に追加する。この方法は `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) 上で下位に位置するメッセージを扱える点が異なります。 +3. 関数ツール経由で公開する。これはオンデマンドのコンテキストに適しており、LLM が必要になったタイミングでツールを呼び出してデータを取得できます。 +4. リトリーバルまたは Web 検索を使用する。これらはファイルやデータベース（リトリーバル）、あるいは Web（Web 検索）から関連データを取得できる特殊なツールです。回答を関連するコンテキスト データに「グラウンディング」するのに役立ちます。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index be118b0fa..177729613 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,42 +4,45 @@ search: --- # コード例 -リポジトリの [examples セクション](https://github.com/openai/openai-agents-python/tree/main/examples) では、SDK のさまざまなサンプル実装をご覧いただけます。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションには、 SDK のさまざまなサンプル実装が用意されています。これらのコード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーでは、以下のような一般的なエージェント設計パターンを示します。 - - 決定論的ワークフロー - - エージェントをツールとして利用 - - エージェントの並列実行 + このカテゴリーのコード例では、一般的なエージェント設計パターンを紹介しています。例: + + - 決定的ワークフロー + - エージェントをツールとして利用 + - エージェントの並列実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - SDK の基礎的な機能を紹介します。 - - 動的な 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 で利用する方法を紹介します。 +- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK と併用する方法を探求できます。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフの実践例をご覧いただけます。 + エージェントのハンドオフに関する実践的なコード例です。 - **[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 つの例です。 - - **customer_service**: 航空会社向けカスタマーサービスシステムの例。 - - **research_bot**: シンプルなディープリサーチ クローン。 + 実際のユースケースを想定した、より充実した 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 1858914a7..4b20832c1 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並列で_ 実行され、ユーザー入力のチェックとバリデーションを行います。たとえば、非常に賢い（そのため遅くて高コストな）モデルを使ってカスタマーリクエストを処理するエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、低コストかつ高速なモデルでガードレールを実行できます。もしガードレールが悪意ある使用を検知した場合、直ちにエラーを発生させることで高コストなモデルの実行を停止し、時間と費用を節約できます。 +ガードレール は エージェント と _並行して_ 実行され、ユーザー 入力のチェックおよびバリデーションを行えます。たとえば、とても賢い（つまり遅く / 高価な）モデルを使ってカスタマーリクエストを処理する エージェント があるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、速く / 安価なモデルでガードレールを実行できます。ガードレールが悪意のある利用を検出した場合、直ちにエラーを送出し、高価なモデルの実行を停止して時間とコストを節約します。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. Input ガードレールは最初のユーザー入力で実行されます -2. Output ガードレールは最終的なエージェント出力で実行されます +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` に渡さないのか疑問に思うかもしれません。これはガードレールが実際の Agent と密接に関連していることが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置いておくと可読性が向上するためです。 + 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントが *最初の* エージェントの場合にのみ実行されます。「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 - 出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、エージェントが *最後の* エージェントである場合にのみ実行されます。入力ガードレールと同様、ガードレールは実際の Agent と密接に関連しているため、エージェントごとに異なるガードレールを実行することになり、コードを同じ場所に置いておくと可読性が向上します。 + 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントが *最後の* エージェントの場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントと密接に関連しているため、コードを同じ場所に置く方が可読性に優れます。 ## トリップワイヤ -入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤでそれを通知できます。トリップワイヤが作動したガードレールを検出すると、ただちに `{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. こちらがエージェントの入力／コンテキストを受け取り、結果を返すガードレール関数です。 +2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 3. ガードレール結果に追加情報を含めることもできます。 -4. こちらがワークフローを定義する実際のエージェントです。 +4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. こちらが実際のエージェントの出力型です。 -2. こちらがガードレールの出力型です。 -3. こちらがエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. こちらがワークフローを定義する実際のエージェントです。 \ No newline at end of file +1. これは実際のエージェントの出力型です。 +2. これはガードレールの出力型です。 +3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 +4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index afde32dcb..5e55ddc49 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 からはツールとして扱われます。したがって `Refund Agent` というエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` となります。 ## ハンドオフの作成 -すべての エージェント には [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、直接 `Agent` を渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 +すべてのエージェントには `handoffs` パラメーターがあり、ここには `Agent` を直接渡すことも、ハンドオフをカスタマイズした `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用してハンドオフを作成できます。この関数では、ハンドオフ先の エージェント に加えて、オーバーライドや入力フィルターなどのオプションを指定できます。 +Agents SDK が提供する `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()` 関数では、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフ先となる エージェント です。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` という名前になります。これを上書きできます。 -- `tool_description_override`: `Handoff.default_tool_description()` によるデフォルトのツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが発生した時点でデータ取得を開始する、といった用途に便利です。この関数は エージェント コンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフで想定される入力の型（任意）。 -- `input_filter`: 次の エージェント が受け取る入力をフィルタリングできます。詳細は後述します。 +- `agent`: タスクを委譲するエージェント。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に評価されます。ここを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` によるデフォルトのツール説明を上書きします。 +- `on_handoff`: ハンドオフ実行時に呼び出されるコールバック関数。ハンドオフが呼び出された瞬間にデータ取得を開始するなどに便利です。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。この入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで期待される入力の型（任意）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルターできます。詳細は後述します。 ```python from agents import Agent, handoff, RunContextWrapper @@ -57,9 +57,9 @@ handoff_obj = handoff( ) ``` -## ハンドオフの入力 +## ハンドオフ入力 -場合によっては、 LLM にハンドオフ呼び出し時にいくつかのデータを渡してほしいことがあります。たとえば「Escalation agent」へのハンドオフでは、その理由を一緒に受け取りログに残したい、というケースです。 +状況によっては、LLM がハンドオフを呼び出す際に何らかのデータを渡してほしい場合があります。たとえば「Escalation agent（エスカレーション エージェント）」へのハンドオフでは、ログ用に理由を渡してもらいたいかもしれません。 ```python from pydantic import BaseModel @@ -83,9 +83,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しい エージェント が会話を引き継ぎ、これまでの会話履歴全体を見ることができます。これを変更したい場合は [`input_filter`][agents.handoffs.Handoff.input_filter] を設定します。入力フィルターは [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが行われると、新しいエージェントが会話を引き継ぎ、以前の会話履歴をすべて閲覧できる状態になります。これを変更したい場合は `input_filter` を設定してください。入力フィルターは `HandoffInputData` として渡された既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 -よくあるパターン（たとえば履歴からすべてのツール呼び出しを取り除くなど）は [`agents.extensions.handoff_filters`][] に実装されています。 +よくあるパターン（履歴からすべてのツール呼び出しを削除するなど）は、`agents.extensions.handoff_filters` に実装済みです。 ```python from agents import Agent, handoff @@ -99,11 +99,11 @@ handoff_obj = handoff( ) ``` -1. これにより `FAQ agent` が呼び出された際、履歴からすべてのツールが自動的に削除されます。 +1. これにより `FAQ agent` が呼び出された際に、履歴からすべてのツール呼び出しが自動的に削除されます。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるように、 エージェント にハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスが用意されているほか、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出してプロンプトに推奨データを自動で追加することもできます。 +LLM がハンドオフを正しく理解できるよう、エージェント内にハンドオフに関する情報を含めることを推奨します。`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX` に推奨のプリフィックスが用意されているほか、`agents.extensions.handoff_prompt.prompt_with_handoff_instructions` を呼び出すことで推奨情報をプロンプトに自動追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index 93b0c3340..e077c29aa 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK - OpenAI Agents SDK は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント指向の AI アプリを構築できます。これは、エージェントに関する以前の試験的プロジェクトである Swarm をプロダクションレベルにアップグレードしたものです。 Agents SDK には、ごく少数の基本コンポーネントがあります: +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、非常に少ない抽象化で軽量かつ使いやすいパッケージとして、エージェント指向の AI アプリを構築できるツールです。これは、以前のエージェント向け実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を、本番環境向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 -- **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できます -- **ガードレール**: エージェントへの入力を検証できます -- **セッション**: エージェント実行間で会話履歴を自動的に保持します +- **エージェント**: instructions と tools を備えた LLM +- **ハンドオフ**: 特定タスクを他のエージェントへ委任する仕組み +- **ガードレール**: エージェントへの入力を検証する仕組み +- **セッション**: エージェント実行間で会話履歴を自動的に保持 - Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えながら実用的なアプリケーションを構築できます。さらに、SDK には組み込みの トレーシング があり、エージェントフローの可視化やデバッグ、評価、さらにはアプリ向けモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに、SDK には **トレーシング** が組み込まれており、エージェントフローの可視化やデバッグ、評価、さらにはアプリ固有のモデルのファインチューニングも行えます。 -## Agents SDK を使う理由 +## Agents SDK を使用する理由 -SDK には 2 つの設計原則があります。 +SDK の設計には 2 つの原則があります。 -1. 使う価値があるだけの機能を備えつつ、学習が容易になるよう基本コンポーネントは少なく。 -2. すぐに使い始められる一方で、動作を細部までカスタマイズ可能に。 +1. 学ぶ価値のある十分な機能を備えつつ、覚えるべきコンポーネント数は最小限に抑える。 +2. そのままでも優れた体験を提供しつつ、処理内容を細かくカスタマイズできる。 -主な機能は次のとおりです。 +主な特徴は次のとおりです。 -- エージェントループ: ツール呼び出し、結果を LLM へ送信、 LLM が完了するまでループ処理を自動で行います。 -- Python ファースト: 新しい抽象概念を学ばずに、言語本来の機能でエージェントをオーケストレーションしチェーン化できます。 -- ハンドオフ: 複数エージェント間での調整と委譲を実現する強力な機能です。 -- ガードレール: エージェントと並行して入力バリデーションやチェックを行い、失敗時には早期終了します。 -- セッション: エージェント実行間の会話履歴を自動で管理し、手動での状態管理を排除します。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic による検証を提供します。 -- トレーシング: フローの可視化・デバッグ・モニタリングが可能で、 OpenAI の評価、ファインチューニング、蒸留ツールとも連携します。 +- エージェントループ: tools の呼び出し、結果を LLM へ送信、LLM が完了するまでループ処理を自動で実行。 +- Python ファースト: 新しい抽象を学習することなく、Python の言語機能でエージェントをオーケストレーションおよび連鎖。 +- ハンドオフ: 複数エージェント間の調整と委任を可能にする強力な機能。 +- ガードレール: エージェントと並行して入力検証を実行し、チェック失敗時には早期終了。 +- セッション: エージェント実行間の会話履歴を自動管理し、手動での状態管理を排除。 +- 関数ツール: 任意の Python 関数を自動スキーマ生成と Pydantic 検証付きの tool へ変換。 +- トレーシング: ワークフローの可視化・デバッグ・監視だけでなく、OpenAI の評価、ファインチューニング、蒸留ツールも利用可能。 ## インストール @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_実行する場合は、環境変数 `OPENAI_API_KEY` を設定してください_) +(_実行の際は `OPENAI_API_KEY` 環境変数を設定してください_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 33f6b08c3..69d45fa73 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 is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーション向けの USB-C ポートのようなものと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 - Agents SDK は MCP をサポートしています。これにより、さまざまな MCP サーバーを使用してエージェントにツールやプロンプトを提供できます。 +Agents SDK は MCP をサポートしています。これにより、幅広い MCP サーバーを使用してエージェントにツールやプロンプトを提供できます。 ## MCP サーバー -現在、 MCP 仕様では利用するトランスポートメカニズムに基づき、3 種類のサーバーを定義しています: +現在、MCP 仕様では使用するトランスポートメカニズムに基づき、3 種類のサーバーが定義されています: -1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動いていると考えてください。 -2. **HTTP over SSE** サーバー: リモートで実行され、URL を介して接続します。 -3. **Streamable HTTP** サーバー: MCP 仕様で定義されている Streamable HTTP トランスポートを使用してリモートで実行されます。 +1. **stdio** サーバー: アプリケーションのサブプロセスとして実行されます。ローカルで動作していると考えてください。 +2. **HTTP over SSE** サーバー: リモートで実行され、URL で接続します。 +3. **Streamable HTTP** サーバー: MCP 仕様で定義された Streamable HTTP トランスポートを用いてリモートで実行されます。 -これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスで接続できます。 +これらのサーバーへは [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] クラスを使って接続できます。 -たとえば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を使用する場合は次のようになります。 +たとえば、[公式 MCP ファイルシステムサーバー](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) を利用する場合は次のようになります。 ```python from agents.run_context import RunContextWrapper @@ -41,7 +41,7 @@ async with MCPServerStdio( ## MCP サーバーの利用 - MCP サーバーはエージェントに追加できます。 Agents SDK はエージェントの実行毎に MCP サーバーの `list_tools()` を呼び出し、 MCP サーバーのツールを LLM に認識させます。 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`: 現在の実行コンテキスト -- `agent`: ツールを要求しているエージェント -- `server_name`: MCP サーバー名 +`ToolFilterContext` では次の情報にアクセスできます: +- `run_context`: 現在の実行コンテキスト +- `agent`: ツールを要求しているエージェント +- `server_name`: MCP サーバー名 ## プロンプト - MCP サーバーはプロンプトも提供でき、パラメーター付きで動的にエージェントの instructions を生成できます。これにより再利用可能なインストラクションテンプレートを作成し、パラメーターでカスタマイズできます。 +MCP サーバーは、agent instructions を動的に生成できるプロンプトも提供します。これにより、パラメーターでカスタマイズ可能な再利用可能な instruction テンプレートを作成できます。 -### プロンプトの使用 +### プロンプトの利用 プロンプトをサポートする MCP サーバーは、次の 2 つの主要メソッドを提供します: -- `list_prompts()`: サーバー上の利用可能なプロンプトを列挙します -- `get_prompt(name, arguments)`: 指定したプロンプトをオプションのパラメーター付きで取得します +- `list_prompts()`: サーバー上のすべてのプロンプトを一覧表示 +- `get_prompt(name, arguments)`: 任意のパラメーター付きで特定のプロンプトを取得 ```python # List available prompts @@ -173,19 +173,19 @@ agent = Agent( ## キャッシュ -エージェントが実行されるたびに、 MCP サーバーの `list_tools()` が呼ばれます。サーバーがリモートの場合、これはレイテンシの原因になります。ツール一覧を自動でキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないことが確実な場合のみ使用してください。 +エージェントが実行されるたびに、MCP サーバーの `list_tools()` が呼ばれます。サーバーがリモートの場合、これはレイテンシーの原因になります。ツール一覧を自動でキャッシュするには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] に `cache_tools_list=True` を渡します。ツール一覧が変更されないと確信できる場合のみ実行してください。 キャッシュを無効化したい場合は、サーバーの `invalidate_tools_cache()` を呼び出します。 -## エンドツーエンドのコード例 +## End-to-end コード例 -動作する完全なコード例は [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) をご覧ください。 +[examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) で完全な動作例をご覧いただけます。 ## トレーシング -[トレーシング](./tracing.md) は以下を含む MCP 操作を自動的にキャプチャします: +[Tracing](./tracing.md) を使用すると、MCP 操作が自動的に記録されます。対象は次のとおりです: -1. ツール一覧取得のための MCP サーバーへの呼び出し -2. 関数呼び出しに関する MCP 関連情報 +1. MCP サーバーへのツール一覧要求 +2. 関数呼び出しに関する MCP 関連情報 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index b2fcd1525..04c7d99e8 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル - Agents SDK には、OpenAI モデルをすぐに利用できる 2 つの形態が用意されています: +Agents SDK には、すぐに使える 2 種類の OpenAI モデル対応が含まれています。 -- **推奨**: [`OpenAIResponsesModel`] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 -- [`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", ...) @@ -26,29 +26,29 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 非 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/) に code examples あり）。 -1. [`set_default_openai_client`] は、`AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケースに適しています。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 -2. [`ModelProvider`] は `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`] では、特定のエージェントインスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) をご覧ください。多くの利用可能なモデルを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) が便利です。 +1. [`set_default_openai_client`][agents.set_default_openai_client] — `AsyncOpenAI` インスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。LLM プロバイダーが OpenAI 互換 API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) をご覧ください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] — `Runner.run` レベルで指定できます。「この run 内のすべての エージェント ではカスタムモデルプロバイダーを使う」といった指定が可能です。設定例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) をご覧ください。 +3. [`Agent.model`][agents.agent.Agent.model] — 特定の Agent インスタンスにモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを混在させることができます。設定例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) をご覧ください。ほとんどのモデルを簡単に利用するには [LiteLLM インテグレーション](./litellm.md) が便利です。 - `platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することをおすすめします。 +`platform.openai.com` の API キーをお持ちでない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの例では、ほとんどの LLM プロバイダーが Responses API をまだサポートしていないため、Chat Completions API/モデルを使用しています。ご使用の LLM プロバイダーが Responses API をサポートしている場合は、Responses を使うことをおすすめします。 + これらの例では Chat Completions API/モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 ## モデルの組み合わせ - 1 つのワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小型で高速なモデルを使用し、複雑なタスクには大型で高性能なモデルを使う、といった形です。[`Agent`] を設定する際、次のいずれかで特定のモデルを選択できます: +1 つのワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、トリアージにはより小さく高速なモデルを使い、複雑なタスクにはより大型で高性能なモデルを使うといったケースです。[`Agent`][agents.Agent] を設定するとき、以下のいずれかの方法で特定のモデルを選択できます。 -1. モデル名を直接渡す。 -2. 任意のモデル名と、それをモデルインスタンスにマッピングできる [`ModelProvider`] を渡す。 -3. [`Model`] 実装を直接提供する。 +1. モデル名を直接渡す。 +2. どのモデル名でも渡し、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`] と [`OpenAIChatCompletionsModel`] の両方の形態をサポートしていますが、ワークフローごとに単一のモデル形態を使用することを推奨します。両モデル形態は利用できる機能やツールのセットが異なるためです。ワークフローでモデル形態を混在させる必要がある場合は、使用するすべての機能が両形態で利用可能かをご確認ください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしますが、ワークフローごとに 1 つのモデル形に統一することを推奨します。2 つの形では利用できる機能や tools が異なるためです。モデル形を混在させる場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -81,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接設定します。 -2. [`Model`] 実装を提供します。 +1. OpenAI モデル名を直接設定しています。 +2. [`Model`][agents.models.interface.Model] 実装を提供しています。 - エージェントで使用するモデルをさらに詳細に設定したい場合は、`temperature` などのオプションパラメーターを含む [`ModelSettings`] を渡すことができます。 +エージェントで使用するモデルをさらに細かく設定したい場合は、`temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -97,7 +97,7 @@ english_agent = Agent( ) ``` - また、OpenAI の Responses API を使用する際には、`user` や `service_tier` など、[その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで利用できない場合は、`extra_args` を使って渡してください。 +また、OpenAI の Responses API を使用する場合は [その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create)（`user`、`service_tier` など）もあります。トップレベルで指定できない場合は、`extra_args` を利用して渡すことができます。 ```python from agents import Agent, ModelSettings @@ -113,27 +113,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー使用時の一般的な問題 +## 他の LLM プロバイダー利用時の一般的な問題 -### Tracing クライアント エラー 401 +### トレーシング クライアント 401 エラー - トレーシングに関連したエラーが発生する場合、トレースが OpenAI サーバーにアップロードされるため、OpenAI API キーが設定されていないことが原因です。解決方法は次の 3 つです: +トレーシング関連のエラーが発生する場合、トレースが OpenAI サーバーにアップロードされる仕組みであり、OpenAI API キーがないことが原因です。解決策は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`] -2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`] - この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) から取得したものである必要があります。 -3. 非 OpenAI のトレースプロセッサーを使用する。詳細は [tracing docs](../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 docs](../tracing.md#custom-tracing-processors) を参照してください。 -### Responses API のサポート +### Responses API サポート - SDK はデフォルトで Responses API を使用しますが、多くの LLM プロバイダーはまだサポートしていません。その結果、404 エラーなどが発生する場合があります。解決策は次の 2 つです: +SDK はデフォルトで Responses API を使用しますが、ほとんどの他社 LLM プロバイダーはまだ対応していません。その結果、404 エラーなどが発生することがあります。対処方法は次の 2 つです。 -1. [`set_default_openai_api("chat_completions")`] を呼び出す。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`] を使用する。コード例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数 `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。code examples は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 -### structured outputs のサポート +### structured outputs サポート - 一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります: +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 ``` @@ -141,12 +140,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` - これは一部のプロバイダーの制限によるもので、JSON 出力には対応していても、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON スキーマ出力をサポートしているプロバイダーを利用することを推奨します。さもないと、アプリが不正な JSON により頻繁に失敗するおそれがあります。 +これは一部プロバイダーの制限で、JSON 出力には対応しているものの、出力に使用する `json_schema` を指定できません。現在修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダーを利用することを推奨します。そうでない場合、壊れた JSON が返され、アプリが頻繁に失敗する可能性があります。 ## プロバイダー間でのモデルの組み合わせ - モデルプロバイダーごとの機能差に注意しないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型 file search や web search をサポートしていますが、多くの他プロバイダーはこれらをサポートしていません。次の制限に注意してください: +モデルプロバイダーごとの機能差を理解しておかないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の file search と web search をサポートしていますが、多くの他社プロバイダーはこれらをサポートしていません。以下の制限に注意してください。 -- サポートしていない `tools` を理解しないプロバイダーには送信しない -- テキストのみのモデルを呼び出す前にマルチモーダル入力を除外する -- structured JSON 出力をサポートしないプロバイダーは、無効な 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 c51bc0eab..e4c914414 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM を通じた任意モデルの利用 +# LiteLLM 経由の任意モデル利用 !!! note - LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題を見つけた場合は、[GitHub issues](https://github.com/openai/openai-agents-python/issues) に報告してください。迅速に対応いたします。 + LiteLLM との統合は現在 beta 版です。特に小規模なモデルプロバイダーでは問題が発生する場合があります。問題を見つけた際は [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に対応いたします。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK では LiteLLM との統合により、あらゆる AI モデルを使用できます。 +[LiteLLM](https://docs.litellm.ai/docs/) は、1 つのインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM との統合を追加したことで、任意の AI モデルを使用できるようになりました。 -## セットアップ +## Setup -`litellm` が利用可能であることを確認してください。オプションの `litellm` 依存関係グループをインストールすることで対応できます。 +`litellm` が利用可能であることを確認する必要があります。オプションの `litellm` 依存グループをインストールすることで設定できます: ```bash pip install "openai-agents[litellm]" ``` -インストールが完了すると、どの エージェント でも [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +インストールが完了すると、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 -## 例 +## Example -以下は完全に動作するコード例です。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます。 +以下は完全に動作する例です。実行するとモデル名と API キーの入力を求められます。例えば、次のように入力できます。 -- `openai/gpt-4.1` をモデルとして指定し、OpenAI API キーを入力 -- `anthropic/claude-3-5-sonnet-20240620` をモデルとして指定し、Anthropic API キーを入力 +- `openai/gpt-4.1` をモデルに指定し、OpenAI API キーを入力 +- `anthropic/claude-3-5-sonnet-20240620` をモデルに指定し、Anthropic API キーを入力 - など -LiteLLM でサポートされているモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) をご覧ください。 +LiteLLM でサポートされているモデルの全リストは [litellm 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 45d62c2b2..7cdebc5a7 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数エージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを実行するか、実行順序、そして次に何を行うかをどのように決定するかということです。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントのフローを指します。どのエージェントがどの順番で実行され、次に何をするかをどう決定するかということです。エージェントをオーケストレーションする主な方法は 2 つあります。 -1. LLM に意思決定を任せる: これは LLM の知能を活用して計画・推論を行い、その結果に基づいて次のステップを決定させる方法です。 -2. コードによるオーケストレーション: コードでエージェントの流れを制御する方法です。 +1. LLM に意思決定させる方法: LLM の知能を利用して計画・推論し、それに基づいて次のステップを決定します。 +2. コードによるオーケストレーション: 自分のコードでエージェントのフローを決定します。 -これらのパターンは組み合わせて使用できます。それぞれにメリットとデメリットがあり、以下で説明します。 +これらのパターンは組み合わせて使用できます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントとは、 instructions、 tools、 handoffs を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM はツールを使ってアクションを実行しデータを取得し、 handoffs でサブエージェントにタスクを委任しながら、自律的にタスクをこなす計画を立てられます。たとえば、リサーチエージェントには次のようなツールを装備できます。 +エージェントとは、instructions、tools、handoffs を備えた LLM です。これにより、オープンエンドなタスクが与えられた場合でも、LLM は自律的に計画を立て、tools を用いてアクションを実行・データを取得し、handoffs でサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のような tools を装備できます。 -- Web 検索によりオンライン情報を取得 -- ファイル検索と取得による社内データや接続先の検索 -- コンピュータ操作でコンピュータ上のアクションを実行 -- コード実行でデータ分析を実施 -- 計画立案やレポート作成などに優れた専門エージェントへの handoffs +- Web 検索でオンライン情報を取得 +- ファイル検索と取得で独自データや接続先を検索 +- コンピュータ操作で PC 上の操作を実行 +- コード実行でデータ分析を行う +- 計画立案やレポート作成に優れた専門エージェントへの handoffs -このパターンはタスクがオープンエンドで、 LLM の知能に依存したい場合に最適です。重要な戦略は次のとおりです。 +このパターンはタスクがオープンエンドで、LLM の知能に頼りたい場合に最適です。重要なポイントは次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、および動作パラメーターを明確に記述します。 -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) を使って、コードで検査可能な適切な形式のデータを生成する。たとえばエージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択します。 +- あるエージェントの出力を次のエージェントの入力へと変換して複数エージェントをチェーンする。ブログ記事作成なら、リサーチ → アウトライン作成 → 記事執筆 → 批評 → 改善という一連のステップに分解できます。 +- タスクを実行するエージェントを `while` ループで回し、評価とフィードバックを行うエージェントが合格と判断するまで繰り返します。 +- `asyncio.gather` など Python の基本コンポーネントで複数エージェントを並列実行する。相互依存のない複数タスクを高速化する際に有効です。 -`examples/agent_patterns` ディレクトリーに複数のコード例があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には多数のコード例があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 77cced861..f79d74523 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -一度だけ実行すれば十分です。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -14,9 +14,9 @@ cd my_project python -m venv .venv ``` -### 仮想環境のアクティブ化 +### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行してください。 +新しいターミナルセッションを開始するたびに実行してください。 ```bash source .venv/bin/activate @@ -28,17 +28,17 @@ source .venv/bin/activate pip install openai-agents # or `uv add openai-agents`, etc ``` -### OpenAI API キーの設定 +### OpenAI API キーを設定する -まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って 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、名前、そして `model_config` などのオプションの 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,14 +93,15 @@ async def main(): print(result.final_output) ``` -## ガードレールの追加 +## ガードレールを追加する -入力または出力に対して実行するカスタム ガードレールを定義できます。 +入力または出力に対して実行するカスタムガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner from pydantic import BaseModel + class HomeworkOutput(BaseModel): is_homework: bool reasoning: str @@ -122,10 +123,11 @@ async def homework_guardrail(ctx, agent, input_data): ## すべてを組み合わせる -これらをすべて組み合わせ、ハンドオフと入力ガードレールを利用してワークフロー全体を実行してみましょう。 +ハンドオフと入力ガードレールを使って、すべてを組み合わせたワークフロー全体を実行してみましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner +from agents.exceptions import InputGuardrailTripwireTriggered from pydantic import BaseModel import asyncio @@ -170,24 +172,32 @@ triage_agent = Agent( ) async def main(): - result = await Runner.run(triage_agent, "who was the first president of the united states?") - print(result.final_output) - - result = await Runner.run(triage_agent, "what is life") - print(result.final_output) + # Example 1: History question + try: + result = await Runner.run(triage_agent, "who was the first president of the united states?") + print(result.final_output) + except InputGuardrailTripwireTriggered as e: + print("Guardrail blocked this input:", e) + + # Example 2: General/philosophical question + try: + result = await Runner.run(triage_agent, "What is the meaning of life?") + print(result.final_output) + except InputGuardrailTripwireTriggered as e: + print("Guardrail blocked this input:", e) if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの表示 +## トレースを表示する -エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動し、実行トレースを表示します。 +エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してエージェント実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう。 +より複雑なエージェントフローを構築する方法を学びましょう: -- [Agents](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 20fd588fe..3f3fe8217 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の realtime 機能を使って音声対応の AI エージェントを構築する方法を詳しく解説します。 +本ガイドでは、 OpenAI Agents SDK の realtime 機能を使用して音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装を改良する過程で互換性が壊れる変更が入る可能性があります。 ## 概要 -Realtime エージェントは、音声とテキスト入力をリアルタイムで処理し、音声で応答する会話フローを実現します。OpenAI の Realtime API と永続的に接続を保ち、低レイテンシで自然な音声対話を可能にし、割り込みにもスムーズに対応します。 +Realtime エージェントは、音声とテキスト入力をリアルタイムに処理し、リアルタイム音声で応答することで対話フローを実現します。 OpenAI の Realtime API と永続的に接続を維持し、低レイテンシで自然な音声会話と割り込みへのスムーズな対応を可能にします。 ## アーキテクチャ -### 主要コンポーネント +### コアコンポーネント -realtime システムは、以下の主要コンポーネントで構成されています。 +リアルタイムシステムは、以下の主要コンポーネントで構成されています。 -- **RealtimeAgent**: instructions、tools、handoffs で設定されるエージェント。 -- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装）。 +- **RealtimeAgent**: instructions、tools、handoffs で構成されるエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出すことでセッションを取得できます。 +- **RealtimeSession**: 1 回の対話セッションを表します。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） ### セッションフロー -典型的な realtime セッションは次のように進行します。 +典型的なリアルタイムセッションは次の流れで進みます。 -1. **RealtimeAgent** を instructions、tools、handoffs で作成します。 -2. **RealtimeRunner** をエージェントと設定オプションでセットアップします。 -3. `await runner.run()` で **セッションを開始** し、RealtimeSession を受け取ります。 -4. `send_audio()` または `send_message()` で **音声またはテキスト** をセッションへ送信します。 -5. セッションを反復処理して **イベントを受信** します。イベントには音声出力、文字起こし、tool 呼び出し、handoff、エラーなどが含まれます。 -6. ユーザーがエージェントの発話を **割り込んだ場合**、現在の音声生成が自動で停止します。 +1. **RealtimeAgent** を instructions、tools、handoffs と共に作成します。 +2. エージェントと各種設定を指定して **RealtimeRunner** をセットアップします。 +3. `await runner.run()` を実行してセッション (**RealtimeSession**) を開始します。 +4. `send_audio()` または `send_message()` を使用して音声またはテキストを送信します。 +5. セッションを反復処理してイベントを受信します。イベントには音声出力、トランスクリプト、ツール呼び出し、ハンドオフ、エラーなどが含まれます。 +6. ユーザーがエージェントの発話中に話し始めた場合は **割り込み** が発生し、現在の音声生成が自動で停止します。 -セッションは会話履歴を保持し、realtime モデルとの永続接続を管理します。 +セッションは会話履歴を保持し、リアルタイムモデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は通常の Agent クラスとほぼ同様に動作しますが、いくつか重要な違いがあります。API の詳細は [`RealtimeAgent`](agents.realtime.agent.RealtimeAgent) リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスとほぼ同じですが、いくつか重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 主な違い: -- モデルの選択はエージェントではなくセッションで設定します。 -- structured outputs（`outputType`）はサポートされません。 -- 声質はエージェントごとに設定できますが、最初のエージェントが発話した後に変更できません。 -- tools、handoffs、instructions などの他の機能は同じ方法で利用できます。 +- モデルの選択はエージェントではなくセッション単位で指定します。 +- structured outputs (`outputType`) はサポートされていません。 +- ボイスはエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、handoffs、instructions などその他の機能は通常のエージェントと同様に機能します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（例: `gpt-4o-realtime-preview`）、声質（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text と/または audio）を指定可能です。音声フォーマットは入力と出力で設定でき、デフォルトは PCM16 です。 +セッション設定では基盤となるリアルタイムモデルの挙動を制御できます。モデル名（`gpt-4o-realtime-preview` など）、ボイス（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text / audio）を指定できます。入力・出力の音声フォーマットは PCM16 がデフォルトですが変更可能です。 -### 音声設定 +### オーディオ設定 -音声設定では、音声入力と出力の扱いを制御します。Whisper などのモデルで入力音声を文字起こししたり、言語を指定したり、専門用語の精度向上のため transcription プロンプトを提供したりできます。ターン検出では、音声検出閾値、無音時間、検出された音声の前後パディングなどを調整して、エージェントがいつ応答を開始・停止すべきかを制御します。 +オーディオ設定では音声入力・出力の扱いを制御します。Whisper などのモデルで音声をトランスクリプトし、言語設定やドメイン固有語の精度を上げる transcription prompt を指定できます。ターン検出では、音声活動検出のしきい値、無音継続時間、検出前後のパディングなどを設定して、エージェントがいつ応答を開始・終了すべきかを調整します。 -## Tools と Functions +## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、realtime エージェントも会話中に実行される function tools をサポートします。 +通常のエージェントと同様に、Realtime エージェントでも会話中に実行される 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**: エージェントの応答音声データ +- **audio**: エージェント応答の raw 音声データ - **audio_end**: エージェントの発話終了 -- **audio_interrupted**: ユーザーによる割り込み -- **tool_start/tool_end**: tool 実行の開始と終了 -- **handoff**: エージェント間の handoff +- **audio_interrupted**: ユーザーによる割り込み発話 +- **tool_start / tool_end**: ツール実行の開始・終了 +- **handoff**: エージェント間のハンドオフ発生 - **error**: 処理中に発生したエラー -詳細は [`RealtimeSessionEvent`](agents.realtime.events.RealtimeSessionEvent) を参照してください。 +詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -Realtime エージェントでは出力ガードレールのみサポートされます。パフォーマンス低下を防ぐため、ガードレールはデバウンスされ、（1 文字ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 +Realtime エージェントでは出力ガードレールのみサポートされます。パフォーマンス維持のため、ガードレールはデバウンスされて定期的に（すべての単語ではなく）評価されます。デフォルトのデバウンス長は 100 文字ですが、変更可能です。 -ガードレールが発火すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答が中断されることがあります。テキストエージェントと違い、Realtime エージェントではガードレール発火時に Exception は発生しません。 +ガードレールが発火すると `guardrail_tripped` イベントが生成され、エージェントの現在の応答が中断される場合があります。リアルタイム性能と安全性を両立させるための挙動です。テキストエージェントと異なり、Realtime エージェントではガードレール発火時に Exception は送出されません。 -## 音声処理 +## オーディオ処理 -[`session.send_audio(audio_bytes)`](agents.realtime.session.RealtimeSession.send_audio) で音声を、[`session.send_message()`](agents.realtime.session.RealtimeSession.send_message) でテキストを送信できます。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] で音声を、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] でテキストをセッションに送信できます。 -音声出力を扱う際は `audio` イベントを受信し、任意の音声ライブラリで再生してください。ユーザーが割り込んだ場合は `audio_interrupted` イベントを検知して、即座に再生を停止し、キューにある音声をクリアする必要があります。 +音声出力を再生するには、`audio` イベントを監視して取得したデータをお好みのオーディオライブラリで再生してください。ユーザーが割り込んだ際には `audio_interrupted` イベントを受信して即座に再生を停止し、キューに溜まった音声をクリアする必要があります。 -## 直接モデルアクセス +## 直接モデルへアクセス -基盤モデルにアクセスして、カスタムリスナーを追加したり高度な操作を行ったりできます。 +より低レベルの制御やカスタムリスナー追加など、高度な用途では基盤モデルへ直接アクセスできます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、低レベルで接続を制御したい高度なユースケース向けに [`RealtimeModel`](agents.realtime.model.RealtimeModel) インターフェースへ直接アクセスできます。 +これにより、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースを直接操作できます。 -## コード例 +## 例 -完全な動作例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。UI あり・なしのデモを含みます。 \ No newline at end of file +動作する完全なサンプルは、[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 7146c4020..cad94d19c 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,35 +4,35 @@ search: --- # クイックスタート -Realtime エージェントを使用すると、OpenAI の Realtime API を介して AI エージェントと音声で対話できます。本ガイドでは、最初の Realtime 音声エージェントを作成する方法を説明します。 +Realtime エージェントを使用すると、OpenAI の Realtime API を介して AI エージェントとの音声会話が可能になります。本ガイドでは、初めてのリアルタイム音声エージェントの作成手順を説明します。 -!!! warning "ベータ機能" -Realtime エージェントは現在ベータ版です。今後の改良に伴い、破壊的変更が発生する可能性があります。 +!!! warning "Beta feature" +Realtime エージェントはベータ版です。実装を改善する過程で破壊的変更が発生する可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 ## インストール -まだインストールしていない場合は、OpenAI Agents SDK をインストールします: +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## 最初の Realtime エージェントの作成 +## 最初のリアルタイム エージェントの作成 -### 1. 必要なコンポーネントをインポート +### 1. 必要なコンポーネントのインポート ```python import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. Realtime エージェントを作成 +### 2. リアルタイム エージェントの作成 ```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`: 利用可能なリアルタイムモデルから選択します（例: `gpt-4o-realtime-preview`） +- `voice`: 音声を選択します (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストおよび／またはオーディオを有効化します (`["text", "audio"]`) ### オーディオ設定 -- `input_audio_format`: 入力音声のフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力音声のフォーマット -- `input_audio_transcription`: 文字起こしの構成 +- `input_audio_format`: 入力オーディオの形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力オーディオの形式 +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声アクティビティのしきい値 (0.0–1.0) -- `silence_duration_ms`: ターン終了を検出するための無音時間 -- `prefix_padding_ms`: 発話前の音声パディング +- `type`: 検出方法 (`server_vad`, `semantic_vad`) +- `threshold`: 音声アクティビティしきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前のオーディオパディング ## 次のステップ -- [Realtime エージェントについて詳しく学ぶ](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダーにある動作する code examples をご覧ください -- エージェントに tools を追加する -- エージェント間の handoffs を実装する -- 安全のための guardrails を設定する +- [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 ca1b1bab7..47f3b5613 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -2,31 +2,31 @@ search: exclude: true --- -# リリースプロセス/変更ログ +# リリースプロセス／変更履歴 -本プロジェクトでは、`0.Y.Z` 形式を用いた、やや変更されたセマンティック バージョニングを採用しています。先頭の `0` は SDK が急速に進化中であることを示します。各コンポーネントの増分ルールは次のとおりです。 +プロジェクトでは、 `0.Y.Z` 形式を用いたセマンティックバージョニングのやや変更されたバージョンを採用しています。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントの増分規則は以下のとおりです。 -## マイナー (`Y`) バージョン +## マイナー ( `Y` ) バージョン -ベータでない公開インターフェースに **破壊的変更** が入る場合、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新に破壊的変更が含まれる可能性があります。 +ベータでない公開インターフェースに **互換性を壊す変更 (breaking changes)** が入る場合、マイナーバージョン `Y` を増やします。たとえば `0.0.x` から `0.1.x` への更新には互換性を壊す変更が含まれることがあります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンを固定して使用することをおすすめします。 +互換性を壊す変更を避けたい場合は、プロジェクトで `0.0.x` 系にバージョンを固定することを推奨します。 -## パッチ (`Z`) バージョン +## パッチ ( `Z` ) バージョン -非破壊的変更の場合は `Z` を増やします。 +互換性を壊さない変更では `Z` を増やします。 - バグ修正 - 新機能 -- プライベート インターフェースの変更 +- プライベートインターフェースの変更 - ベータ機能の更新 -## 破壊的変更の変更ログ +## 互換性を壊す変更の変更履歴 ### 0.2.0 -このバージョンでは、以前 `Agent` を引数に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。例としては MCP サーバーの `list_tools()` 呼び出しがあります。これは型注釈のみの変更であり、受け取るオブジェクトは引き続き `Agent` です。更新の際は、型エラーを修正して `Agent` を `AgentBase` に置き換えてください。 +このバージョンでは、これまで `Agent` を引数に取っていたいくつかの箇所が、代わりに `AgentBase` を引数に取るようになりました。例としては MCP サーバーの `list_tools()` 呼び出しなどです。型に関する変更のみであり、受け取るオブジェクトは引き続き `Agent` です。更新する際は、型エラーを解消するために `Agent` を `AgentBase` に置き換えてください。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` の 2 つの新しいパラメーターが追加されました。`MCPServer` をサブクラス化しているクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーター `run_context` と `agent` が追加されました。`MCPServer` を継承するクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index cf88e6d08..b72953e49 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,4 +18,4 @@ 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 d80dff6b6..5870ac833 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 結果 +# 実行結果 -`Runner.run` メソッドを呼び出すと、戻り値は次のいずれかになります: +`Runner.run` メソッドを呼び出すと、返される値は次のいずれかです。 -- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] -- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult] を返すのは `run` もしくは `run_sync` を呼び出した場合 +- [`RunResultStreaming`][agents.result.RunResultStreaming] を返すのは `run_streamed` を呼び出した場合 -これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに格納されています。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれています。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。内容は次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行された エージェント からの最終出力が入っています。内容は次のいずれかです。 -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト +- 最後の エージェント に `output_type` が定義されていない場合は `str` +- エージェント に `output_type` が定義されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` の型は `Any` です。ハンドオフが発生する可能性があるため、静的型付けはできません。ハンドオフが起こると、どのエージェントが最後になるかは不定であり、可能な出力型の集合を静的に特定できないからです。 + `final_output` の型は `Any` です。ハンドオフが発生する可能性があるため、静的型付けはできません。ハンドオフが起こると、どの エージェント が最後になるか分からないため、可能な出力型の集合を静的に特定できないのです。 -## 次ターンの入力 +## 次のターン用入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使用すると、渡した元の入力とエージェント実行中に生成されたアイテムを結合した input list に変換できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しいユーザー入力を追加したりするときに便利です。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、実行時に生成されたアイテムを元の入力と連結した入力リストに変換できます。これにより、ある エージェント の実行結果をそのまま別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが簡単になります。 -## 最後のエージェント +## 最後に実行されたエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが格納されています。アプリケーションによっては、これは次回ユーザーが入力する際に役立つことがよくあります。たとえば、一次受付のエージェントが言語別のエージェントへハンドオフする場合、最後のエージェントを保存しておき、次にユーザーからメッセージが来た際に再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行された エージェント が入っています。アプリケーションによっては、これは次回 ユーザー が入力を送ってきたときに便利です。たとえば、一次トリアージを行い言語別 エージェント へハンドオフするフロントライン エージェント がいる場合、最後の エージェント を保存しておけば、次回のメッセージで再利用できます。 -## 新しいアイテム +## 新しく生成されたアイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。`RunItem` は LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが入っています。アイテムは [`RunItem`][agents.items.RunItem] でラップされており、その中に LLM が生成した raw アイテムが含まれます。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを表します。raw アイテムは生成されたメッセージです。 - [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツールレスポンスです。アイテムからソース / ターゲットエージェントも取得できます。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツール応答です。また、アイテムからソース / ターゲット エージェント にもアクセスできます。 - [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツールレスポンスです。アイテムからツール出力も取得できます。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツール応答です。また、アイテムからツール出力にもアクセスできます。 - [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 ### ガードレール結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果が含まれます (存在する場合)。ガードレール結果には記録または保存したい有用な情報が含まれることがあるため、ここから取得できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールがあればその結果が格納されます。ガードレール結果にはログ出力や保存に役立つ情報が含まれることがあるため、利用できるようにしています。 -### raw レスポンス +### raw 応答 -[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が格納されています。 +[`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 bdfc8aeae..08ef6d888 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスを通じて実行できます。方法は 3 つあります: +エージェントは [`Runner`][agents.run.Runner] クラスを介して実行できます。方法は 3 つあります: -1. [`Runner.run()`][agents.run.Runner.run] — 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync] — 同期メソッドで、内部的には `.run()` を呼び出します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] — 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリームします。 +1. [`Runner.run()`][agents.run.Runner.run] — 非同期で実行され、 [`RunResult`][agents.result.RunResult] を返します。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync] — 同期メソッドで、内部で `.run()` を呼び出します。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] — 非同期で実行され、 [`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリームします。 ```python from agents import Agent, Runner @@ -20,63 +20,64 @@ async def main(): print(result.final_output) # Code within the code, # Functions calling themselves, - # Infinite loop's dance. + # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) をご覧ください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）を指定できます。 +`Runner` で `run` メソッドを使用すると、開始エージェントと入力を渡します。入力は文字列 (ユーザー メッセージと見なされます) か、OpenAI Responses API のアイテム リストのいずれかです。 -Runner は次のループを実行します: +`Runner` は次のループを実行します: -1. 現在のエージェントと入力を使って LLM を呼び出します。 +1. 現在のエージェントに対して、現在の入力を用いて LLM を呼び出します。 2. LLM が出力を生成します。 - 1. `final_output` を返した場合はループを終了し、結果を返します。 - 2. ハンドオフがある場合は現在のエージェントと入力を更新し、ループを再実行します。 - 3. ツール呼び出しがある場合はツールを実行し、その結果を追加してループを再実行します。 -3. 渡された `max_turns` を超えた場合は [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 + 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 + 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し結果を追加してから、ループを再実行します。 +3. 渡された `max_turns` を超えた場合、 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、求められた型のテキスト出力があり、かつツール呼び出しが存在しないことです。 + LLM の出力が「最終出力」と見なされるルールは、望ましい型のテキスト出力を生成し、ツール呼び出しが 1 つもないことです。 ## ストリーミング -ストリーミングを利用すると、LLM 実行中にストリーミングイベントを受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行の完全な情報（新しい出力を含む）が格納されます。`.stream_events()` を呼び出してストリーミングイベントを取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 +ストリーミングを利用すると、LLM 実行中のイベントを逐次受け取れます。ストリーム終了後、 [`RunResultStreaming`][agents.result.RunResultStreaming] には実行に関する完全な情報 (生成されたすべての新しい出力を含む) が格納されます。ストリーミングイベントは `.stream_events()` で取得できます。詳しくは [ストリーミングガイド](streaming.md) を参照してください。 ## 実行設定 -`run_config` パラメーターでは、エージェントの実行に関するグローバル設定を構成できます: +`run_config` パラメーターを使って、エージェント実行のグローバル設定を行えます: -- [`model`][agents.run.RunConfig.model]: 各 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` は複数の実行間でトレースを関連付けるための任意フィールドです。 +- [`model`][agents.run.RunConfig.model]: 各エージェントの `model` 設定に関わらず、グローバルで使用する LLM モデルを指定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名の検索に用いるモデルプロバイダー。デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。例: グローバルで `temperature` や `top_p` を設定。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に適用する入力または出力ガードレールのリスト。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに入力フィルターが設定されていない場合に適用されるグローバル入力フィルター。新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] を参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体での [トレーシング](tracing.md) を無効にします。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微情報をトレースに含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング用にワークフロー名、トレース ID、グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は複数の実行にわたるトレースをリンクする際に使用できます。 - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータ。 -## 会話／チャットスレッド +## 会話 / チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（＝1 つ以上の LLM 呼び出し）が実行されますが、論理的にはチャット会話の 1 ターンとして扱われます。例: +いずれかの `run` メソッドを呼び出すと、1 つ以上のエージェント (つまり 1 回以上の LLM 呼び出し) が実行されますが、チャット会話の論理的には 1 ターンとして扱われます。例: -1. ユーザーターン: ユーザーがテキストを入力 -2. Runner 実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフ。2 つ目のエージェントがさらにツールを実行し、最終的な出力を生成。 +1. ユーザーのターン: ユーザーがテキストを入力 +2. `Runner` の実行: 最初のエージェントが LLM を呼び出しツールを実行、次に 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(): agent = Agent(name="Assistant", instructions="Reply very concisely.") + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?") @@ -90,9 +91,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 @@ -115,20 +116,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 が送出するすべての例外の基底クラス。 +- [`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 +- [`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 8fae9068c..3529900ce 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 は特定のセッションに対して会話履歴を保存し、明示的な手動メモリー管理なしにコンテキストを維持できるようにします。これは、エージェントが過去の対話を記憶してほしいチャットアプリケーションやマルチターンの会話を構築する際に特に便利です。 +Sessions は特定のセッションの会話履歴を保存し、明示的なメモリ管理を行わなくてもエージェントがコンテキストを維持できるようにします。これは、エージェントに過去のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話を構築する際に特に便利です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリーを有効にすると、次のように動作します。 +セッションメモリを有効にすると、次の処理が行われます。 -1. **各実行の前**: Runner は自動的にそのセッションの会話履歴を取得し、入力アイテムの先頭に追加します。 -2. **各実行の後**: 実行中に生成された新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出しなど) がすべて自動的にセッションに保存されます。 -3. **コンテキスト保持**: 同じセッションでの次回以降の実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 +1. **各実行前**: Runner は自動的にそのセッションの会話履歴を取得し、入力アイテムの先頭に追加します。 +2. **各実行後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）がすべて自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の実行では、完全な会話履歴が含まれるため、エージェントがコンテキストを維持できます。 これにより、`.to_input_list()` を手動で呼び出したり、実行間で会話状態を管理したりする必要がなくなります。 -## メモリー操作 +## メモリ操作 ### 基本操作 -Sessions では会話履歴を管理するために次の操作が利用できます。 +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 @@ -117,16 +117,16 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリーオプション +## メモリオプション -### メモリーなし (デフォルト) +### メモリなし（デフォルト） ```python # Default behavior - no session memory result = await Runner.run(agent, "Hello") ``` -### SQLite メモリー +### SQLite メモリ ```python from agents import SQLiteSession @@ -168,9 +168,9 @@ result2 = await Runner.run( ) ``` -## カスタムメモリー実装 +## カスタムメモリ実装 -独自のセッションメモリーを実装する場合は、[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成します。 +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます。 ````python from agents.memory import Session @@ -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 1570b8076..0a3b6e735 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 response イベント +## raw 応答イベント -`RawResponsesStreamEvent` は、LLM から直接渡される raw なイベントです。OpenAI Responses API フォーマットで提供されるため、各イベントには `response.created` や `response.output_text.delta` などの type とデータが含まれます。生成されたレスポンスメッセージをすぐにユーザーへストリーミングしたい場合に便利です。 +[`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 イベントと agent イベント +## 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 d7d7146e5..72d4f42b9 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールはエージェントがデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作などのアクションを実行できるようにします。Agents SDK には 3 種類のツールがあります: +エージェントはツールを利用することで、データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作まで多彩なアクションを実行できます。Agents SDK には次の 3 つのツールクラスがあります。 -- Hosted ツール: LLM サーバー上で AI モデルと並行して実行されるツールです。OpenAI は retrieval、Web 検索、コンピュータ操作を Hosted ツールとして提供しています。 -- Function calling: 任意の Python 関数をツールとして利用できます。 -- Agents as tools: エージェントをツールとして扱い、ハンドオフせずに他のエージェントを呼び出せるようにします。 +- Hosted ツール: これらは LLM サーバー上で AI モデルと並行して動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を Hosted ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして利用できます。 +- Agents as tools: エージェント自体をツール化することで、ハンドオフすることなくエージェント同士を呼び出せます。 ## Hosted ツール -[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用すると、OpenAI がいくつかの組み込みツールを提供します: +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています。 -- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントによる Web 検索を可能にします。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 -- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルに公開します。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] により、エージェントは Web 検索 を実行できます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 +- [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できます。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルへ公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## Function ツール +## Function tools -任意の Python 関数をツールとして使用できます。Agents SDK がツールの設定を自動で行います: +任意の Python 関数をそのままツールとして利用できます。Agents SDK が自動で設定を行います。 -- ツール名は Python 関数名になります (任意で名前を指定可能) -- ツールの説明は関数の docstring から取得されます (任意で説明を指定可能) -- 関数の引数から入力スキーマを自動生成します -- 各入力の説明は、無効化しない限り docstring から取得します +- ツール名には Python 関数名が使用されます (別名を指定することも可能)。 +- ツール説明は関数の docstring から取得されます (カスタム説明も可)。 +- 関数の引数から自動で入力スキーマを生成します。 +- 各入力の説明は docstring から取得されます (無効化も可能)。 -Python の `inspect` モジュールで関数シグネチャを取得し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを作成します。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`pydantic` でスキーマを生成しています。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、同期・非同期どちらでも構いません。 -2. Docstring があれば、ツールおよび各引数の説明を取得します。 -3. 関数の最初の引数として `context` を受け取ることができます。また、ツール名や説明、docstring スタイルなどを上書き設定できます。 -4. デコレートした関数をツールのリストに渡します。 +1. 引数には任意の Python 型を使用でき、同期／非同期どちらの関数もサポートします。 +2. docstring があれば、ツールおよび引数の説明を取得します。 +3. 関数の最初の引数に `context` を受け取ることができ、ツール名や説明、docstring スタイルなどのオーバーライドも設定可能です。 +4. デコレートした関数を tools のリストに渡すだけで利用できます。 -??? note "出力を表示する" +??? note "出力を展開して表示" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### カスタム Function ツール +### カスタム 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 文字列の引数を受け取り、ツール出力の文字列を返す async 関数 +- `name` +- `description` +- `params_json_schema` ― 引数の JSON スキーマ +- `on_invoke_tool` ― [`ToolContext`][agents.tool_context.ToolContext] と引数(JSON 文字列)を受け取り、ツール出力を文字列で返す async 関数 ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを解析してツールのスキーマを抽出し、docstring からツールおよび個々の引数の説明を取得します。主なポイントは以下のとおりです: +前述のとおり、関数シグネチャを解析してスキーマを生成し、docstring からツール説明や各引数の説明を抽出します。ポイントは以下のとおりです。 -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を把握し、Pydantic モデルを動的に生成して全体のスキーマを表現します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。対応している 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` にすると解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## エージェントをツールとして使用 +## Agents as tools -一部のワークフローでは、制御を委譲せずに中央のエージェントが専門エージェントのネットワークをオーケストレーションしたい場合があります。その際はエージェントをツールとしてモデル化できます。 +ワークフローによっては、複数の専門エージェントを中央のエージェントがオーケストレーションする方が便利な場合があります。その際、エージェントをツールとして扱うことでハンドオフせずに実現できます。 ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツールエージェントのカスタマイズ +### ツール化エージェントのカスタマイズ -`agent.as_tool` はエージェントを簡単にツール化するための便利メソッドですが、すべての設定をサポートしているわけではありません (たとえば `max_turns` は設定できません)。高度なユースケースでは、ツール実装内で `Runner.run` を直接使用してください: +`agent.as_tool` はエージェントを手軽にツール化するためのヘルパーです。ただし `max_turns` などすべての設定をサポートしているわけではありません。高度な構成が必要な場合は、ツール実装内で `Runner.run` を直接呼び出してください。 ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### カスタム出力抽出 +### 出力のカスタム抽出 -場合によっては、ツールエージェントの出力を中央エージェントへ返す前に加工したいことがあります。たとえば以下のようなケースです: +ツール化したエージェントの出力を中央エージェントへ返す前に加工したいケースがあります。たとえば以下のような場合です。 -- サブエージェントのチャット履歴から特定の情報 (例: JSON ペイロード) を抽出する -- エージェントの最終回答を変換または再フォーマットする (例: Markdown をプレーンテキストや CSV に変換) -- 出力を検証し、不足または不正な場合にフォールバック値を提供する +- チャット履歴から特定の情報 (例: JSON ペイロード) のみを抽出したい。 +- Markdown をプレーンテキストや CSV に変換するなど、最終回答のフォーマットを変更したい。 +- レスポンスが欠落・不正な場合に検証やフォールバック値を設定したい。 -そのような場合は `as_tool` メソッドに `custom_output_extractor` 引数を渡します: +`as_tool` メソッドの `custom_output_extractor` 引数に関数を渡すことで実現できます。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -315,12 +315,12 @@ json_tool = data_agent.as_tool( ) ``` -## Function ツールでのエラー処理 +## function ツールでのエラー処理 -`@function_tool` でツールを作成する際、`failure_error_function` を指定できます。この関数はツール呼び出しでクラッシュが発生した場合に LLM へ返すエラー応答を生成します。 +`@function_tool` でツールを作成する際、`failure_error_function` を指定できます。これはツール呼び出しが失敗した場合に LLM へ返すエラーメッセージを生成する関数です。 -- 何も渡さなかった場合、デフォルトで `default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 -- 独自のエラー関数を渡した場合は、その関数が実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡すと、ツール呼び出しのエラーが再スローされ、呼び出し元で処理できます。たとえば、モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになります。 +- 何も渡さなかった場合、デフォルトの `default_tool_error_function` が実行され、「エラーが発生した」と LLM へ通知します。 +- 独自のエラー関数を渡すと、それが実行され LLM へ送信されます。 +- 明示的に `None` を渡すと、ツール呼び出し時のエラーは再スローされ、呼び出し側で処理できます。たとえばモデルが無効な JSON を生成した場合は `ModelBehaviorError`、ユーザーコードがクラッシュした場合は `UserError` などです。 -`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 3ef44165f..5e19f19a2 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK には、エージェント実行中に発生するイベント ( LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベント) を網羅的に記録する組み込みのトレーシング機能が含まれています。 [Traces dashboard](https://platform.openai.com/traces) を使用すると、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生する LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントなどの詳細なイベント記録を収集します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。 + トレーシングはデフォルトで有効になっています。無効化する方法は 2 つあります。 - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化する - 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する + 2. 単一の実行で無効化する場合は [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する -***OpenAI の API を使用し Zero Data Retention ( ZDR ) ポリシーの下で運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 1 つのワークフローにおけるエンドツーエンドの操作を表します。複数のスパンで構成され、以下のプロパティを持ちます。 - - `workflow_name` : 論理的なワークフローまたはアプリ名。例: 「コード生成」や「カスタマー サービス」 - - `trace_id` : トレースの一意 ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id` : 省略可。会話内の複数トレースをリンクするグループ ID。たとえばチャットスレッド ID などに利用できます。 - - `disabled` : `True` の場合、このトレースは記録されません。 - - `metadata` : 省略可のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次のものがあります。 - - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを示す `trace_id` - - 親スパンを指す `parent_id` (存在する場合) - - スパンに関する情報を含む `span_data` 。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など +- **トレース** は 1 つのワークフローのエンドツーエンド操作を表します。トレースは複数のスパンで構成されます。トレースのプロパティは次のとおりです。 + - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 + - `trace_id`: トレースの一意 ID。渡さなかった場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: オプションのグループ ID。同じ会話からの複数トレースをリンクするために使用します。例としてチャットスレッド ID など。 + - `disabled`: `True` の場合、このトレースは記録されません。 + - `metadata`: トレースに付与するオプションメタデータ。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンのプロパティは次のとおりです。 + - `started_at` と `ended_at` タイムスタンプ + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id` (存在する場合) + - スパンに関する情報を含む `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など。 ## デフォルトのトレーシング -デフォルトでは、SDK は以下をトレースします。 +デフォルトでは、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_span()` でラップ +- ガードレールを `guardrail_span()` でラップ +- ハンドオフを `handoff_span()` でラップ +- 音声入力 (speech-to-text) を `transcription_span()` でラップ +- 音声出力 (text-to-speech) を `speech_span()` でラップ +- 関連する音声スパンは `speech_group_span()` の下にネストされることがあります -デフォルトのトレース名は「Agent trace」です。`trace` を使用する際にこの名前を設定することも、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 +デフォルトではトレース名は「Agent trace」です。`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,60 +64,60 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `with trace()` で 2 回の `Runner.run` をラップしているため、それぞれの実行は個別にトレースを作成せず、全体トレースに含まれます。 +1. `Runner.run` への 2 回の呼び出しが `with trace()` 内にラップされているため、個々の実行は 2 つのトレースを作成せず、全体トレースの一部になります。 ## トレースの作成 -トレースは [`trace()`][agents.tracing.trace] 関数で作成できます。開始と終了が必要で、方法は 2 つあります。 +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります。 -1. **推奨**: コンテキストマネージャとして使用する ( 例: `with trace(...) as my_trace` ) 。これにより、トレースの開始と終了が自動で行われます。 -2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出す。 +1. **推奨**: コンテキストマネージャとして使用する (例: `with trace(...) as my_trace`)。これにより開始と終了が自動化されます。 +2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すことも可能です。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されるため、並行処理に自動対応します。トレースを手動で開始／終了する場合は、`start()` / `finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新してください。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。これにより並行処理でも自動的に機能します。トレースを手動で開始／終了する場合は、`start()`／`finish()` に `mark_as_current` と `reset_current` を渡して現在のトレースを更新してください。 ## スパンの作成 -各種 [`*_span()`][agents.tracing.create] メソッドでスパンを作成できます。通常、スパンを手動で作成する必要はありませんが、カスタム情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も用意されています。 +各種 [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。通常は手動でスパンを作成する必要はありません。カスタムスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] も用意されています。 -スパンは自動で現在のトレースに属し、最も近い現在のスパンの下にネストされます。この情報も Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 +スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。これも Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で管理されます。 ## 機微なデータ -一部のスパンでは機微なデータを取得する可能性があります。 +一部のスパンは機微なデータを含む可能性があります。 -`generation_span()` は LLM 生成の入力／出力を、`function_span()` は関数呼び出しの入力／出力を保存します。これらに機微なデータが含まれる場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使って取得を無効化できます。 +`generation_span()` は LLM 生成の入出力を、`function_span()` は関数呼び出しの入出力を保存します。これらに機微なデータが含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でデータの取得を無効化できます。 -同様に、オーディオ スパンには入力／出力オーディオの base64 エンコード PCM データがデフォルトで含まれます。これを無効にする場合は、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定してください。 +同様に、オーディオスパンはデフォルトで入力・出力オーディオの base64 エンコード PCM データを含みます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、このオーディオデータの取得を無効化できます。 -## カスタム トレース プロセッサ +## カスタムトレーシングプロセッサ -トレーシングの高レベル アーキテクチャは以下のとおりです。 +トレーシングの高レベルアーキテクチャは次のとおりです。 -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を生成し、トレースの作成を担当します。 -- `TraceProvider` は [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を使用してトレース／スパンをバッチ送信し、[`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] が OpenAI バックエンドへバッチでエクスポートします。 +- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、トレースの生成を担当します。 +- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、スパンとトレースをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、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) -- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) -- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) -- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) -- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) -- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) -- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) -- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) -- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) -- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) -- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) -- [Okahu-Monocle](https://github.com/monocle2ai/monocle) -- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) -- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) \ No newline at end of file +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) +- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) +- [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) +- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) +- [Scorecard](https://docs.scorecard.io/docs/documentation/features/tracing#openai-agents-sdk-integration) +- [Keywords AI](https://docs.keywordsai.co/integration/development-frameworks/openai-agent) +- [LangSmith](https://docs.smith.langchain.com/observability/how_to_guides/trace_with_openai_agents_sdk) +- [Maxim AI](https://www.getmaxim.ai/docs/observe/integrations/openai-agents-sdk) +- [Comet Opik](https://www.comet.com/docs/opik/tracing/integrations/openai_agents) +- [Langfuse](https://langfuse.com/docs/integrations/openaiagentssdk/openai-agents) +- [Langtrace](https://docs.langtrace.ai/supported-integrations/llm-frameworks/openai-agents-sdk) +- [Okahu-Monocle](https://github.com/monocle2ai/monocle) +- [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) +- [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 0a2e54e0a..fdbd268dd 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` 関数を使用してエージェントの可視化を生成できます。この関数は有向グラフを作成し、次のように表現します: -- **エージェント** は黄色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジで示されます。 +- ** エージェント ** は黄色のボックスで表示されます。 +- ** ツール ** は緑色の楕円で表示されます。 +- ** ハンドオフ ** は一方のエージェントから別のエージェントへの有向エッジで示されます。 ### 使用例 @@ -52,33 +52,34 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![エージェントグラフ](../assets/images/graph.png) + +これにより、 ** triage agent ** の構造とサブエージェントおよびツールへの接続を視覚的に表現したグラフが生成されます。 -これにより、**triage agent** の構造とサブエージェント、ツールとの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 生成されたグラフには次の要素が含まれます: -- エントリポイントを示す **start ノード** (`__start__`) -- 黄色で塗りつぶされた **長方形** のエージェント -- 緑色で塗りつぶされた **楕円** のツール +- エントリーポイントを示す ** start ノード ** ( `__start__` ) +- 黄色で塗りつぶされた ** 四角形 ** で示されるエージェント +- 緑色で塗りつぶされた ** 楕円 ** で示されるツール - 相互作用を示す有向エッジ - - エージェント間のハンドオフには **実線の矢印** - - ツール呼び出しには **点線の矢印** -- 実行が終了する場所を示す **end ノード** (`__end__`) + - エージェント間のハンドオフには ** 実線矢印 ** + - ツール呼び出しには ** 破線矢印 ** +- 実行終了地点を示す ** end ノード ** ( `__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 97d13a0ea..7cb9374e3 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -`VoicePipeline` は、 エージェント ワークフローを音声アプリへ簡単に変換できるクラスです。実行したいワークフローを渡すだけで、パイプラインが入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ戻す処理を自動で行います。 +` VoicePipeline ` クラスは、エージェントワークフローを音声アプリに簡単に組み込めます。ワークフローを渡すと、入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声へ変換する処理をパイプラインが自動で行います。 ```mermaid graph LR @@ -34,33 +34,37 @@ 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] — エラーイベントです。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] + 音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] + ターンの開始・終了などライフサイクルイベントを通知します。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] + エラーイベントです。 ```python @@ -80,4 +84,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK には現時点で [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートがありません。検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内部で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が始まったことを示し、`turn_ended` は該当ターンの音声がすべて送信された後に発火します。これらのイベントを利用して、モデルがターンを開始した際に話者のマイクをミュートし、そのターンに関する音声をすべて出力し終えたらアンミュートする、といった制御が可能です。 \ No newline at end of file +Agents SDK には現在、` StreamedAudioInput ` に対する組み込みの割り込みサポートはありません。検出された各ターンごとにワークフローが個別に実行されます。アプリケーション内で割り込みを処理したい場合は、` 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 2e7facbfe..c24b92b40 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,19 +6,19 @@ search: ## 前提条件 - Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしてください。その後、SDK の音声オプション依存関係をインストールします。 +まず、 Agents SDK の基本クイックスタート手順に従い、仮想環境をセットアップしてください。その後、SDK から音声用のオプション依存関係をインストールします: ```bash pip install 'openai-agents[voice]' ``` -## コンセプト +## 基本概念 -理解しておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、次の 3 ステップを実行します。 +押さえておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、次の 3 ステップから成るプロセスです: 1. 音声をテキストに変換する speech-to-text モデルを実行します。 2. 通常はエージェント的ワークフローであるあなたのコードを実行し、結果を生成します。 -3. 結果のテキストを再び音声に変換する text-to-speech モデルを実行します。 +3. 結果のテキストを音声に戻す text-to-speech モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定しましょう。すでにこの SDK でエージェントを構築したことがある場合は、おなじみのはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。すでにこの SDK でエージェントを構築したことがあれば、馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、ツールを用意します。 ```python import asyncio @@ -90,9 +90,9 @@ agent = Agent( ) ``` -## Voice パイプライン +## 音声パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな Voice パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインをセットアップします。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめて実行する +## 統合例 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに向かって話します。自分でエージェントと会話できるデモは [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) にありますので、ぜひご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話しかけてくれます。実際に自分でエージェントと会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index f2d1093e2..e8dbda2a9 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -6,13 +6,13 @@ search: [エージェントがトレーシングされる方法](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントを参照できますが、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを追加で設定することも可能です。 +トレーシングの基本情報については上記のドキュメントをご覧ください。また、 `VoicePipelineConfig` を使用してパイプラインのトレーシングを追加で設定できます。 -トレーシングに関連する主なフィールドは次のとおりです: +主なトレーシング関連フィールドは次のとおりです。 -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに音声の書き起こしなどの機微情報を含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われる処理には影響しません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース ワークフローの名前です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための `group_id` です。 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機微情報をトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、 Workflow 内の処理には影響しません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースワークフローの名前です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための `group_id` です。 - [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに追加するメタデータです。 \ No newline at end of file