diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 828b36355..4a6bc16ec 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,15 +4,16 @@ search: --- # エージェント -エージェントはアプリの主要な構成ブロックです。エージェントは、大規模言語モデル ( LLM ) に instructions と tools を設定したものです。 +エージェントはアプリの中心的な構成要素です。エージェントは、instructions と tools で設定された大規模言語モデル ( LLM ) です。 ## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +エージェントでよく設定するプロパティは次のとおりです。 -- `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 @@ -31,7 +32,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型について汎用的です。コンテキストは依存性注入の手段で、`Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行時の依存関係や状態をまとめて保持します。任意の Python オブジェクトをコンテキストとして渡せます。 +エージェントは汎用的な `context` 型を取ります。コンテキストは依存性注入用のツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、tool、handoff などに渡され、実行時に必要な依存関係や状態を格納する入れ物として機能します。コンテキストには任意の 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、list、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 を使用するよう指示されます。 ## ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡しておくと、エージェントは必要に応じてそれらに処理を委譲できます。これにより、単一のタスクに特化したモジュール式エージェントを編成できる強力なパターンが実現します。詳細は [handoffs](handoffs.md) ドキュメントをご覧ください。 +ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフのリストを渡すと、エージェントは関連性がある場合にそれらへ委譲できます。これは、単一タスクに特化したモジュール型エージェントを編成する強力なパターンです。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -95,7 +96,7 @@ triage_agent = Agent( ## 動的 instructions -通常はエージェント作成時に instructions を指定しますが、関数を介して動的に instructions を提供することもできます。その関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数と `async` 関数の両方に対応しています。 +通常はエージェント作成時に instructions を渡しますが、関数を通じて動的に instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。同期関数でも `async` 関数でも利用可能です。 ```python def dynamic_instructions( @@ -112,15 +113,15 @@ 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] を設定することでツール使用を強制できます。有効な値は次のとおりです。 +tools のリストを渡しても、LLM が必ずツールを使用するわけではありません。`ModelSettings.tool_choice` を設定することでツール使用を強制できます。設定可能な値は次のとおりです。 -1. `auto` — ツールを使用するかどうかを LLM が判断します。 -2. `required` — LLM にツール使用を必須化します ( ただし使用するツールは自動選択 )。 -3. `none` — LLM にツールを使用しないことを要求します。 -4. 特定の文字列 ( 例: `my_tool` ) — その特定のツールを LLM に使用させます。 +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` により再びツール呼び出しが生成されるというサイクルが続くためです。 - ツール呼び出し後にエージェントを完全に停止させたい場合 ( 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..193045490 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、 SDK はインポートされた時点で LLM リクエストとトレーシングに使用する `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にこの環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を利用してキーを設定できます。 +デフォルトでは、 SDK はインポートされるとすぐに LLM リクエストとトレーシング用に `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、 [set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを構成することも可能です。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `AsyncOpenAI` インスタンスを作成します。これを変更するには、 [set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAIクライアントを設定することもできます。デフォルトでは、 SDK は環境変数または上記で設定したデフォルトキーを用いて `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 @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## トレーシング -トレーシングはデフォルトで有効になっています。前述の OpenAI API キー（環境変数または設定したデフォルトキー）が自動的に使用されます。トレーシングで使用する API キーを個別に設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を利用してください。 +トレーシングはデフォルトで有効になっています。上記セクションの OpenAI API キー (環境変数または設定済みのデフォルトキー) が自動的に使用されます。トレーシング専用の API キーを設定したい場合は、 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用してください。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -トレーシングを完全に無効化するには、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を呼び出します。 +トレーシングを完全に無効化したい場合は、 [`set_tracing_disabled()`][agents.set_tracing_disabled] 関数を使用できます。 ```python from agents import set_tracing_disabled @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## デバッグログ - 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 ロギングガイド](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..77eae1e81 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという言葉には複数の意味があります。ここでは主に 2 つのコンテキストについて説明します。 +コンテキストという用語は多義的です。ここでは主に 2 つのコンテキスト クラスがあります。 -1. コード内でローカルに利用できるコンテキスト: ツール関数の実行時や `on_handoff` などのコールバック、ライフサイクルフックで必要となるデータや依存関係です。 -2. LLM が参照できるコンテキスト: LLM がレスポンスを生成する際に見えるデータです。 +1. コード内でローカルに利用できるコンテキスト: これはツール関数の実行時や `on_handoff` などのコールバック、ライフサイクル フック内で必要となるデータや依存関係です。 +2. LLM が利用できるコンテキスト: これは LLM が応答を生成する際に参照できるデータです。 -## ローカルコンテキスト +## ローカル コンテキスト -ローカルコンテキストは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 +ローカル コンテキストは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。基本的な流れは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的なパターンとして dataclass や Pydantic オブジェクトを使用します。 -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` からアクセスできます。 -**最重要ポイント**: あるエージェントの実行において、エージェント・ツール関数・ライフサイクルフックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 +**最も重要な点**: ひとつのエージェント実行において、エージェント・ツール関数・ライフサイクル フックなどはすべて同じ _型_ のコンテキストを使用しなければなりません。 -コンテキストでは次のような用途が考えられます。 +コンテキストは次のような用途に利用できます。 -- 実行に関するデータ（例: ユーザー名 / uid やその他のユーザー情報） -- 依存オブジェクト（例: ロガー、データフェッチャーなど） -- ヘルパー関数 +- 実行に関するコンテキスト データ（例: ユーザー名 / UID などのユーザー情報） +- 依存関係（例: ロガー オブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは LLM には送信されません。あくまでローカルのオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキスト オブジェクトは **LLM に送信されません**。あくまでローカル オブジェクトであり、読み書きやメソッド呼び出しが可能です。 ```python import asyncio @@ -42,7 +42,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 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装内でコンテキストを参照しています。 -3. エージェントにジェネリック `UserInfo` を付与することで、型チェッカーが誤りを検出できます（たとえば別のコンテキスト型を受け取るツールを渡した場合など）。 +1. これはコンテキスト オブジェクトです。ここでは dataclass を使用していますが、任意の型を利用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることが分かります。ツール実装はコンテキストからデータを読み取ります。 +3. エージェントにジェネリック型 `UserInfo` を指定し、型チェッカーがエラーを検出できるようにしています（例: 異なるコンテキスト型を取るツールを渡そうとした場合など）。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント / LLM コンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴に含まれるものだけです。したがって、新しいデータを LLM に渡したい場合は、そのデータを履歴に含める形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴からのみ取得されます。そのため、新しいデータを LLM に渡したい場合は、履歴に含める形で提供する必要があります。主な方法は以下のとおりです。 -1. 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. エージェントの `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 00f634ec1..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 の基礎的な機能を示す例です。 + ここでは、以下のような SDK の基礎的な機能を紹介しています。例: - - 動的なシステムプロンプト - - ストリーミング出力 - - ライフサイクルイベント + - 動的なシステムプロンプト + - ストリーミング出力 + - ライフサイクルイベント - **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** Web 検索やファイル検索など、 OpenAI がホストするツールの実装方法と、それらをエージェントに統合する方法を学べます。 - **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを SDK で利用する方法を探ります。 + OpenAI 以外のモデルを SDK と併用する方法を探求できます。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフを実践的に示す例です。 + エージェントのハンドオフに関する実践的なコード例です。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP を使ったエージェントの構築方法を学べます。 + MCP を用いたエージェントの構築方法を学べます。 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service)** と **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - より実践的なユースケースを示す、拡張された 2 つの例です。 + 実際のユースケースを想定した、より充実した 2 つのコード例 - - **customer_service**: 航空会社向けカスタマーサービスシステムの例 - - **research_bot**: シンプルなディープリサーチクローン + - **customer_service**: 航空会社向けのカスタマーサービスシステム例 + - **research_bot**: シンプルなディープリサーチ クローン - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS と STT モデルを用いた音声エージェントの例をご覧ください。 \ 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..4b20832c1 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは エージェント と _並行して_ 実行され、ユーザー入力のチェックとバリデーションを行えます。例えば、とても賢い（つまり遅く/高価な）モデルを使用してカスタマーリクエストを処理するエージェントがあるとします。悪意のある ユーザー がモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、速く/安価なモデルで動くガードレールを実行できます。ガードレールが悪意のある利用を検知すると、直ちにエラーを送出して高価なモデルの実行を停止し、時間とコストを節約できます。 +ガードレール は エージェント と _並行して_ 実行され、ユーザー 入力のチェックおよびバリデーションを行えます。たとえば、とても賢い（つまり遅く / 高価な）モデルを使ってカスタマーリクエストを処理する エージェント があるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、速く / 安価なモデルでガードレールを実行できます。ガードレールが悪意のある利用を検出した場合、直ちにエラーを送出し、高価なモデルの実行を停止して時間とコストを節約します。 ガードレールには 2 種類あります: -1. 入力ガードレール は初期 ユーザー 入力に対して実行されます -2. 出力ガードレール は最終的なエージェント出力に対して実行されます +1. 入力ガードレール は最初のユーザー入力で実行されます +2. 出力ガードレール は最終的なエージェントの出力で実行されます ## 入力ガードレール 入力ガードレールは 3 ステップで実行されます: 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップします。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理を行えます。 !!! Note - 入力ガードレールは ユーザー 入力に対して実行されることを意図しているため、ガードレールは *最初* のエージェントでのみ実行されます。「なぜ `guardrails` プロパティがエージェントにあり、`Runner.run` に渡さないのか」と疑問に思うかもしれません。これは、ガードレールが実際の エージェント と密接に関連していることが多いからです。異なるエージェントには異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントが *最初の* エージェントの場合にのみ実行されます。「guardrails」プロパティをエージェントに持たせるのではなく `Runner.run` に渡す形にしない理由は？ガードレールは実際のエージェントと密接に関連していることが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置く方が可読性に優れるからです。 ## 出力ガードレール 出力ガードレールは 3 ステップで実行されます: 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 -3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップします。 +3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理を行えます。 !!! Note - 出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、ガードレールは *最後* のエージェントでのみ実行されます。入力ガードレールの場合と同様、ガードレールが実際の エージェント と密接に関連していることが多いため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントが *最後の* エージェントの場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントと密接に関連しているため、コードを同じ場所に置く方が可読性に優れます。 -## トリップワイヤー +## トリップワイヤ -入力または出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤーでそれを示すことができます。トリップワイヤーがトリガーされたガードレールを検知した時点で、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力あるいは出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤでその旨を通知できます。トリップワイヤが起動したガードレールを検出するとすぐに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。この例では、内部で エージェント を実行してこれを行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行してこれを行います。 ```python from pydantic import BaseModel @@ -95,8 +95,8 @@ async def main(): ``` 1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果に追加情報を含めることができます。 +2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレール結果に追加情報を含めることもできます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -155,4 +155,4 @@ async def main(): 1. これは実際のエージェントの出力型です。 2. これはガードレールの出力型です。 3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file +4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index c0e99556e..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 @@ -59,7 +59,7 @@ 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` を設定してください。入力フィルターは `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..e077c29aa 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](https://github.com/openai/openai-agents-python) は、非常に少ない抽象化で軽量かつ使いやすいパッケージとして、エージェント指向の AI アプリを構築できるツールです。これは、以前のエージェント向け実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を、本番環境向けにアップグレードしたものです。Agents SDK にはごく少数の基本コンポーネントがあります。 - **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: エージェントが特定タスクを他のエージェントへ委任するしくみ -- **ガードレール**: エージェントへの入力を検証する機能 +- **ハンドオフ**: 特定タスクを他のエージェントへ委任する仕組み +- **ガードレール**: エージェントへの入力を検証する仕組み +- **セッション**: エージェント実行間で会話履歴を自動的に保持 -Python と組み合わせることで、これらのコンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストを抑えつつ実際のアプリケーションを構築できます。さらに SDK には、エージェントフローを可視化・デバッグできる **トレーシング** が標準搭載されており、評価やファインチューニングにも活用可能です。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実用的なアプリケーションを構築できます。さらに、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 の評価、ファインチューニング、蒸留ツールも利用可能。 ## インストール @@ -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..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 は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションにとっての USB‑C ポートのようなものと考えてください。USB‑C が各種デバイスを周辺機器と接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールと接続するための標準化された方法を提供します。 +> 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 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()` を呼び出し、 LLM に MCP サーバーのツールを認識させます。 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 サーバーは、agent instructions を動的に生成できるプロンプトも提供します。これにより、パラメーターでカスタマイズ可能な再利用可能な instruction テンプレートを作成できます。 + +### プロンプトの利用 + +プロンプトをサポートする 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()` を呼び出します。 -## エンドツーエンドのコード例 +## 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 410c01676..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`][agents.models.openai_responses.OpenAIResponsesModel] は、新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は、[Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] — 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] — [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。 ## 非 OpenAI モデル -ほとんどの非 OpenAI モデルは [LiteLLM インテグレーション](./litellm.md) 経由で利用できます。まず、litellm 依存グループをインストールします: +ほとんどの非 OpenAI モデルは [LiteLLM インテグレーション](./litellm.md) 経由で利用できます。まず、litellm 依存グループをインストールしてください。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` 接頭辞を付けて任意の [サポート対象モデル](https://docs.litellm.ai/docs/providers) を使用します: +その後、`litellm/` プレフィックスを付けて [サポートされているモデル](https://docs.litellm.ai/docs/providers) を指定します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) @@ -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/) に code examples あり）。 -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`][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 - これらの例では、Responses API をまだサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 + + これらの例では Chat Completions API/モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーが Responses API をサポートしている場合は、Responses を使用することを推奨します。 ## モデルの組み合わせ -1 つのワークフロー内でエージェントごとに異なるモデルを使用したい場合があります。たとえば、振り分けには小さく高速なモデルを、複雑なタスクには大きく高性能なモデルを使用するといったケースです。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法でモデルを選択できます。 +1 つのワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、トリアージにはより小さく高速なモデルを使い、複雑なタスクにはより大型で高性能なモデルを使うといったケースです。[`Agent`][agents.Agent] を設定するとき、以下のいずれかの方法で特定のモデルを選択できます。 -1. モデル名を直接指定する -2. 任意のモデル名と、その名前を Model インスタンスへマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を指定する -3. [`Model`][agents.models.interface.Model] 実装を直接渡す +1. モデル名を直接渡す。 +2. どのモデル名でも渡し、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両形態をサポートしていますが、各ワークフローで 1 つのモデル形態に統一することを推奨します。2 つの形態はサポートする機能とツールが異なるためです。混在させる場合は、使用する機能が双方で利用可能かを必ず確認してください。 + + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしますが、ワークフローごとに 1 つのモデル形に統一することを推奨します。2 つの形では利用できる機能や tools が異なるためです。モデル形を混在させる場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -82,10 +81,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接設定 -2. [`Model`][agents.models.interface.Model] 実装を提供 +1. OpenAI モデル名を直接設定しています。 +2. [`Model`][agents.models.interface.Model] 実装を提供しています。 -エージェントで使用するモデルをさらに構成したい場合は、`temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 +エージェントで使用するモデルをさらに細かく設定したい場合は、`temperature` などのオプションパラメーターを指定できる [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -98,7 +97,7 @@ english_agent = Agent( ) ``` -OpenAI の Responses API を使用する場合、`user` や `service_tier` など[その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create) があります。トップレベルで指定できない場合は、`extra_args` で渡してください。 +また、OpenAI の Responses API を使用する場合は [その他のオプションパラメーター](https://platform.openai.com/docs/api-reference/responses/create)（`user`、`service_tier` など）もあります。トップレベルで指定できない場合は、`extra_args` を利用して渡すことができます。 ```python from agents import Agent, ModelSettings @@ -114,27 +113,24 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー使用時の一般的な問題 +## 他の LLM プロバイダー利用時の一般的な問題 -### Tracing クライアントの 401 エラー +### トレーシング クライアント 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) を参照してください。 +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")`][agents.set_default_openai_api] を呼び出す - `OPENAI_API_KEY` と `OPENAI_BASE_URL` を環境変数で設定している場合に有効です。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する - 例は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは環境変数 `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。code examples は [こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 -### structured outputs のサポート +### structured outputs サポート 一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。その場合、次のようなエラーが発生することがあります。 @@ -144,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 651d7a51b..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/) は、1 つのインターフェースで 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 a179fed36..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、ツール、ハンドオフを備えた LLM です。オープンエンドなタスクが与えられた場合、 LLM はタスクをどのように進めるかを自律的に計画し、ツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントへタスクを委譲できます。たとえば、リサーチエージェントには次のようなツールを装備できます。 +エージェントとは、instructions、tools、handoffs を備えた LLM です。これにより、オープンエンドなタスクが与えられた場合でも、LLM は自律的に計画を立て、tools を用いてアクションを実行・データを取得し、handoffs でサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のような tools を装備できます。 -- Web 検索でオンライン情報を取得する -- ファイル検索で独自データや接続を調べる -- コンピュータ操作でコンピュータ上のアクションを実行する +- 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`](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 30c3219d7..f79d74523 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ行えば十分です。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -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 @@ -120,12 +121,13 @@ 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.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 new file mode 100644 index 000000000..3f3fe8217 --- /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 と永続的に接続を維持し、低レイテンシで自然な音声会話と割り込みへのスムーズな対応を可能にします。 + +## アーキテクチャ + +### コアコンポーネント + +リアルタイムシステムは、以下の主要コンポーネントで構成されています。 + +- **RealtimeAgent**: instructions、tools、handoffs で構成されるエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出すことでセッションを取得できます。 +- **RealtimeSession**: 1 回の対話セッションを表します。ユーザーが会話を開始するたびに作成し、会話が終了するまで保持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） + +### セッションフロー + +典型的なリアルタイムセッションは次の流れで進みます。 + +1. **RealtimeAgent** を instructions、tools、handoffs と共に作成します。 +2. エージェントと各種設定を指定して **RealtimeRunner** をセットアップします。 +3. `await runner.run()` を実行してセッション (**RealtimeSession**) を開始します。 +4. `send_audio()` または `send_message()` を使用して音声またはテキストを送信します。 +5. セッションを反復処理してイベントを受信します。イベントには音声出力、トランスクリプト、ツール呼び出し、ハンドオフ、エラーなどが含まれます。 +6. ユーザーがエージェントの発話中に話し始めた場合は **割り込み** が発生し、現在の音声生成が自動で停止します。 + +セッションは会話履歴を保持し、リアルタイムモデルとの永続接続を管理します。 + +## エージェント設定 + +RealtimeAgent は通常の Agent クラスとほぼ同じですが、いくつか重要な違いがあります。詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API リファレンスをご覧ください。 + +主な違い: + +- モデルの選択はエージェントではなくセッション単位で指定します。 +- structured outputs (`outputType`) はサポートされていません。 +- ボイスはエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、handoffs、instructions などその他の機能は通常のエージェントと同様に機能します。 + +## セッション設定 + +### モデル設定 + +セッション設定では基盤となるリアルタイムモデルの挙動を制御できます。モデル名（`gpt-4o-realtime-preview` など）、ボイス（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（text / audio）を指定できます。入力・出力の音声フォーマットは PCM16 がデフォルトですが変更可能です。 + +### オーディオ設定 + +オーディオ設定では音声入力・出力の扱いを制御します。Whisper などのモデルで音声をトランスクリプトし、言語設定やドメイン固有語の精度を上げる transcription prompt を指定できます。ターン検出では、音声活動検出のしきい値、無音継続時間、検出前後のパディングなどを設定して、エージェントがいつ応答を開始・終了すべきかを調整します。 + +## ツールと関数 + +### ツールの追加 + +通常のエージェントと同様に、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**: エージェント応答の raw 音声データ +- **audio_end**: エージェントの発話終了 +- **audio_interrupted**: ユーザーによる割り込み発話 +- **tool_start / tool_end**: ツール実行の開始・終了 +- **handoff**: エージェント間のハンドオフ発生 +- **error**: 処理中に発生したエラー + +詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 + +## ガードレール + +Realtime エージェントでは出力ガードレールのみサポートされます。パフォーマンス維持のため、ガードレールはデバウンスされて定期的に（すべての単語ではなく）評価されます。デフォルトのデバウンス長は 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..cad94d19c --- /dev/null +++ b/docs/ja/realtime/quickstart.md @@ -0,0 +1,179 @@ +--- +search: + exclude: true +--- +# クイックスタート + +Realtime エージェントを使用すると、OpenAI の Realtime API を介して AI エージェントとの音声会話が可能になります。本ガイドでは、初めてのリアルタイム音声エージェントの作成手順を説明します。 + +!!! warning "Beta feature" +Realtime エージェントはベータ版です。実装を改善する過程で破壊的変更が発生する可能性があります。 + +## 前提条件 + +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 + +## インストール + +まだインストールしていない場合は、OpenAI Agents SDK をインストールしてください: + +```bash +pip install openai-agents +``` + +## 最初のリアルタイム エージェントの作成 + +### 1. 必要なコンポーネントのインポート + +```python +import asyncio +from agents.realtime import RealtimeAgent, RealtimeRunner +``` + +### 2. リアルタイム エージェントの作成 + +```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`: 利用可能なリアルタイムモデルから選択します（例: `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) フォルダーにある動作するコード例を確認してください +- エージェントにツールを追加する +- エージェント間のハンドオフを実装する +- 安全性のためのガードレールを設定する + +## 認証 + +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..47f3b5613 --- /dev/null +++ b/docs/ja/release.md @@ -0,0 +1,32 @@ +--- +search: + exclude: true +--- +# リリースプロセス／変更履歴 + +プロジェクトでは、 `0.Y.Z` 形式を用いたセマンティックバージョニングのやや変更されたバージョンを採用しています。先頭の `0` は SDK がまだ急速に進化していることを示します。各コンポーネントの増分規則は以下のとおりです。 + +## マイナー ( `Y` ) バージョン + +ベータでない公開インターフェースに **互換性を壊す変更 (breaking changes)** が入る場合、マイナーバージョン `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` が追加されました。`MCPServer` を継承するクラスでは、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 108c12b90..b72953e49 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..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] を使用すると、エージェント実行中に生成されたアイテムを元の入力に連結した入力リストへ変換できます。これにより、あるエージェント実行の出力を別の実行へ渡したり、ループで実行して毎回新しいユーザー入力を追加したりすることが容易になります。 +[`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 アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] — LLM がハンドオフ ツールを呼び出したことを示します。 raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] — ハンドオフが発生したことを示します。 raw アイテムはハンドオフ ツール呼び出しに対するツール応答です。また、アイテムから送信元 / 送信先エージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] — LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] — ツールが呼び出されたことを示します。 raw アイテムはツール応答です。また、アイテムからツール出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] — LLM からの推論アイテムを示します。 raw アイテムは生成された推論内容です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを表します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は LLM がハンドオフツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] はハンドオフが発生したことを示します。raw アイテムはハンドオフツール呼び出しへのツール応答です。また、アイテムからソース / ターゲット エージェント にもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] はツールが呼び出されたことを示します。raw アイテムはツール応答です。また、アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 ### ガードレール結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの結果が存在する場合に格納されます。ガードレール結果には、ログや保存を行いたい有用な情報が含まれることがあるため、これらを参照できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールがあればその結果が格納されます。ガードレール結果にはログ出力や保存に役立つ情報が含まれることがあるため、利用できるようにしています。 -### raw レスポンス +### raw 応答 -[`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、 LLM が生成した [`ModelResponse`][agents.items.ModelResponse] が格納されます。 +[`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..08ef6d888 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 @@ -21,60 +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) を参照してください。 ## エージェントループ -`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 設定 +## 実行設定 -`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]: 各エージェントの `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 番目のエージェントへハンドオフしさらにツールを実行、最後に出力を生成 -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(): 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?") @@ -88,12 +91,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 は自動的に以下を行います: + +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なるセッション 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..3529900ce --- /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 +# 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", + 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(): + # 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") + + # First turn + 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() + + # Second turn - the agent will remember the previous conversation + 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() + + # Third turn - continuing the conversation + 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..0a3b6e735 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使用すると、 エージェント の実行が進行するにつれて発生する更新を購読できます。これにより、エンド ユーザーに進捗状況や部分的な応答を表示するのに役立ちます。 +ストリーミング を利用すると、 エージェント の実行中に発生する更新を購読できます。これにより、エンドユーザーへ進捗状況や部分的な応答を表示するのに役立ちます。 -ストリーミングを行うには、 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。続いて `result.stream_events()` を呼び出すと、後述する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 +ストリーミング を行うには、 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。その後、 `result.stream_events()` を呼び出すと、後述する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームを取得できます。 -## raw response イベント +## raw 応答イベント -[`RawResponsesStreamEvent`][agents.stream_events.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 @@ -37,9 +37,9 @@ if __name__ == "__main__": ## Run item イベントと エージェント イベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルなイベントです。アイテムが完全に生成されたタイミングを通知するため、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗をプッシュできます。同様に、 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] はハンドオフなどで現在の エージェント が変わった際に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルなイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といった粒度で進捗を ユーザー に配信できます。同様に、 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は現在の エージェント が変更された際（たとえば ハンドオフ の結果）に更新を通知します。 -たとえば、以下のコードは raw イベントを無視し、ユーザーへ更新のみをストリーミングします。 +例えば、次のコードは raw イベントを無視し、 ユーザー に対して更新のみをストリーム配信します。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index cd80092d5..72d4f42b9 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,21 +4,21 @@ 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] を使用する際に、いくつかの組み込みツールを提供しています。 -- [`WebSearchTool`][agents.tool.WebSearchTool] はエージェントに Web 検索を行わせます。 +- [`WebSearchTool`][agents.tool.WebSearchTool] により、エージェントは Web 検索 を実行できます。 - [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストアから情報を取得します。 - [`ComputerTool`][agents.tool.ComputerTool] はコンピュータ操作タスクを自動化します。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] はサンドボックス環境でコードを実行します。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルから直接利用できるようにします。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できます。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモート MCP サーバーのツールをモデルへ公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 - [`LocalShellTool`][agents.tool.LocalShellTool] はローカルマシンでシェルコマンドを実行します。 @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## 関数ツール +## Function tools -任意の Python 関数をツールとして使用できます。Agents SDK が自動的に設定を行います。 +任意の Python 関数をそのままツールとして利用できます。Agents SDK が自動で設定を行います。 -- ツールの名前は Python 関数の名前になります（任意で名前を指定することも可能です） -- ツールの説明は関数の docstring から取得されます（任意で説明を指定することも可能です） -- 関数の引数から自動的に入力スキーマを生成します -- 各入力の説明は、無効化しない限り docstring から取得されます +- ツール名には Python 関数名が使用されます (別名を指定することも可能)。 +- ツール説明は関数の docstring から取得されます (カスタム説明も可)。 +- 関数の引数から自動で入力スキーマを生成します。 +- 各入力の説明は docstring から取得されます (無効化も可能)。 -Python の `inspect` モジュールを使用して関数シグネチャを抽出し、[`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 ツール -Python 関数をそのままツールにしたくない場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を指定する必要があります。 +Python 関数を使わずに [`FunctionTool`][agents.tool.FunctionTool] を直接作成することもできます。その場合、次を指定してください。 - `name` - `description` -- `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（context と引数の JSON 文字列を受け取り、ツールの出力を文字列で返す async 関数） +- `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. `griffe` で docstring を解析します。サポートする形式は `google`、`sphinx`、`numpy` です。自動判定はベストエフォートのため、`function_tool` 呼び出し時に明示設定もできます。`use_docstring_info` を `False` にすると解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## ツールとしてのエージェント +## Agents as tools -一部のワークフローでは、ハンドオフせずに中央のエージェントが複数の専門エージェントをオーケストレーションしたい場合があります。そのような場合、エージェントをツールとしてモデル化できます。 +ワークフローによっては、複数の専門エージェントを中央のエージェントがオーケストレーションする方が便利な場合があります。その際、エージェントをツールとして扱うことでハンドオフせずに実現できます。 ```python from agents import Agent, Runner @@ -267,14 +267,14 @@ async def main(): print(result.final_output) ``` -### ツールエージェントのカスタマイズ +### ツール化エージェントのカスタマイズ -`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 に変換するなど、最終回答のフォーマットを変更したい。 +- レスポンスが欠落・不正な場合に検証やフォールバック値を設定したい。 -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file +`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..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` に設定する + 2. 単一の実行で無効化する場合は [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定する -***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングを利用できません。*** +***OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は 1 度のワークフロー全体を表します。複数のスパンで構成され、次のプロパティを持ちます: - - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 - - `trace_id`: トレースを一意に識別する ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: オプションのグループ ID。会話内の複数トレースを関連付けます。たとえばチャットスレッド ID など。 - - `disabled`: `True` の場合、このトレースは記録されません。 - - `metadata`: トレースに付随する任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ個々の処理を表します。スパンは以下を保持します: - - `started_at` と `ended_at` タイムスタンプ - - 所属トレースを示す `trace_id` - - 親スパンを指す `parent_id` (存在する場合) - - スパンに関する情報を格納する `span_data`。たとえば `AgentSpanData` にはエージェント情報が、`GenerationSpanData` には LLM 生成情報が含まれます。 +- **トレース** は 1 つのワークフローのエンドツーエンド操作を表します。トレースは複数のスパンで構成されます。トレースのプロパティは次のとおりです。 + - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」 + - `trace_id`: トレースの一意 ID。渡さなかった場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: オプションのグループ ID。同じ会話からの複数トレースをリンクするために使用します。例としてチャットスレッド ID など。 + - `disabled`: `True` の場合、このトレースは記録されません。 + - `metadata`: トレースに付与するオプションメタデータ。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンのプロパティは次のとおりです。 + - `started_at` と `ended_at` タイムスタンプ + - 所属するトレースを示す `trace_id` + - 親スパンを指す `parent_id` (存在する場合) + - スパンに関する情報を含む `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など。 ## デフォルトのトレーシング -デフォルトで SDK は以下をトレースします: +デフォルトでは、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. `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) -- [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..fdbd268dd 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,9 +2,9 @@ search: exclude: true --- -# エージェントの可視化 +# エージェント可視化 -エージェントの可視化を使用すると、 ** Graphviz ** を用いてエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、handoffs がどのように相互作用するかを理解するのに役立ちます。 +エージェント可視化を使用すると、 ** Graphviz ** を使ってエージェントとその関係を構造的なグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,11 +16,11 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は有向グラフを作成し、以下のように表現します。 +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は有向グラフを作成し、次のように表現します: -- **エージェント** は黄色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **handoffs** はエージェント間の有向エッジで示されます。 +- ** エージェント ** は黄色のボックスで表示されます。 +- ** ツール ** は緑色の楕円で表示されます。 +- ** ハンドオフ ** は一方のエージェントから別のエージェントへの有向エッジで示されます。 ### 使用例 @@ -52,26 +52,27 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![エージェントグラフ](../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() @@ -84,4 +85,4 @@ draw_graph(triage_agent).view() 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..7cb9374e3 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,37 @@ 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 +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 291b9882a..c24b92b40 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,19 +6,19 @@ search: ## 前提条件 -まずは [クイックスタート手順](../quickstart.md) に従って Agents SDK をセットアップし、仮想環境を作成してください。その後、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 モデルを実行して音声をテキストに変換します。 +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 @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして、シンプルな音声パイプラインを構築します。 +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] をワークフローとして使用し、シンプルな音声パイプラインをセットアップします。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめて実行 +## 統合例 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけます。実際にエージェントと会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話しかけてくれます。実際に自分でエージェントと会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 21f4788f9..e8dbda2a9 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` を使用してパイプラインのトレーシングを追加で設定できます。 主なトレーシング関連フィールドは次のとおりです。 -- [`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 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()) 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/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?") 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: 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 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/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 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/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: 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 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" },