diff --git a/docs/ja/agents.md b/docs/ja/agents.md index b6b04e482..3d148053a 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリにおける中核の構成要素です。エージェントは、instructions と tools で構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる構成要素です。エージェントは、instructions とツールで構成された大規模言語モデル（LLM）です。 -## 基本構成 +## 基本設定 -エージェントで最も一般的に設定するプロパティは次のとおりです。 +一般的に設定するエージェントのプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer メッセージ、または system prompt とも呼ばれます。 -- `model`: 使用する LLM と、temperature、top_p などのモデル調整用の任意の `model_settings`。 -- `tools`: エージェントがタスク達成のために使用できるツール。 +- `name`: エージェントを識別する必須の文字列です。 +- `instructions`: developer message または system prompt とも呼ばれます。 +- `model`: 使用する LLM と、temperature、top_p などのモデル調整パラメーターを設定する任意の `model_settings`。 +- `tools`: エージェントがタスクを達成するために使用できるツールです。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントはその `context` 型に対してジェネリックです。Context は依存性注入のためのツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行に必要な依存関係と状態の寄せ集めとして機能します。任意の Python オブジェクトを context として提供できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のツールです。あなたが作成して `Runner.run()` に渡すオブジェクトで、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態の入れ物として機能します。任意の Python オブジェクトをコンテキストとして提供できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト（`str`）出力を生成します。特定の型の出力をエージェントに生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型（dataclasses、lists、TypedDict など）をサポートします。 +デフォルトでは、エージェントはプレーンテキスト（`str`）の出力を生成します。特定のタイプの出力を生成したい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型（dataclasses、lists、TypedDict など）をサポートします。 ```python from pydantic import BaseModel @@ -73,20 +73,20 @@ agent = Agent( !!! note - `output_type` を渡すと、通常のプレーンテキスト応答ではなく、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようにモデルに指示します。 + `output_type` を渡すと、モデルに通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示します。 -## マルチエージェントの設計パターン +## マルチ エージェント システムの設計パターン -マルチエージェントシステムの設計方法は多数ありますが、一般的に広く適用できるパターンは次の 2 つです。 +マルチ エージェント システムの設計方法は数多くありますが、広く適用できるパターンとして一般的に次の 2 つがあります。 -1. マネージャー（エージェントをツールとして）: 中央のマネージャー/オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を維持します。 -2. ハンドオフ: ピアのエージェントが制御を専門のエージェントに引き渡し、そのエージェントが会話を引き継ぎます。これは分散型です。 +1. マネージャー（エージェントをツールとして）: 中央のマネージャー／オーケストレーターが、ツールとして公開された専門のサブ エージェントを呼び出し、会話の制御を維持します。 +2. ハンドオフ: ピアのエージェントが、会話を引き継ぐ専門のエージェントに制御をハンドオフします。これは分散型です。 -詳細は [エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) を参照してください。 +詳しくは、[エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)をご覧ください。 ### マネージャー（エージェントをツールとして） -`customer_facing_agent` はすべてのユーザー対応を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントをご覧ください。 +`customer_facing_agent` はすべてのユーザー対応を処理し、ツールとして公開された専門のサブ エージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) のドキュメントをご覧ください。 ```python from agents import Agent @@ -115,7 +115,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委譲できるサブエージェントです。ハンドオフが発生すると、委譲先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに特化したモジュール式のエージェントが可能になります。詳細は [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブ エージェントです。ハンドオフが発生すると、委任されたエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに秀でたモジュール式の専門エージェントが可能になります。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェントを作成するときに instructions を指定できますが、関数を通じて動的な instructions を提供することもできます。この関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を受け付けます。 +多くの場合、エージェントの作成時に instructions を指定できます。ただし、関数を介して動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも利用できます。 ```python def dynamic_instructions( @@ -153,15 +153,15 @@ agent = Agent[UserContext]( ## ライフサイクルイベント（フック） -場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりします。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +エージェントのライフサイクルを観察したい場合があります。たとえば、イベントをログに記録したり、特定のイベントが発生したときにデータを事前取得したりする場合です。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック/バリデーションを実行し、エージェントの出力が生成された後にも同様のチェックを行えます。たとえば、ユーザーの入力とエージェントの出力の妥当性をスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントをご覧ください。 +ガードレールにより、エージェントの実行と並行してユーザー入力に対するチェック／検証を行い、エージェントの出力が生成された後にもチェックを実行できます。たとえば、ユーザーの入力やエージェントの出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) のドキュメントをご覧ください。 -## エージェントのクローン/コピー +## エージェントのクローン／コピー -エージェントの `clone()` メソッドを使用すると、エージェントを複製し、任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -178,12 +178,12 @@ robot_agent = pirate_agent.clone( ## ツール使用の強制 -ツールのリストを渡しても、LLM が必ずしもツールを使うとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、ツール使用を強制できます。有効な値は次のとおりです。 +ツールのリストを指定しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定してツール使用を強制できます。有効な値は次のとおりです。 -1. `auto`: LLM にツールを使うかどうかの判断を任せます。 -2. `required`: LLM にツールの使用を要求します（ただし、どのツールを使うかは賢く判断できます）。 -3. `none`: LLM にツールを使わないよう要求します。 -4. 特定の文字列（例: `my_tool`）を設定し、その特定のツールの使用を要求します。 +1. `auto`: LLM がツールを使用するかどうかを判断します。 +2. `required`: LLM にツール使用を必須にします（どのツールを使うかは賢く判断できます）。 +3. `none`: LLM にツールを使用しないことを必須にします。 +4. 特定の文字列（例: `my_tool`）を設定すると、LLM にその特定のツールを使用させます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -203,10 +203,10 @@ agent = Agent( ## ツール使用の動作 -`Agent` の `tool_use_behavior` パラメーターは、ツール出力の扱いを制御します。 +`Agent` の設定にある `tool_use_behavior` パラメーターは、ツール出力の扱いを制御します。 - `"run_llm_again"`: デフォルト。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、追加の LLM 処理なしに最終応答として使用します. +- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を、その後の LLM 処理なしで最終応答として使用します。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -224,7 +224,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールが呼び出された場合に停止し、その出力を最終応答として使用します。 +- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールのいずれかが呼び出された場合に停止し、その出力を最終応答として使用します。 ```python from agents import Agent, Runner, function_tool @@ -248,7 +248,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。 +- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を続行するかを決定するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -286,4 +286,4 @@ agent = Agent( !!! note - 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツール結果が LLM に送られ、`tool_choice` により LLM がさらに別のツール呼び出しを生成し続けるために発生します。 \ No newline at end of file + 無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループは、ツールの結果が LLM に送られ、`tool_choice` によりさらに別のツール呼び出しを生成し続けるために発生します。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 7f8d4e875..170d286b9 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 @@ -50,9 +50,9 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグログ +## デバッグ ログ -SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。 +この SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。既定では、警告とエラーは `stdout` に送られ、それ以外のログは抑制されます。 詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズすることもできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳しくは [Python ロギング ガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 ```python import logging @@ -83,7 +83,7 @@ logger.addHandler(logging.StreamHandler()) ### ログ内の機微情報 -一部のログには機微情報（例: ユーザーのデータ）が含まれる場合があります。これらのデータが記録されないようにするには、次の環境変数を設定してください。 +一部のログには機微情報（たとえば ユーザー データ）が含まれる場合があります。これらのデータがログに出力されないようにするには、次の環境変数を設定してください。 LLM の入力と出力のログ記録を無効にするには: diff --git a/docs/ja/context.md b/docs/ja/context.md index e5ce0c193..d62afa07a 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストは多義的な用語です。重要なのは次の 2 つのクラスです。 +コンテキストという語は多義的です。ここでは主に次の 2 つのコンテキストがあります。 -1. コードからローカルで利用可能なコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 -2. LLM に提供されるコンテキスト: 応答を生成する際に LLM が参照できるデータです。 +1. コードからローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に利用できるコンテキスト: 応答生成時に LLM が参照できるデータです。 ## ローカルコンテキスト これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 -2. そのオブジェクトを各種 run メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 -3. すべてのツール呼び出しやライフサイクルフックには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +2. そのオブジェクトを各種の実行メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 +3. すべてのツール呼び出しやライフサイクルフックなどにはラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -**最も重要** な注意点: 特定のエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じコンテキストの型を使用する必要があります。 +**最も重要な** 注意点: あるエージェント実行に関与するすべてのエージェント、ツール関数、ライフサイクルなどは、同じ型のコンテキストを使用しなければなりません。 コンテキストは次のような用途に使えます: -- 実行時のコンテキストデータ（例: ユーザー名/uid やその他のユーザーに関する情報） -- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） -- ヘルパー関数 +- 実行に関するコンテキストデータ（例: ユーザー名/uid などのユーザー情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは LLM に送信されません。これは純粋にローカルなオブジェクトであり、読み書きやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM には送信されません。読み書きやメソッド呼び出しができる、純粋にローカルなオブジェクトです。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っているのが分かります。ツールの実装はコンテキストから読み取ります。 -3. 型チェッカーでエラーを検出できるように（例えば、異なるコンテキスト型を受け取るツールを渡した場合など）、エージェントにジェネリクス `UserInfo` を付けています。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装ではコンテキストから読み取っています。 +3. エージェントにジェネリクスとして `UserInfo` を付け、型チェッカーがエラーを検出できるようにします（例えば、異なるコンテキスト型を取るツールを渡そうとした場合など）。 4. コンテキストは `run` 関数に渡されます。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント/LLM のコンテキスト -LLM が呼び出されるとき、LLM が参照できるのは会話履歴からのデータのみです。したがって、新しいデータを LLM に利用可能にしたい場合は、その履歴で参照できる形で提供しなければなりません。方法はいくつかあります: +LLM が呼び出されるとき、LLM が参照できるのは会話履歴のデータのみです。したがって、新しいデータを LLM に利用可能にするには、その履歴で参照できる形で提供する必要があります。主な方法は次のとおりです。 -1. エージェントの `instructions` に追加します。これは「system prompt」や「developer message」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 -2. `Runner.run` 関数を呼ぶときの `input` に追加します。これは `instructions` を使う方法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)でより下位のメッセージを持たせられます。 -3. 関数ツール経由で公開します。これは _オンデマンド_ のコンテキストに有用です。LLM は必要なときにデータが必要だと判断し、ツールを呼び出してそのデータを取得できます。 -4. リトリーバルまたは Web 検索を使います。これらは、ファイルやデータベース（リトリーバル）、あるいは Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに応答を「グラウンディング」するのに有用です。 \ No newline at end of file +1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を返す動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した方法です。 +2. `Runner.run` を呼び出すときの `input` に追加します。これは `instructions` の戦略に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できます。 +3. 関数ツールで公開します。これはオンデマンドのコンテキストに有用で、LLM が必要に応じてツールを呼び出してデータを取得できます。 +4. リトリーバルや Web 検索を使用します。これは、ファイルやデータベースから関連データを取得する（リトリーバル）あるいはウェブから取得する（Web 検索）ための特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 3b52cbcc3..b38de1c45 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -2,47 +2,47 @@ search: exclude: true --- -# サンプル +# コード例 + +リポジトリ の [repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK の多様なサンプル実装をご覧ください。これらのコード例は、さまざまなパターンや機能を示すいくつかのカテゴリーに整理されています。 -[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK の多様なサンプル実装を確認できます。これらの code examples は、さまざまなパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの code examples は、次のような一般的なエージェント設計パターンを示します + このカテゴリーの例では、次のような一般的なエージェント設計パターンを示します - 決定的なワークフロー - ツールとしてのエージェント - - 並列エージェント実行 + - エージェントの並列実行 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらの code examples は、SDK の基礎的な機能を示します + このカテゴリーでは、次のような SDK の基礎的な機能を紹介します - 動的な システムプロンプト - ストリーミング出力 - ライフサイクルイベント - **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法と、 - それらをエージェントに統合する方法を学べます。 + Web 検索 や ファイル検索 などの OpenAI がホストするツール の実装方法と、それらをエージェントに統合する方法を学べます。 -- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - SDK で OpenAI 以外のモデルを使用する方法を紹介します。 +- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 以外のモデルを SDK で使う方法を確認できます。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - エージェントのハンドオフ の実践的な code examples を確認できます。 + エージェントの ハンドオフ の実用例をご覧ください。 - **[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):** - 実世界のアプリケーションを示す、より作り込まれた code examples が 2 つあります + 実運用に近いアプリケーションを示す、完成度の高い 2 つの例 - - **customer_service**: 航空会社向けのカスタマーサービスシステムの例。 - - **research_bot**: シンプルな ディープリサーチ クローン。 + - **customer_service**: 航空会社向けのカスタマーサービス システムの例。 + - **research_bot**: シンプルな ディープリサーチ のクローン。 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 当社の TTS と STT モデルを用いた音声エージェントの code examples を確認できます。 + TTS と STT モデルを使った音声エージェントの例をご覧ください。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使用してリアルタイム体験を構築する方法を示す code examples。 \ No newline at end of file + SDK を使ってリアルタイムなエクスペリエンスを構築する方法の例。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index dc0d68cbb..0da7119de 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと _並行して_ 実行され、ユーザー入力の検査と検証を行います。たとえば、顧客からのリクエスト対応に非常に賢い（＝遅くて高価な）モデルを使うエージェントがあるとします。悪意あるユーザーがそのモデルに数学の宿題を手伝わせるような依頼をすることは避けたいはずです。そこで、速くて安価なモデルでガードレールを実行できます。ガードレールが不正利用を検知したら、即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、 ユーザー 入力のチェックと検証を行います。例えば、非常に賢い（その分、遅く/高価な）モデルを使って顧客対応をする エージェント があるとします。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるよう求めるのは避けたいはずです。そのために、速く/安価なモデルでガードレールを実行できます。ガードレールが悪用を検知した場合は即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。 -ガードレールには 2 種類あります。 +ガードレールには 2 種類あります: -1. 入力ガードレールは最初のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェント出力に対して実行されます +1. 入力ガードレールは最初の ユーザー 入力に対して実行されます +2. 出力ガードレールは最終的な エージェント の出力に対して実行されます ## 入力ガードレール -入力ガードレールは次の 3 ステップで実行されます。 +入力ガードレールは次の 3 ステップで実行されます: -1. まず、ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップします。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が行えます。 +1. まず、ガードレールは エージェント に渡されたものと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、 ユーザー への適切な応答や例外処理が行えるようになります。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールが走るのは、そのエージェントが「最初の」エージェントである場合のみです。`guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのはなぜかと疑問に思うかもしれません。ガードレールは実際のエージェントに密接に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。 + 入力ガードレールは ユーザー 入力に対して実行されることを想定しているため、エージェントのガードレールはそのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティが エージェント 側にあり、`Runner.run` に渡さないのか疑問に思うかもしれません。これは、ガードレールが実際の Agent に密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行することになるため、コードを同じ場所に置くことで可読性が向上します。 ## 出力ガードレール -出力ガードレールは次の 3 ステップで実行されます。 +出力ガードレールは次の 3 ステップで実行されます: -1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップします。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が行えます。 +1. まず、ガードレールは エージェント によって生成された出力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、 ユーザー への適切な応答や例外処理が行えるようになります。 !!! Note - 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントのガードレールが走るのは、そのエージェントが「最後の」エージェントである場合のみです。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 出力ガードレールは最終的な エージェント 出力に対して実行されることを想定しているため、エージェントのガードレールはそのエージェントが「最後の」エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際の Agent に密接に関連する傾向があるため、コードを同じ場所に置くことが可読性の面で有用です。 ## トリップワイヤー -入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが作動したガードレールを検知したら、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでそれを知らせます。トリップワイヤーが作動したガードレールを検知した時点で、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、Agent の実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。以下の例では、内部でエージェントを実行してこれを行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、内部で エージェント を実行してこれを行います。 ```python from pydantic import BaseModel @@ -94,10 +94,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレールの結果に追加情報を含めることができます。 -4. これはワークフローを定義する実際のエージェントです。 +1. この エージェント をガードレール関数内で使用します。 +2. これが エージェント の入力/コンテキストを受け取り、結果を返すガードレール関数です。 +3. ガードレール結果に追加情報を含めることができます。 +4. これはワークフローを定義する実際の エージェント です。 出力ガードレールも同様です。 @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. これは実際のエージェントの出力型です。 +1. これは実際の エージェント の出力型です。 2. これはガードレールの出力型です。 -3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 -4. これはワークフローを定義する実際のエージェントです。 \ No newline at end of file +3. これが エージェント の出力を受け取り、結果を返すガードレール関数です。 +4. これはワークフローを定義する実際の エージェント です。 \ No newline at end of file diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 5585b7fdf..44d0b122c 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`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すか、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡せます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き渡し先のエージェントに加えて、任意の上書き設定や入力フィルターを指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加えて、任意のオーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -以下は、シンプルなハンドオフの作り方です。 +以下はシンプルなハンドオフの作成方法です。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. エージェントを直接使う（`billing_agent` のように）ことも、`handoff()` 関数を使うこともできます。 +1. `billing_agent` のようにエージェントを直接使っても、`handoff()` 関数を使ってもかまいません。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数では、さまざまな点をカスタマイズできます。 -- `agent`: 引き渡し先のエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使われ、`transfer_to_` に解決されます。これを上書きできます。 +- `agent`: ハンドオフ先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に解決されます。これを上書きできます。 - `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されることがわかった時点でデータ取得を開始するなどに便利です。この関数はエージェントのコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフが想定する入力の型（任意）です。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうかです。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼ばれた時点でデータ取得を開始するなどに便利です。この関数はエージェントコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフで期待する入力の型（任意）です。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。 +- `is_enabled`: ハンドオフを有効にするかどうか。真偽値、または実行時に動的に有効・無効を切り替える真偽値を返す関数を指定できます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## ハンドオフの入力 -状況によっては、ハンドオフを呼び出す際に LLM にいくつかのデータを提供してほしい場合があります。例えば「エスカレーションエージェント」へのハンドオフを想像してください。ログのために理由を提供してほしい、というようなケースです。 +状況によっては、ハンドオフを呼び出す際に LLM にデータの提供を求めたい場合があります。たとえば「エスカレーションエージェント」へのハンドオフを考えてみてください。理由を提供してもらい、ログに残したいことがあるでしょう。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を閲覧できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] を介して既存の入力を受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが行われると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を参照できるかのように振る舞います。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] として受け取り、新しい `HandoffInputData` を返す関数です。 -一般的なパターン（例えば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +よくあるパターン（例：履歴からすべてのツール呼び出しを削除する）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -100,11 +100,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 b62760ec3..66ba55b75 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、以前のエージェント向け実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) の、本番運用に適したアップグレード版です。Agents SDK には、非常に小さな基本コンポーネントのセットがあります。 +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化を最小限に抑えた軽量で使いやすいパッケージで、エージェント型の AI アプリを構築できるようにします。これは、エージェントに関する以前の実験的プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) の本番運用に適したアップグレード版です。Agents SDK には、ごく少数の基本コンポーネントがあります。 - **エージェント**: instructions と tools を備えた LLM -- **ハンドオフ**: 特定のタスクでエージェントが他のエージェントに委譲できる機能 -- **ガードレール**: エージェントの入力と出力の検証を可能にする機能 -- **セッション**: エージェントの実行間で会話履歴を自動的に維持する機能 +- **ハンドオフ**: 特定のタスクを他のエージェントに委譲できる仕組み +- **ガードレール**: エージェントの入力と出力を検証する仕組み +- **セッション**: エージェントの実行間で会話履歴を自動的に維持する仕組み -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習コストなしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が付属しており、エージェント フローの可視化とデバッグ、評価、さらにはアプリケーション向けのモデルのファインチューニングまで行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現するのに十分強力であり、急な学習曲線なしに実運用レベルのアプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化してデバッグできるほか、評価したり、アプリケーション向けにモデルを微調整することも可能です。 -## Why use the Agents SDK +## Agents SDK を使う理由 -この SDK の設計原則は 2 つあります。 +この SDK には 2 つの設計原則があります。 -1. 十分に使う価値がある機能を備えつつ、基本コンポーネントは少なく、短時間で学べること。 -2. そのままでも優れた動作をする一方で、何が起きるかを正確にカスタマイズできること。 +1. 使う価値がある十分な機能を備えつつ、学習が迅速に済むよう基本コンポーネントは少数に抑える。 +2. すぐに使えて十分に機能する一方で、実際に何が起きるかを正確にカスタマイズできる。 -SDK の主な機能は次のとおりです。 +SDK の主な特徴は次のとおりです。 -- エージェント ループ: ツールの呼び出し、結果を LLM へ送信、LLM の完了までのループを処理する組み込みのループ。 -- Python ファースト: 新しい抽象化を学ぶのではなく、言語の組み込み機能でエージェントのオーケストレーションや連鎖を実現。 -- ハンドオフ: 複数のエージェント間での調整や委譲を可能にする強力な機能。 -- ガードレール: エージェントと並行して入力の検証やチェックを実行し、失敗時には早期に中断。 -- セッション: エージェントの実行間での会話履歴を自動管理し、手動の状態管理を不要に。 -- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 -- トレーシング: ワークフローの可視化、デバッグ、モニタリングを可能にし、OpenAI の評価、ファインチューニング、蒸留ツール群も利用可能。 +- エージェント ループ: ツールの呼び出し、実行結果の LLM への送信、LLM が完了するまでのループ処理を行う組み込みのエージェント ループ。 +- Python ファースト: 新しい抽象化を学ぶのではなく、言語の組み込み機能でエージェントをオーケストレーションし連鎖させる。 +- ハンドオフ: 複数のエージェント間で調整と委譲を行う強力な機能。 +- ガードレール: エージェントと並行して入力のバリデーションやチェックを実行し、チェックに失敗した場合は早期に中断。 +- セッション: エージェントの実行間での会話履歴を自動管理し、手動の状態管理を不要にする。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic によるバリデーションを提供。 +- トレーシング: ワークフローの可視化、デバッグ、モニタリングに加え、OpenAI の評価、ファインチューニング、蒸留ツール群の利用を可能にする組み込みのトレーシング。 ## インストール diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 2ce0acb49..d3833a8f7 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,32 +4,32 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールとコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントからの引用です。 -> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーションのための USB-C ポートのようなものです。USB-C がデバイスをさまざまな周辺機器やアクセサリに標準化された方法で接続できるのと同様に、MCP は AI モデルをさまざまなデータソースやツールに標準化された方法で接続します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、ファイルシステム、HTTP、またはコネクタで支えられたツールをエージェントに公開するために独自のサーバーを構築したりできます。 +Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、独自に構築して、ファイルシステム、HTTP、あるいはコネクタで支えられたツールを エージェント に公開できます。 ## Choosing an MCP integration -エージェントに MCP サーバーを接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは Python SDK がサポートするオプションの概要です。 +MCP サーバーを エージェント に接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションをまとめたものです。 -| 必要なこと | 推奨オプション | -| --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -| モデルの代わりに OpenAI の Responses API からパブリックに到達可能な MCP サーバーを呼び出す | [`HostedMCPTool`][agents.tool.HostedMCPTool] による **Hosted MCP server tools** | -| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] による **Streamable HTTP MCP servers** | -| Server-Sent Events を用いた HTTP を実装するサーバーと通信する | [`MCPServerSse`][agents.mcp.server.MCPServerSse] による **HTTP with SSE MCP servers** | -| ローカルプロセスを起動して stdin/stdout 経由で通信する | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] による **stdio MCP servers** | +| 必要なこと | 推奨オプション | +| ------------------------------------------------------------------------------------ | -------------------------------------------------------- | +| OpenAI の Responses API がモデルの代わりに公開到達可能な MCP サーバーを呼び出せるようにする | **Hosted MCP server tools**（ホスト型 MCP ツール）経由の [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| ローカルまたはリモートで運用する Streamable HTTP サーバーに接続する | **Streamable HTTP MCP servers** 経由の [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Server‑Sent Events を用いた HTTP を実装するサーバーと通信する | **HTTP with SSE MCP servers** 経由の [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| ローカルプロセスを起動し、stdin/stdout 越しに通信する | **stdio MCP servers** 経由の [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -以下のセクションでは、それぞれのオプションの設定方法と、どのトランスポートを選ぶべきかを説明します。 +以下のセクションでは、それぞれのオプション、設定方法、どのトランスポートを選ぶべきかについて説明します。 ## 1. Hosted MCP server tools -ホスト型ツールは、ツールの往復処理全体を OpenAI のインフラストラクチャに移します。コードでツールの列挙や呼び出しを行う代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] はサーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、Python プロセスへの追加のコールバックなしでそれらを呼び出します。ホスト型ツールは現在、Responses API の hosted MCP 連携をサポートする OpenAI モデルで動作します。 +Hosted ツールは、ツールの往復処理全体を OpenAI のインフラに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、あなたの Python プロセスへの追加のコールバックなしにそれらを実行します。Hosted ツールは現在、Responses API の hosted MCP 連携をサポートする OpenAI モデルで動作します。 ### Basic hosted MCP tool -エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` 辞書は REST API に送る JSON と同じ構造です: +`HostedMCPTool` を エージェント の `tools` リストに追加して hosted ツールを作成します。`tool_config` の dict は、REST API に送る JSON を反映します。 ```python import asyncio @@ -57,11 +57,11 @@ async def main() -> None: asyncio.run(main()) ``` -ホストされたサーバーは自動的にそのツールを公開します。`mcp_servers` に追加する必要はありません。 +Hosted サーバーはツールを自動的に公開するため、`mcp_servers` に追加する必要はありません。 ### Streaming hosted MCP results -ホスト型ツールは、関数ツールとまったく同じ方法でストリーミング結果をサポートします。`Runner.run_streamed` に `stream=True` を渡すと、モデルが実行中でも増分的な MCP 出力を消費できます: +Hosted ツールは、関数ツールとまったく同じ方法で結果の ストリーミング をサポートします。`Runner.run_streamed` に `stream=True` を渡して、モデルがまだ処理中でも増分の MCP 出力を消費します。 ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -73,7 +73,7 @@ print(result.final_output) ### Optional approval flows -サーバーが機微な操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を必須にできます。`tool_config` の `require_approval` を単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの辞書で設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 +サーバーが機密性の高い操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を必須にできます。`tool_config` の `require_approval` を単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict で設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -101,11 +101,11 @@ agent = Agent( ) ``` -コールバックは同期・非同期のどちらでもよく、モデルが継続実行に必要な承認データを求めるたびに呼び出されます。 +コールバックは同期・非同期のどちらでもよく、モデルが継続実行に必要な承認データを要求するたびに呼び出されます。 ### Connector-backed hosted servers -Hosted MCP は OpenAI コネクタにも対応しています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホストされたサーバーがコネクタのツールを公開します。 +Hosted MCP は OpenAI コネクタにも対応しています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、hosted サーバーはコネクタのツールを公開します。 ```python import os @@ -121,13 +121,13 @@ HostedMCPTool( ) ``` -ストリーミング、承認、コネクタを含む完全なホスト型ツールのサンプルは +ストリーミング、承認、コネクタを含む完全な hosted ツールのサンプルは [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 ## 2. Streamable HTTP MCP servers ネットワーク接続を自分で管理したい場合は、 -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、レイテンシを低く保ちながら自社インフラ内でサーバーを実行したい場合に最適です。 +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、レイテンシを抑えつつ自社インフラ内でサーバーを運用したい場合に最適です。 ```python import asyncio @@ -162,17 +162,17 @@ async def main() -> None: asyncio.run(main()) ``` -コンストラクタは次の追加オプションを受け付けます: +コンストラクタは次の追加オプションを受け付けます。 -- `client_session_timeout_seconds` は HTTP の読み取りタイムアウトを制御します。 -- `use_structured_content` は、テキスト出力よりも `tool_result.structured_content` を優先するかどうかを切り替えます。 +- `client_session_timeout_seconds` は HTTP 読み取りタイムアウトを制御します。 +- `use_structured_content` は `tool_result.structured_content` を文字出力より優先するかを切り替えます。 - `max_retry_attempts` と `retry_backoff_seconds_base` は `list_tools()` と `call_tool()` に自動リトライを追加します。 -- `tool_filter` は公開するツールのサブセットを制限できます（[Tool filtering](#tool-filtering) を参照）。 +- `tool_filter` は公開するツールをサブセット化できます（[Tool filtering](#tool-filtering) を参照）。 ## 3. HTTP with SSE MCP servers MCP サーバーが HTTP with SSE トランスポートを実装している場合は、 -[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外の API は Streamable HTTP サーバーと同一です。 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 ```python @@ -201,7 +201,7 @@ async with MCPServerSse( ## 4. stdio MCP servers -ローカルのサブプロセスとして動作する MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキストマネージャの終了時に自動的にクローズします。これは、迅速なプロトタイプや、サーバーがコマンドラインのエントリポイントのみを公開している場合に役立ちます。 +ローカルのサブプロセスとして動作する MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキストマネージャーの終了時に自動的にクローズします。これは、迅速なプロトタイプや、サーバーがコマンドラインのエントリポイントのみを公開している場合に便利です。 ```python from pathlib import Path @@ -229,11 +229,11 @@ async with MCPServerStdio( ## Tool filtering -各 MCP サーバーはツールフィルターをサポートしており、エージェントに必要な関数だけを公開できます。フィルタリングは構築時にも、実行ごとに動的にも行えます。 +各 MCP サーバーはツールフィルタをサポートしており、エージェント に必要な機能だけを公開できます。フィルタリングは、構築時または実行ごとに動的に行えます。 ### Static tool filtering -[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、単純な許可/ブロックリストを構成します: +[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、単純な許可／ブロックリストを設定します。 ```python from pathlib import Path @@ -255,7 +255,7 @@ filesystem_server = MCPServerStdio( ### Dynamic tool filtering -より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。同期・非同期のどちらでもよく、ツールを公開すべきときに `True` を返します。 +より精緻なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。これは同期・非同期いずれでもよく、ツールを公開すべきときに `True` を返します。 ```python from pathlib import Path @@ -279,14 +279,14 @@ async with MCPServerStdio( ... ``` -フィルターコンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。 +フィルタコンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 ## Prompts -MCP サーバーは、エージェントの instructions を動的に生成する Prompts も提供できます。Prompts をサポートするサーバーは次の 2 つのメソッドを公開します: +MCP サーバーは、エージェントの instructions を動的に生成する Prompts も提供できます。Prompts をサポートするサーバーは次の 2 つのメソッドを公開します。 - `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。 +- `get_prompt(name, arguments)` は、任意の パラメーター 付きで具体的なプロンプトを取得します。 ```python from agents import Agent @@ -306,19 +306,19 @@ agent = Agent( ## Caching -各エージェント実行は、各 MCP サーバーに対して `list_tools()` を呼び出します。リモートサーバーは顕著なレイテンシを生む可能性があるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変化しないと確信できる場合にのみ `True` に設定してください。後で新しい一覧を強制するには、サーバーインスタンスで `invalidate_tools_cache()` を呼び出します。 +すべての エージェント 実行は、各 MCP サーバーに対して `list_tools()` を呼び出します。リモートサーバーは顕著なレイテンシを導入しうるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変更されないと確信できる場合にのみ、これを `True` に設定してください。後で新しいリストを強制するには、サーバーインスタンス上で `invalidate_tools_cache()` を呼び出します。 ## Tracing -[Tracing](./tracing.md) は、次を含む MCP アクティビティを自動的に捕捉します: +[Tracing](./tracing.md) は MCP のアクティビティを自動的に捕捉します。以下を含みます。 -1. ツール一覧のための MCP サーバーへの呼び出し。 +1. ツールを列挙するための MCP サーバーへの呼び出し。 2. ツール呼び出しに関する MCP 関連情報。 -![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) +![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) ## Further reading -- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様と設計ガイド。 +- [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様および設計ガイド。 - [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP のサンプル。 -- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む完全な hosted MCP デモ。 \ No newline at end of file +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認やコネクタを含む完全な hosted MCP のデモ。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index 59c8270a3..edf99223f 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに使える形で次の 2 種類でサポートしています。 +Agents SDK には、OpenAI モデルに対する 2 通りのサポートが標準で含まれています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい Responses API を使用して OpenAI API を呼び出します。(https://platform.openai.com/docs/api-reference/responses) -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。Chat Completions API を使用して OpenAI API を呼び出します。(https://platform.openai.com/docs/api-reference/chat) +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 ## OpenAI モデル -`Agent` を初期化するときにモデルを指定しない場合、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント型ワークフローにおける予測可能性と低レイテンシの強力なバランスを提供します。 +`Agent` を初期化する際にモデルを指定しない場合、既定のモデルが使用されます。現在の既定は [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント ワークフローの予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) などの他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルへ切り替えたい場合は、次のセクションの手順に従ってください。 -### デフォルトの OpenAI モデル +### 既定の OpenAI モデル -カスタムモデルを設定していないすべてのエージェントに対して特定のモデルを一貫して使用したい場合は、エージェントを実行する前に環境変数 `OPENAI_DEFAULT_MODEL` を設定してください。 +カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使用したい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -この方法で GPT-5 の reasoning モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用すると、SDK はデフォルトで妥当な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。これらの設定を自分で構築したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) といった GPT-5 の推論モデルをこの方法で使用する場合、SDK は既定で妥当な `ModelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。これらの設定を自分で構成したい場合は、`agents.models.get_default_model_settings("gpt-5")` を呼び出してください。 -より低レイテンシや特定の要件がある場合は、別のモデルと設定を選択できます。デフォルトモデルの reasoning の強度を調整するには、独自の `ModelSettings` を渡してください。 +さらに低レイテンシや特定の要件がある場合は、別のモデルや設定を選べます。既定モデルの推論負荷を調整するには、独自の `ModelSettings` を指定してください。 ```python from openai.types.shared import Reasoning @@ -44,52 +44,52 @@ my_agent = Agent( ) ``` -特に低レイテンシを重視する場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、デフォルト設定よりも高速にレスポンスが返ってくることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしていないため、本 Agents SDK はデフォルトで `"low"` を使用しています。 +特に低レイテンシが必要な場合は、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を組み合わせると、既定設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（たとえば ファイル検索 や 画像生成）は `"minimal"` の推論負荷をサポートしていないため、本 Agents SDK では既定を `"low"` にしています。 #### 非 GPT-5 モデル -カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `ModelSettings` にフォールバックします。 +カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルに互換性のある汎用の `ModelSettings` にフォールバックします。 ## 非 OpenAI モデル -[LiteLLM 連携](../litellm.md) を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、litellm の依存関係グループをインストールします。 +[LiteLLM 連携](./litellm.md)を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、litellm の依存関係グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -次に、`litellm/` プレフィックスを付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 +その後、`litellm/` プレフィックスを付けて、[サポート対象モデル](https://docs.litellm.ai/docs/providers) を使用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使うその他の方法 +### 非 OpenAI モデルの他の利用方法 -他の LLM プロバイダを統合する方法はさらに 3 つあります（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーは、さらに 3 つの方法で統合できます（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に有用です。これは LLM プロバイダが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能なサンプルは [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行のすべてのエージェントにカスタムのモデルプロバイダを使う」と指定できます。設定可能なサンプルは [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] は特定の Agent インスタンスでモデルを指定できます。これにより、エージェントごとに異なるプロバイダを組み合わせて使うことができます。設定可能なサンプルは [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの利用可能なモデルを簡単に使う方法としては、[LiteLLM 連携](../litellm.md) があります。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に使います。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行のすべてのエージェントでカスタムのモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] は、特定の Agent インスタンスでモデルを指定できます。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの利用可能なモデルを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) が便利です。 -`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することをおすすめします。 +`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することを推奨します。 !!! note - これらの code examples では、Responses API/モデルではなく Chat Completions API/モデルを使用しています。これは、多くの LLM プロバイダがまだ Responses API をサポートしていないためです。もし使用する LLM プロバイダが Responses をサポートしている場合は、Responses の使用をおすすめします。 + これらの code examples では、Responses API/モデルではなく Chat Completions API/モデルを使用しています。多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーがサポートしている場合は、Responses の使用を推奨します。 ## モデルの組み合わせ -1 つのワークフローの中で、エージェントごとに異なるモデルを使いたい場合があります。例えば、トリアージには小型で高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使うといった使い分けです。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法で特定のモデルを選択できます。 +単一のワークフローの中で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小さく高速なモデルを使い、複雑なタスクにはより大きく高機能なモデルを使うといった形です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選択できます。 -1. モデル名を直接渡す。 +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 つのモデル形に統一することをおすすめします。両者はサポートする機能やツールのセットが異なるためです。ワークフローでモデル形を混在させる場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + 本 SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、両者はサポートする機能やツールが異なるため、各ワークフローでは単一のモデル形状を使用することを推奨します。ワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -122,10 +122,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI のモデル名を直接設定します。 +1. OpenAI モデルの名前を直接設定します。 2. [`Model`][agents.models.interface.Model] 実装を提供します。 -エージェントで使用するモデルをさらに設定したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡すことで、temperature などの任意のモデル構成パラメーターを指定できます。 +エージェントで使用するモデルをさらに構成したい場合は、[`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。これは temperature などの任意のモデル構成パラメーターを提供します。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例：`user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡せます。 +また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡せます。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダ使用時の一般的な問題 +## 他の LLM プロバイダー使用時の一般的な問題 -### トレーシングクライアントのエラー 401 +### トレーシング クライアント エラー 401 -トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI のサーバーにアップロードされる一方で、OpenAI の API キーを持っていないためです。解決策は次の 3 つです。 +トレーシングに関連するエラーが発生する場合、トレースが OpenAI サーバーにアップロードされる一方で OpenAI の API キーをお持ちでないことが原因です。解決するには次の 3 つの選択肢があります。 1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 2. トレーシング用に OpenAI のキーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. OpenAI 以外のトレースプロセッサーを使用する。[トレーシングのドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +3. OpenAI 以外のトレース プロセッサーを使用する。[tracing ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、ほとんどの他の LLM プロバイダはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決するには、次の 2 つの方法があります。 +SDK は既定で Responses API を使用しますが、ほとんどの他社 LLM プロバイダーはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決策は次の 2 つです。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](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](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。このため、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダ側の不足によるものです。JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないことがあります。現在これに対する修正に取り組んでいますが、JSON schema 出力をサポートするプロバイダに依存することをおすすめします。そうでないと、JSON の不正形式が原因でアプリが頻繁に壊れてしまいます。 +これは一部プロバイダー側の不足によるもので、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないことがあります。現在これに対する解決策に取り組んでいますが、JSON schema 出力をサポートするプロバイダーに依存することを推奨します。そうでない場合、JSON の不正構造によりアプリがしばしば動作しなくなるためです。 -## プロバイダをまたいだモデルの混在 +## プロバイダー間でのモデルの混在 -モデルプロバイダ間の機能差異に注意しないと、エラーに遭遇する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索および Web 検索をサポートしていますが、多くの他プロバイダはこれらの機能をサポートしていません。次の制限に注意してください。 +モデルプロバイダー間の機能差を理解しておかないと、エラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 および Web 検索 をサポートしますが、多くの他社プロバイダーはこれらの機能をサポートしません。以下の制限に注意してください。 -- サポートされていない `tools` を理解しないプロバイダに送らない -- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングする -- 構造化された JSON 出力をサポートしないプロバイダは、無効な JSON を生成することがある点に注意する \ No newline at end of file +- サポートしていない `tools` を理解しないプロバイダーに送信しないでください +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください +- 構造化された JSON 出力をサポートしないプロバイダーは、無効な JSON を生成することがあります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 0e53e75bc..447f4e058 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM による任意モデルの利用 +# LiteLLM 経由での任意モデルの利用 !!! note - LiteLLM 統合はベータです。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題は [GitHub issues](https://github.com/openai/openai-agents-python/issues) から報告してください。迅速に修正します。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーで問題が発生する可能性があります。問題は [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、あらゆる AI モデルを利用できるようにしました。 ## セットアップ -`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください: +`litellm` を利用可能にする必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -これは完全に動作するサンプルです。実行すると、モデル名と API キーの入力を求められます。たとえば次のように入力できます: +これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば次のように入力できます。 -- `openai/gpt-4.1`（モデル）と OpenAI の API キー -- `anthropic/claude-3-5-sonnet-20240620`（モデル）と Anthropic の API キー +- `openai/gpt-4.1` をモデルに指定し、OpenAI の API キーを入力 +- `anthropic/claude-3-5-sonnet-20240620` をモデルに指定し、Anthropic の API キーを入力 - など -LiteLLM でサポートされているモデルの完全な一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM でサポートされているモデルの完全な一覧は、[litellm のプロバイダードキュメント](https://docs.litellm.ai/docs/providers)をご覧ください。 ```python from __future__ import annotations @@ -76,9 +76,9 @@ if __name__ == "__main__": asyncio.run(main(model, api_key)) ``` -## 利用データのトラッキング +## 使用データの追跡 -LiteLLM のレスポンスを Agents SDK の利用状況メトリクスに反映させるには、エージェント作成時に `ModelSettings(include_usage=True)` を渡してください。 +LiteLLM の応答を Agents SDK の使用状況メトリクスに反映させたい場合は、エージェント作成時に `ModelSettings(include_usage=True)` を渡してください。 ```python from agents import Agent, ModelSettings diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index aec3a7ad8..e28e31a3d 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -2,40 +2,40 @@ search: exclude: true --- -# 複数のエージェントのオーケストレーション +# 複数の エージェント のオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントをどの順番で実行し、次に何をするかをどう決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内での エージェント の流れを指します。どの エージェント を、どの順番で実行し、その後の判断をどう行うかです。エージェント をオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定させる: LLM の知能を使って計画・推論し、それに基づいて取るべきステップを決定します。 -2. コードでオーケストレーションする: コードでエージェントの流れを決めます。 +1. LLM に意思決定させる: これにより、 LLM の知能を使って計画・推論し、それに基づいて実行する手順を決めます。 +2. コードでオーケストレーションする: コードで エージェント の流れを決めます。 -これらのパターンは組み合わせて使えます。いずれにもトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使えます。各方法には以下のようなトレードオフがあります。 ## LLM によるオーケストレーション -エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたときに、LLM は自律的にタスクへの取り組み方を計画し、ツールを使って行動・データ取得を行い、ハンドオフを使ってサブエージェントにタスクを委譲できます。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 +エージェント は、instructions、tools、ハンドオフ を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、 LLM はツールを使って行動・データ取得を行い、ハンドオフ を使ってサブエージェントに作業を委任しながら、タスクへの取り組み方を自律的に計画できます。例えば、リサーチ用の エージェント には次のようなツールを備えられます。 -- Web 検索でオンライン情報を探す -- ファイル検索と取得でプロプライエタリなデータや接続を検索する -- コンピュータ操作でコンピュータ上のアクションを実行する -- コード実行でデータ分析を行う -- 計画立案、レポート作成などに長けた専門エージェントへのハンドオフ +- Web 検索でオンライン情報を見つける +- ファイル検索 と取得で独自データやコネクションを検索する +- コンピュータ操作 でコンピュータ上のアクションを実行する +- コード実行 でデータ分析を行う +- 計画立案、レポート作成などに優れた特化 エージェント への ハンドオフ -このパターンは、タスクがオープンエンドで LLM の知能に頼りたい場合に最適です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、 LLM の知能に依存させたい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、および準拠すべきパラメーターを明確にします。 -2. アプリを監視し、反復改善する。問題が起きる箇所を見極め、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。たとえばループで実行して自己批評させる、またはエラーメッセージを与えて改善させます。 -4. 何でもできる汎用エージェントではなく、1 つのタスクに特化して卓越したエージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練して、タスクの上達と改善を図れます。 +1. 良いプロンプトに投資する。利用可能なツール、その使い方、運用すべきパラメーターを明確にします。 +2. アプリを監視し、反復改善する。問題の発生箇所を把握し、プロンプトを改善します。 +3. エージェント に内省と改善を許可する。例えばループで実行して自己批評させる、エラーメッセージを与えて改善させる、など。 +4. 何でもできる汎用 エージェント よりも、1 つのタスクに特化して卓越する エージェント を用意する。 +5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これにより エージェント を訓練し、タスクの上達を図れます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の面でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの観点で、より決定的かつ予測可能にできます。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査可能な 適切な形式のデータ を生成する。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、カテゴリーに基づいて次のエージェントを選ぶといった使い方です。 -- 複数のエージェントを、あるエージェントの出力を次のエージェントの入力に変換して連結する。ブログ記事の作成のようなタスクを、リサーチ、アウトライン作成、本文作成、批評、改善という一連のステップに分解できます。 -- 実行役のエージェントと、その出力を評価してフィードバックを与えるエージェントを組み合わせ、評価者が基準を満たしたと判断するまで `while` ループで回す。 -- 複数のエージェントを並行実行する。例えば Python の基本コンポーネントである `asyncio.gather` を使う。互いに依存しない複数タスクがある場合、速度向上に有効です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェント にタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次の エージェント を選ぶ。 +- 複数の エージェント を連結し、先行出力を後続入力に変換する。ブログ記事作成のようなタスクを、調査→アウトライン作成→本文執筆→批評→改善という一連のステップに分解する。 +- 実行役の エージェント を `while` ループで走らせつつ、評価とフィードバックを行う エージェント を併走させ、評価者が所定基準の合格を出すまで続ける。 +- 複数の エージェント を並列実行する（例: Python の基本コンポーネントである `asyncio.gather` を活用）。相互依存しない複数タスクがあるとき、速度向上に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) にいくつかの code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 32faeda88..8c33aed33 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは一度だけ実行すれば十分です。 +これは最初の一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行します。 +新しいターミナルセッションを開始するたびに実行します。 ```bash source .venv/bin/activate @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだお持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions、名前、およびオプションの config（たとえば `model_config`）で定義します。 +エージェントは instructions、名前、任意の構成（`model_config` など）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## さらにいくつかのエージェントを追加 +## エージェントの追加 -追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加のコンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを決定するための追加コンテキストを提供します。 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各エージェントごとに、そのエージェントがタスクを進める方法を判断する際に選択できる、送信側ハンドオフ オプションの一覧を定義できます。 +各エージェントごとに、タスクを前進させる方法を判断するために選択できる送出側ハンドオフ候補の一覧を定義できます。 ```python triage_agent = Agent( @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 全体の統合 +## すべてを組み合わせる -すべてをまとめて、ハンドオフと入力ガードレールを使用し、ワークフロー全体を実行しましょう。 +ハンドオフと入力ガードレールを用いて、すべてを組み合わせてワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェント実行中に起きたことを確認するには、OpenAI ダッシュボードの Trace viewer に移動して、エージェントの実行のトレースを表示します。 +エージェントの実行中に何が起きたかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動し、エージェントのトレースを表示します。 ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう。 +より複雑なエージェント フローの構築方法を学びましょう: -- [エージェント](agents.md)の設定について学ぶ。 -- [エージェントの実行](running_agents.md)について学ぶ。 -- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md)について学ぶ。 \ No newline at end of file +- エージェントの設定方法について学びます: [エージェント](agents.md)。 +- [エージェントの実行](running_agents.md) について学びます。 +- [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md) について学びます。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index 49baa2381..7977affb9 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK のリアルタイム機能を用いて、音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -リアルタイムエージェントはベータ版です。実装の改善に伴い、互換性に影響する変更が入る可能性があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -リアルタイムエージェントは、音声とテキスト入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを可能にします。OpenAI の Realtime API と持続的に接続し、低レイテンシで自然な音声対話や割り込みへの優雅な対応を実現します。 +Realtime エージェントは、リアルタイムで音声とテキスト入力を処理し、リアルタイム音声で応答する会話フローを可能にします。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話と、割り込みへのスムーズな対応を実現します。 ## アーキテクチャ ### コアコンポーネント -リアルタイムシステムは、いくつかの主要コンポーネントで構成されます。 +realtime システムは次の主要コンポーネントで構成されます。 -- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェントです。 +- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェント。 - **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデルインターフェイス（通常は OpenAI の WebSocket 実装） +- **RealtimeSession**: 単一の対話セッション。通常、ユーザー が会話を開始するたびに作成し、会話が完了するまで維持します。 +- **RealtimeModel**: 基盤のモデルインターフェース（一般的には OpenAI の WebSocket 実装） ### セッションフロー -一般的なリアルタイムセッションは次のフローに従います。 +典型的な realtime セッションは次の流れに従います。 1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 2. **RealtimeRunner をセットアップ** し、エージェントと設定オプションを指定します。 -3. **セッションを開始** します。`await runner.run()` を使用すると RealtimeSession が返されます。 -4. **音声またはテキストメッセージを送信** します。`send_audio()` または `send_message()` を使用します。 -5. **イベントをリッスン** します。セッションを反復処理してイベントを受け取ります。イベントには、音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. **割り込みに対応** します。ユーザーがエージェントの発話中に話し始めると、現在の音声生成は自動的に停止します。 +3. `await runner.run()` を用いて **セッションを開始** し、RealtimeSession を取得します。 +4. `send_audio()` または `send_message()` を使って **音声またはテキストメッセージを送信** します。 +5. セッションを反復処理して **イベントをリッスン** します。イベントには音声出力、文字起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザー がエージェントの発話に被せて話した際の **割り込み処理** を行います。これにより現在の音声生成は自動的に停止します。 -セッションは会話履歴を保持し、リアルタイムモデルとの持続的な接続を管理します。 +セッションは会話履歴を保持し、realtime モデルとの永続的な接続を管理します。 -## エージェントの設定 +## エージェント設定 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつかの重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] のリファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。API の詳細は [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェントレベルではなくセッションレベルで設定します。 -- structured outputs はサポートされません（`outputType` はサポート対象外）。 +- モデルの選択はエージェント レベルではなくセッション レベルで設定します。 +- structured outputs はサポートされません（`outputType` は未対応）。 - ボイスはエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 -- それ以外の機能（tools、ハンドオフ、instructions）は同様に機能します。 +- その他の機能（tools、ハンドオフ、instructions）は同様に動作します。 -## セッションの設定 +## セッション設定 ### モデル設定 -セッション設定により、基盤となるリアルタイムモデルの動作を制御できます。モデル名（例: `gpt-realtime`）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力と出力の両方に設定可能で、既定は PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-realtime` など）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、および対応モダリティ（テキストや音声）を設定できます。音声フォーマットは入力と出力の両方で設定でき、既定は PCM16 です。 ### 音声設定 -音声設定は、セッションが音声入力と出力をどのように扱うかを制御します。Whisper のようなモデルを用いた入力音声の文字起こし、言語設定、およびドメイン固有用語の精度向上のための文字起こしプロンプトを指定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出された発話周辺のパディングなど、エージェントが応答を開始・停止するタイミングを調整できます。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper のようなモデルを使用した入力音声の文字起こし、言語設定、ドメイン固有用語の精度を高めるための文字起こしプロンプトを構成できます。発話区間検出の設定により、エージェントがいつ応答を開始・停止すべきかを制御でき、音声活動検出のしきい値、無音継続時間、検出された発話の前後のパディングを指定できます。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、リアルタイムエージェントは会話中に実行される 関数ツール をサポートします。 +通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします。 ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、会話を専門特化したエージェント間で引き継ぐことができます。 +ハンドオフにより、会話を専門化されたエージェント間で転送できます。 ```python from agents.realtime import realtime_handoff @@ -117,14 +117,14 @@ main_agent = RealtimeAgent( ) ``` -## イベント処理 +## イベントハンドリング -セッションは、セッションオブジェクトを反復処理することでリッスンできるイベントをストリーミングします。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に扱うべき主なイベントは以下です。 +セッションはイベントをストリーミングし、セッションオブジェクトを反復処理してこれらをリッスンできます。イベントには、音声出力チャンク、文字起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特にハンドルすべき主要イベントは以下です。 - **audio**: エージェントの応答からの raw 音声データ - **audio_end**: エージェントの発話が終了 -- **audio_interrupted**: ユーザーがエージェントを割り込み -- **tool_start/tool_end**: ツール実行のライフサイクル +- **audio_interrupted**: ユーザー がエージェントを割り込み +- **tool_start/tool_end**: ツール実行ライフサイクル - **handoff**: エージェントのハンドオフが発生 - **error**: 処理中にエラーが発生 @@ -132,9 +132,9 @@ main_agent = RealtimeAgent( ## ガードレール -リアルタイムエージェントでサポートされるのは出力ガードレールのみです。パフォーマンス問題を避けるため、これらのガードレールはデバウンスされ、（毎語ではなく）定期的に実行されます。既定のデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでは出力の ガードレール のみがサポートされます。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるため、（毎語ではなく）定期的に実行されます。既定のデバウンス長は 100 文字ですが、設定可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて指定できます。両方のソースから提供されたガードレールは併せて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースからのガードレールは併用されて実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断することがあります。デバウンス動作は、安全性とリアルタイム性能要件のバランスに役立ちます。テキストエージェントと異なり、リアルタイムエージェントはガードレールが作動しても例外を発生させません。 +ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンスの挙動は、安全性とリアルタイム性能要件のバランスを取るのに役立ちます。テキスト エージェントと異なり、realtime エージェントはガードレールがトリップしても例外をスローしません。 ## 音声処理 [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用して音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 -音声出力については、`audio` イベントをリッスンして、任意の音声ライブラリで音声データを再生してください。ユーザーがエージェントを割り込んだ際に即座に再生を停止し、キュー済み音声をクリアするため、`audio_interrupted` イベントも必ず監視してください。 +音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで音声データを再生してください。ユーザー がエージェントを割り込んだ際に即座に再生を停止し、キュー済み音声をクリアするため、`audio_interrupted` イベントも必ず監視してください。 ## モデルへの直接アクセス -基盤となるモデルにアクセスして、カスタムリスナーを追加したり高度な操作を実行したりできます。 +基盤のモデルにアクセスして、カスタムリスナーの追加や高度な操作を行えます。 ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェイスへ直接アクセスできます。 +これにより、接続をより低レベルで制御する必要がある高度なユースケースに対して、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## コード例 +## 例 -完全な動作コードについては、UI コンポーネントの有無それぞれのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file +完全な動作する code examples は、UI コンポーネントの有無のデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 41e7c5841..c4fb6dc69 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,26 +4,26 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声会話を可能にします。このガイドでは、最初の Realtime 音声エージェントの作成手順を説明します。 +Realtime エージェントは、OpenAI の Realtime API を使用して AI エージェントとの音声対話を可能にします。本ガイドでは、最初の リアルタイム 音声エージェントの作成手順を説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改良に伴い、互換性のない変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、後方互換性のない変更が入る可能性があります。 ## 前提条件 -- Python 3.9 以上 -- OpenAI API キー -- OpenAI Agents SDK に関する基本的な理解 +- Python 3.9 以上 +- OpenAI API キー +- OpenAI Agents SDK の基本的な知識 ## インストール -まだの場合は、OpenAI Agents SDK をインストールしてください: +まだの場合は、OpenAI Agents SDK をインストールします: ```bash pip install openai-agents ``` -## 最初の Realtime エージェントの作成 +## 最初の リアルタイム エージェントの作成 ### 1. 必要なコンポーネントのインポート @@ -32,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. Realtime エージェントの作成 +### 2. リアルタイム エージェントの作成 ```python agent = RealtimeAgent( @@ -41,7 +41,7 @@ agent = RealtimeAgent( ) ``` -### 3. Runner のセットアップ +### 3. runner のセットアップ ```python runner = RealtimeRunner( @@ -109,9 +109,9 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 完全なサンプルコード +## 完全な例 -動作する完全なサンプルコードは次のとおりです: +以下は動作する完全な例です: ```python import asyncio @@ -188,44 +188,44 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 設定オプション +## 構成オプション ### モデル設定 -- `model_name`: 利用可能な Realtime モデルから選択します (例: `gpt-realtime`) -- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`) +- `model_name`: 利用可能な リアルタイム モデルから選択 (例: `gpt-realtime`) +- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`) ### 音声設定 -- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力音声の形式 -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_format`: 入力音声のフォーマット (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 出力音声のフォーマット +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方式 (`server_vad`, `semantic_vad`) -- `threshold`: 音声活動のしきい値 (0.0-1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前の音声パディング +- `type`: 検出方式 (`server_vad`, `semantic_vad`) +- `threshold`: 音声活動のしきい値 (0.0-1.0) +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [Realtime エージェントの詳細](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダにある動作するサンプルコードを確認する -- エージェントにツールを追加する -- エージェント間のハンドオフを実装する -- 安全性のためのガードレールを設定する +- [リアルタイム エージェントの詳細](guide.md) +- 動作する code examples は [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダをご覧ください +- エージェントに tools を追加 +- エージェント間のハンドオフを実装 +- 安全性のためのガードレールを設定 ## 認証 -環境に OpenAI API キーが設定されていることを確認してください: +OpenAI API キーが環境に設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション作成時に直接渡します: +また、セッション作成時に直接渡すこともできます: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 2906d3001..8a21c4941 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,29 +4,29 @@ search: --- # リリースプロセス/変更履歴 -このプロジェクトは、`0.Y.Z` という形式のやや変更されたセマンティック バージョニングに従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増加させます。 +このプロジェクトは、形式 `0.Y.Z` を用いる、セマンティック バージョニングをやや変更した方式に従います。先頭の `0` は、 SDK がまだ急速に進化していることを示します。各コンポーネントの増分ルールは次のとおりです。 ## マイナー (`Y`) バージョン -ベータではない公開インターフェースに対する**破壊的変更**がある場合、マイナー バージョン `Y` を上げます。例えば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれる可能性があります。 +ベータでないパブリック インターフェースに対する**後方互換性のない変更**がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への変更には、互換性破壊が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 +互換性破壊を避けたい場合は、プロジェクトで `0.0.x` にピン留めすることをおすすめします。 ## パッチ (`Z`) バージョン -非破壊的変更には `Z` を増やします。 +後方互換性のある変更については `Z` を増やします: - バグ修正 - 新機能 -- 非公開インターフェースの変更 +- プライベート インターフェースの変更 - ベータ機能の更新 -## 破壊的変更の変更履歴 +## 後方互換性のない変更の変更履歴 ### 0.2.0 -このバージョンでは、これまで `Agent` を引数として受け取っていた複数の箇所が、代わりに `AgentBase` を引数として受け取るようになりました。例えば、MCP サーバーでの `list_tools()` 呼び出しなどです。これは純粋に型定義上の変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを解消してください。 +このバージョンでは、以前は引数として `Agent` を受け取っていた箇所の一部が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、 MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型付けに関する変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` という 2 つの新しい params が追加されました。`MCPServer` を継承するすべてのクラスに、これらの params を追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーターが 2 つ追加されました: `run_context` と `agent`。`MCPServer` をサブクラス化しているすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index e84d776a2..80d5361ab 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,8 @@ search: --- # REPL ユーティリティ -この SDK には、ターミナルでエージェントの動作をすばやく対話的にテストできる `run_demo_loop` が用意されています。 +この SDK には、ターミナル上でエージェントの挙動を素早く対話的にテストできる `run_demo_loop` が用意されています。 + ```python import asyncio @@ -18,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間の会話履歴を保持します。既定では、生成と同時にモデル出力をストリーミングします。上の例を実行すると、run_demo_loop は対話型のチャットセッションを開始します。入力を継続的に求め、ターン間の会話全体の履歴を記憶し（そのためエージェントは何が話されたかを把握します）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 +`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成されたモデル出力をそのままストリーミングします。上記の例を実行すると、`run_demo_loop` は対話的なチャットセッションを開始します。継続的に入力を求め、ターン間で会話全体の履歴を記憶し（そのためエージェントは何が話されたかを把握します）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 -このチャットセッションを終了するには、`quit` または `exit` と入力して Enter キーを押すか、`Ctrl-D` キーボードショートカットを使用します。 \ No newline at end of file +チャットセッションを終了するには、`quit` または `exit` と入力して（そして Enter を押す）、もしくは `Ctrl-D` のキーボードショートカットを使用してください。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index 20a19d081..01cb8244f 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 結果 +# 実行結果 -`Runner.run` メソッドを呼び出すと、以下のいずれかが返ります: +`Runner.run` メソッドを呼び出すと、次のどちらかが得られます。 -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] +- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ここに最も有用な情報が含まれます。 +どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、最も有用な情報の多くはここにあります。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が入ります。これは次のいずれかです。 -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は、`last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `output_type` が定義されていない場合は `str` +- エージェントに出力タイプが定義されている場合は `last_agent.output_type` 型のオブジェクト !!! note - `final_output` は `Any` 型です。ハンドオフ のため、静的型付けはできません。ハンドオフ が発生すると、どのエージェントでも最後になり得るため、可能な出力タイプの集合を静的には特定できません。 + `final_output` の型は `Any` です。ハンドオフのため、静的型付けはできません。ハンドオフが発生する場合、どの Agent が最後になるか分からないため、可能な出力タイプの集合を静的には特定できないからです。 -## 次ターンの入力 +## 次ターンへの入力 -[`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] です。Run item は 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 c67ca0c4e..0286b358e 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。方法は 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。選択肢は 3 つあります: -1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 +1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを逐次ストリーミングします。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリーミングします。 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳しくは [実行結果ガイド](results.md) をご覧ください。 +詳細は[結果ガイド](results.md)をご覧ください。 -## エージェントのループ +## エージェントループ -`Runner` の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージとみなされます）か、OpenAI Responses API のアイテムのリストのいずれかです。 +`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）または入力アイテムのリストで、これは OpenAI Responses API のアイテムです。 -Runner は次のループを実行します。 +runner は次のループを実行します: 1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了して結果を返します。 - 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追加してループを再実行します。 + 1. LLM が `final_output` を返した場合、ループを終了し、結果を返します。 + 2. LLM がハンドオフした場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追加して、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、ツール呼び出しがない場合です。 + LLM の出力が「最終出力」と見なされる条件は、目的の型のテキスト出力を生成し、ツール呼び出しがないことです。 ## ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行の完全な情報が格納されます。ストリーミングイベントは `.stream_events()` を呼び出してください。詳しくは [ストリーミング ガイド](streaming.md) をご覧ください。 +ストリーミングにより、LLM の実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行の完全な情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出して取得できます。詳細は[ストリーミングガイド](streaming.md)をご覧ください。 ## 実行設定 -`run_config` パラメーターで、エージェント実行のグローバル設定を構成できます。 +`run_config` パラメーターでは、エージェント実行のグローバル設定を構成できます: -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、使用するグローバルな LLM モデルを設定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力ガードレールのリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既定のものがない場合に適用するグローバルな入力フィルターです。入力フィルターにより、新しいエージェントへ送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントをご覧ください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化できます。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、LLM やツール呼び出しの入出力など、機微なデータを含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングにおけるワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けられます。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関係なく、使用するグローバルな LLM モデルを設定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力ガードレールのリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: すでに設定がないハンドオフすべてに適用するグローバル入力フィルターです。入力フィルターにより、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントをご覧ください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の[トレーシング](tracing.md)を無効にできます。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、LLM やツール呼び出しの入出力など、機微なデータを含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングのワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にわたるトレースを関連付けられます。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話/チャットスレッド -任意の run メソッドの呼び出しは、1 つ以上のエージェント（つまり 1 回以上の LLM 呼び出し）を実行することがありますが、チャット会話の 1 つの論理的なターンを表します。例: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（つまり 1 回以上の LLM 呼び出しが行われる）可能性がありますが、チャット会話における 1 回の論理的なターンを表します。例: 1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフ。2 番目のエージェントがさらにツールを実行し、出力を生成。 +2. Runner の実行: 1 つ目のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフ。2 つ目のエージェントがさらにツールを実行し、その後出力を生成。 -エージェントの実行終了時に、ユーザーへ何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを表示する、または最終出力のみを表示することができます。いずれの場合も、ユーザーが追質問をすることがあり、その場合は再度 run メソッドを呼び出します。 +エージェント実行の最後に、ユーザーに何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを表示する、または最終出力のみを表示する、といった選択が可能です。いずれの場合も、ユーザーがフォローアップの質問をすることがあり、その場合は再度 run メソッドを呼び出します。 -### 会話の手動管理 +### 手動の会話管理 -次のターンの入力を取得するには、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って、会話履歴を手動で管理できます。 +次のターン用の入力を取得するには、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます: ```python async def main(): @@ -91,9 +91,9 @@ async def main(): # California ``` -### Sessions による会話の自動管理 +### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出さずに会話履歴を自動で扱えます。 +より簡単な方法として、[Sessions](sessions.md) を使うと、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動処理できます: ```python from agents import Agent, Runner, SQLiteSession @@ -117,26 +117,26 @@ async def main(): # California ``` -Sessions は自動で次を行います。 +Sessions は自動的に次を行います: -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- セッション ID ごとに別々の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なる session ID ごとに別個の会話を維持 -詳細は [Sessions のドキュメント](sessions.md) をご覧ください。 +詳細は [Sessions のドキュメント](sessions.md)をご覧ください。 -## 長時間実行エージェントと人間参加型 (human-in-the-loop) +## 長時間実行エージェントと human-in-the-loop -Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、耐障害性があり長時間実行されるワークフロー（人間参加型のタスクを含む）を実行できます。Temporal と Agents SDK が連携して長時間タスクを完了させるデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) をご覧ください。ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) です。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使用して、human-in-the-loop タスクを含む永続的な長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で、ドキュメントは[こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)をご覧ください。 ## 例外 -SDK は特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 +SDK は特定の場合に例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです: -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。ほかの特定の例外はすべてこの型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡した `max_turns` 制限を超えた場合に送出されます。指定した対話ターン数内にタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が想定外または無効な出力を生成した場合に発生します。これには次が含まれます。 - - 不正な JSON: 特定の `output_type` が定義されている場合などに、ツール呼び出しや直接の出力で不正な JSON 構造を返す。 - - ツール関連の予期しない失敗: モデルが期待どおりにツールを使用できない場合 -- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（この SDK を用いてコードを書く人）が誤った使い方をした場合に送出されます。通常は不適切なコード実装、無効な構成、または SDK の API の誤用が原因です。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力ガードレールまたは出力ガードレールの条件に合致した場合に送出されます。入力ガードレールは処理前に着信メッセージを確認し、出力ガードレールは配信前にエージェントの最終応答をチェックします。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外はすべてこの汎用型から派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` に渡された `max_turns` 制限を超えたときに送出されます。指定された対話ターン数内でエージェントがタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤モデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。これには次が含まれます: + - 不正な JSON: ツール呼び出し用、または直接の出力として不正な JSON 構造を返した場合（特に特定の `output_type` が定義されている場合）。 + - 予期しないツール関連の失敗: モデルが期待どおりの方法でツールを使用できなかった場合 +- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（SDK を用いてコードを書く人）が誤りを犯した場合に送出されます。これは通常、不正なコード実装、無効な構成、または SDK の API の誤用に起因します。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力ガードレールまたは出力ガードレールの条件が満たされたときに送出されます。入力ガードレールは処理前に受信メッセージを、出力ガードレールは配信前にエージェントの最終応答をチェックします。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 1897ea74f..899949663 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は組み込みのセッションメモリを提供し、複数のエージェント実行にわたって会話履歴を自動的に保持します。これにより、ターン間で手動で `.to_input_list()` を扱う必要がなくなります。 +Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に保持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 -セッションは特定のセッション用に会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えさせたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッションに対して会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -49,19 +49,19 @@ print(result.final_output) # "Approximately 39 million" ## 仕組み -セッションメモリを有効にすると: +セッションメモリが有効な場合: -1. **各実行の前**: ランナーはセッションの会話履歴を自動で取得し、入力アイテムの先頭に付加します。 -2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）はすべて自動的にセッションへ保存されます。 -3. **コンテキストの維持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: Runner はセッションの会話履歴を自動的に取得し、入力アイテムの先頭に追加します。 +2. **各実行の後**: 実行中に生成された新しいすべてのアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）は、自動的にセッションに保存されます。 +3. **コンテキストの維持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出して会話状態を管理する必要がなくなります。 +これにより、手動で `.to_input_list()` を呼び出し、実行間で会話状態を管理する必要がなくなります。 ## メモリ操作 ### 基本操作 -セッションは会話履歴を管理するための複数の操作をサポートします: +セッションは、会話履歴を管理するためにいくつかの操作をサポートします: ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 修正のための pop_item の利用 +### 修正のための `pop_item` の使用 -`pop_item` メソッドは、会話内の最後のアイテムを取り消したり修正したりしたい場合に特に便利です: +`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたい場合に特に有用です: ```python from agents import Agent, Runner, SQLiteSession @@ -117,7 +117,7 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## メモリのオプション +## メモリオプション ### メモリなし（デフォルト） @@ -129,8 +129,7 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API メモリ [OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api) を使用して、 -独自のデータベースを管理せずに会話状態を永続化できます。これは、会話履歴の保存に OpenAI がホストするインフラに -すでに依存している場合に役立ちます。 +独自のデータベースを管理することなく会話状態を永続化します。これは、会話履歴の保存に OpenAI ホストのインフラストラクチャにすでに依存している場合に役立ちます。 ```python from agents import OpenAIConversationsSession @@ -191,11 +190,11 @@ result2 = await Runner.run( ### SQLAlchemy ベースのセッション -より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）をセッションストレージとして利用できます。 +より高度なユースケースでは、SQLAlchemy 駆動のセッションバックエンドを使用できます。これにより、セッションの保存に SQLAlchemy がサポートするあらゆるデータベース（PostgreSQL、MySQL、SQLite など）を使用できます。 -**例 1: `from_url` を使用したインメモリ SQLite** +**例 1: `from_url` とインメモリ SQLite の使用** -これは最も簡単なはじめ方で、開発やテストに最適です。 +これは最も簡単な入門方法で、開発やテストに最適です。 ```python import asyncio @@ -216,9 +215,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**例 2: 既存の SQLAlchemy エンジンを使用** +**例 2: 既存の SQLAlchemy エンジンの使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っていることが多いでしょう。これをセッションに直接渡せます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性があります。これをセッションに直接渡せます。 ```python import asyncio @@ -247,7 +246,7 @@ if __name__ == "__main__": ``` -## 独自メモリ実装 +## カスタムメモリ実装 [`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: @@ -296,19 +295,19 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理するのに役立つ意味のあるセッション ID を使用します: +会話を整理しやすい意味のあるセッション ID を使用します: -- ユーザー基準: `"user_12345"` -- スレッド基準: `"thread_abc123"` -- コンテキスト基準: `"support_ticket_456"` +- ユーザー単位: `"user_12345"` +- スレッド単位: `"thread_abc123"` +- コンテキスト単位: `"support_ticket_456"` -### メモリの永続化 +### メモリ永続化 -- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用 -- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用 -- 既存のデータベースを持つ本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 -- 履歴を OpenAI Conversations API に保存したい場合は OpenAI ホスト型ストレージ（`OpenAIConversationsSession()`）を使用 -- さらに高度なユースケース向けに（Redis、Django など）他の本番システム向けのカスタムセッションバックエンドの実装を検討 +- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します +- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します +- 既存のデータベースがある本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します（SQLAlchemy がサポートするデータベース） +- OpenAI ホストのストレージ（`OpenAIConversationsSession()`）は、履歴を OpenAI Conversations API に保存したい場合に使用します +- より高度なユースケースでは、他の本番システム（Redis、Django など）向けにカスタムセッションバックエンドの実装を検討します ### セッション管理 @@ -336,7 +335,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリが実際にどのように動作するかを示す完全な例です: +セッションメモリの動作を示す完全な例です: ```python import asyncio @@ -400,9 +399,9 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは以下を参照してください: +詳細な API ドキュメントは以下をご覧ください: -- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`Session`][agents.memory.Session] - プロトコル インターフェース - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 - [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 実装 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 73761f170..778730c2b 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、エージェントの実行が進むにつれて更新を購読できます。エンドユーザーへの進捗表示や部分的なレスポンスの表示に役立ちます。 +ストリーミングは、エージェントの実行が進行するにつれて更新を購読できるようにします。これは、エンド ユーザーに進行状況の更新や部分的なレスポンスを表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出して [`RunResultStreaming`][agents.result.RunResultStreaming] を取得します。`result.stream_events()` を呼ぶと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 -## raw レスポンスイベント +## Raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式で、各イベントはタイプ（`response.created`、`response.output_text.delta` など）とデータを持ちます。生成されたメッセージを即座にユーザーへストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これは OpenAI Responses API フォーマットであり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、生成され次第、ユーザーにレスポンスメッセージをストリーミングしたい場合に有用です。 -たとえば、次のコードは LLM が生成したテキストをトークンごとに出力します。 +例えば、これは LLM が生成するテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Run アイテムイベントとエージェントイベント +## 実行アイテムイベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、トークン単位ではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗更新を送れます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などのレベルで進行状況をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変わったとき（例: ハンドオフの結果として）の更新を提供します。 -たとえば、次のコードは raw イベントを無視して、ユーザーへ更新だけをストリーミングします。 +例えば、これは raw イベントを無視し、ユーザーへ更新をストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 0a6d7b012..946bf29e3 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行するための手段です。たとえばデータ取得、コード実行、外部 API 呼び出し、さらにはコンピュータの使用まで可能です。 Agent SDK には 3 種類のツールがあります: +ツールは エージェント がアクションを実行できるようにします。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 つのツールのクラスがあります。 -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 -- Function Calling: 任意の Python 関数をツールとして使えます。 -- ツールとしての エージェント: エージェント をツールとして使えます。これにより、ハンドオフなしで エージェント から他の エージェント を呼び出せます。 +- Hosted tools: これは AI モデルと同じ LLM サーバー上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を Hosted tools として提供します。 +- Function calling: 任意の Python 関数をツールとして使えるようにします。 +- Agents as tools: エージェントをツールとして使用でき、ハンドオフ なしで別の エージェント を呼び出せます。 ## ホスト型ツール -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する際に、いくつかの組み込みツールを提供しています: +OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合にいくつかのビルトインツールを提供します。 -- [`WebSearchTool`][agents.tool.WebSearchTool]: エージェント が Web 検索 を行えます。 -- [`FileSearchTool`][agents.tool.FileSearchTool]: OpenAI の ベクトルストア から情報を取得できます。 -- [`ComputerTool`][agents.tool.ComputerTool]: コンピュータ操作 の自動化が可能です。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]: サンドボックス環境で LLM がコードを実行できます。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool]: リモートの MCP サーバーのツールをモデルに公開します。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]: プロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool]: あなたのマシン上でシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web を検索させます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI の ベクトルストア から情報を取得できます。 +- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を可能にします。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバーのツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はあなたのマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして使用できます。 Agents SDK がツールを自動的にセットアップします: +任意の Python 関数をツールとして使用できます。Agents SDK が自動でツールをセットアップします。 -- ツール名は Python 関数名になります（任意の名前を指定することも可能） -- ツールの説明は関数の docstring から取得されます（説明を指定することも可能） -- 関数入力のスキーマは関数の引数から自動生成されます +- ツール名は Python 関数の名前になります（または任意の名前を指定できます） +- ツールの説明は関数の docstring から取得されます（または説明を指定できます） +- 関数入力のスキーマは関数の引数から自動的に作成されます - 各入力の説明は、無効化しない限り、関数の docstring から取得されます -関数シグネチャの抽出には Python の `inspect` モジュールを、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ生成には `pydantic` を使用しています。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、スキーマ作成には `pydantic` を使用します。 ```python import json @@ -103,11 +103,11 @@ for tool in agent.tools: ``` 1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期のどちらでも構いません。 -2. docstring が存在する場合、説明文および引数の説明の取得に使用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。また、ツール名や説明、使用する docstring スタイルなどのオーバーライドも設定できます。 -4. デコレートした関数をツール一覧に渡せます。 +2. docstring があれば、全体の説明と引数の説明に利用します。 +3. 関数はオプションで `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring のスタイルなどのオーバーライドも設定できます。 +4. デコレートした関数をツールのリストに渡せます。 -??? note "出力を表示" +??? note "Expand to see output" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。必要に応じて直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: +ときには、Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次の項目を指定してください。 - `name` - `description` - `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と、JSON 文字列の引数を受け取り、ツールの出力を文字列で返す非同期関数） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力を文字列で返す非同期関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足: +前述のとおり、関数シグネチャを自動解析してツールのスキーマを抽出し、docstring を解析してツールと各引数の説明を抽出します。注意点は次のとおりです。 -1. シグネチャ解析は `inspect` モジュール経由で行います。型アノテーションを用いて引数の型を理解し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など大半の型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。形式の自動検出を試みますがベストエフォートのため、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定して docstring 解析を無効化することも可能です。 +1. シグネチャの解析は `inspect` モジュールで行います。引数の型は型アノテーションを用いて解釈し、全体スキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDicts などほとんどの型をサポートします。 +2. docstring の解析には `griffe` を使用します。対応する docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますがベストエフォートであり、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定すると docstring 解析を無効化できます。 スキーマ抽出のコードは [`agents.function_schema`][] にあります。 -## ツールとしてのエージェント +## エージェントをツールとして -一部のワークフローでは、ハンドオフせずに中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。これは エージェント をツールとしてモデル化することで実現できます。 +一部のワークフローでは、ハンドオフ するのではなく、中央の エージェント が専門特化した エージェント 群をオーケストレーションしたい場合があります。これは エージェント をツールとしてモデリングすることで実現できます。 ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツール化エージェントのカスタマイズ +### ツール化したエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント をツールに変換しやすくするための簡便メソッドです。ただし、すべての設定に対応しているわけではありません。例えば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: +`agent.as_tool` 関数は エージェント をツールに変換しやすくするための簡便メソッドです。ただし、すべての構成をサポートしているわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 ```python @function_tool @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### カスタム出力抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に有用です: +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。これは次のような場合に便利です。 -- サブ エージェント のチャット履歴から特定情報（例: JSON ペイロード）を抽出する。 -- エージェント の最終回答を変換または再整形する（例: Markdown をプレーンテキストや CSV に変換）。 -- 出力を検証し、応答が欠落または不正な場合にフォールバック値を提供する。 +- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 +- エージェントの最終回答を変換または再フォーマットする（例: Markdown をプレーンテキストや CSV に変換）。 +- 出力を検証したり、エージェントの応答が欠落または不正な場合にフォールバック値を提供する。 -これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます: +これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます。 ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 条件付きツール有効化 -実行時に `is_enabled` パラメーターを使って、エージェント ツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザーの嗜好、実行時条件に基づいて、LLM に提供するツールを動的に絞り込めます。 +`is_enabled` パラメーター を使って、実行時に エージェント のツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザー の嗜好、実行時の条件に基づいて、LLM に利用可能なツールを動的にフィルタリングできます。 ```python import asyncio @@ -372,24 +372,24 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーターは次を受け付けます: +`is_enabled` パラメーター は次を受け付けます。 - **ブール値**: `True`（常に有効）または `False`（常に無効） - **呼び出し可能関数**: `(context, agent)` を受け取り、真偽値を返す関数 -- **非同期関数**: 複雑な条件ロジック用の async 関数 +- **非同期関数**: 複雑な条件ロジック向けの async 関数 -無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: -- ユーザー権限に基づく機能ゲーティング -- 環境別のツール提供（開発 vs 本番） -- ツール構成の A/B テスト +無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です。 +- ユーザー 権限に基づく機能ゲーティング +- 環境別のツール可用性（開発 vs 本番） +- 異なるツール構成の A/B テスト - 実行時状態に基づく動的ツールフィルタリング -## 関数ツールでのエラー処理 +## 関数ツールのエラー処理 -`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM に提供するエラーレスポンスを返す関数です。 +`@function_tool` で関数ツールを作成する際、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM にエラーレスポンスを返す関数です。 -- 既定（何も渡さない場合）では、エラー発生を LLM に伝える `default_tool_error_function` が実行されます。 -- 独自のエラー関数を渡した場合はそれが実行され、その応答が LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しエラーは再スローされ、あなたが処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、あなたのコードがクラッシュした場合は `UserError` などになり得ます。 +- 既定では（何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 +- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、呼び出し側で処理する必要があります。モデルが不正な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -412,4 +412,4 @@ def get_user_profile(user_id: str) -> str: ``` -`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラー処理を行う必要があります。 \ No newline at end of file +`FunctionTool` オブジェクトを手動で作成する場合は、`on_invoke_tool` 関数内でエラーを処理する必要があります。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 8262797d3..8cf65afda 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK には組み込みのトレーシングが含まれており、エージェント実行中のイベントを包括的に記録します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで対象です。[Traces ダッシュボード](https://platform.openai.com/traces)を使って、開発中や本番運用中のワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングがあり、エージェントの実行中に発生するイベント（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベント）を包括的に記録します。 [Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は 2 つあります: + トレーシングはデフォルトで有効です。無効にする方法は 2 つあります: - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます + 2. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行に対してトレーシングを無効化できます -***OpenAI の API を Zero Data Retention (ZDR) ポリシーの下で利用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。複数のスパンで構成されます。トレースには次のプロパティがあります: - - `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 生成に関する情報などが含まれます。 +- **トレース** は「ワークフロー」の単一のエンドツーエンド処理を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `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()` でラップされます -- 音声入力（音声→テキスト）は `transcription_span()` でラップされます -- 音声出力（テキスト→音声）は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の下にネストされる場合があります +- 全体の `Runner.{run, run_sync, run_streamed}()` が `trace()` でラップされます。 +- エージェントが実行されるたびに、`agent_span()` でラップされます +- LLM 生成は `generation_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます +- ガードレールは `guardrail_span()` でラップされます +- ハンドオフは `handoff_span()` でラップされます +- 音声入力（音声認識）は `transcription_span()` でラップされます +- 音声出力（テキスト読み上げ）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親付けされる場合があります -デフォルトのトレース名は "Agent workflow" です。`trace` を使う場合にこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用してこの名前を設定できます。または、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、他の送信先へトレースを送ることができます（置き換え、またはセカンダリ送信先として）。 +さらに、[カスタム トレーシング プロセッサー](#custom-tracing-processors)を設定して、トレースを他の送信先へ送ることができます（置き換え、またはセカンダリ送信先として）。 ## 上位レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、全体のコードを `trace()` でラップします。 +`run()` への複数回の呼び出しを単一のトレースにまとめたい場合があります。これは、コード全体を `trace()` でラップすることで実現できます。 ```python from agents import Agent, Runner, trace @@ -68,43 +68,43 @@ async def main(): ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。次の 2 つの方法があります: +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: -1. 推奨: トレースをコンテキストマネージャーとして使用します（例: `with trace(...) as my_trace`）。これにより適切なタイミングで自動的に開始・終了されます。 +1. 推奨: トレースをコンテキストマネージャとして使用します（例: `with trace(...) as my_trace`）。これにより、適切なタイミングでトレースが自動的に開始・終了されます。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。これにより自動的に並行実行に対応します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これにより、自動的に並行処理で動作します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` および `reset_current` を渡す必要があります。 ## スパンの作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的にはスパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。 +さまざまな [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が用意されています。 -スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される直近の現在スパンの下にネストされます。 +スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡される、最も近い現在のスパンの下にネストされます。 -## 機微情報 +## 機微データ -特定のスパンは機微情報を含む可能性があります。 +一部のスパンは機微なデータを収集する可能性があります。 -`generation_span()` は LLM 生成の入出力を保存し、`function_span()` は関数呼び出しの入出力を保存します。これらに機微情報が含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそれらのデータの収集を無効化できます。 +`generation_span()` は LLM 生成の入出力を保存し、`function_span()` は関数呼び出しの入出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそのデータの収集を無効化できます。 -同様に、音声スパンにはデフォルトで入力・出力音声の base64 エンコードされた PCM データが含まれます。この音声データの収集は、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して無効化できます。 +同様に、音声スパンにはデフォルトで入出力音声の base64 エンコードされた PCM データが含まれます。この音声データの収集は、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して無効化できます。 -## カスタムトレーシングプロセッサー +## カスタム トレーシング プロセッサー -トレーシングの高レベルアーキテクチャは次のとおりです: +トレーシングの高レベルなアーキテクチャは次のとおりです: -- 初期化時にグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成し、これがトレースの作成を担当します。 -- `TraceProvider` には [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、これはトレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。エクスポーターはスパンとトレースを OpenAI バックエンドにバッチでエクスポートします。 +- 初期化時に、トレースの作成を担うグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を構成し、バッチでトレース/スパンを [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。これがスパンとトレースを OpenAI のバックエンドにバッチでエクスポートします。 -このデフォルト構成をカスタマイズして、別のバックエンドや追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります: +このデフォルト設定をカスタマイズして、別のバックエンドに送信したり、追加のバックエンドへも送る、またはエクスポーターの動作を変更するには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備できた時点で受け取る「追加の」トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに「置き換え」られます。これは、OpenAI バックエンドに送信する `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送られないことを意味します。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、生成済みのトレースとスパンを受け取る「追加の」トレースプロセッサーを追加できます。これにより、 OpenAI のバックエンドへの送信に加えて、独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに「置き換え」できます。つまり、 OpenAI のバックエンドにトレースを送信したい場合は、それを行う `TracingProcessor` を含めない限り、トレースは送信されません。 ## OpenAI 以外のモデルでのトレーシング -OpenAI の API キーを非 OpenAI モデルで使用すると、トレーシングを無効化せずに OpenAI の Traces ダッシュボードで無料のトレーシングを有効にできます。 +トレーシングを無効化する必要なく、 OpenAI API キーを OpenAI 以外のモデルで使用して、 OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -125,28 +125,29 @@ agent = Agent( ) ``` -## 備考 -- 無料のトレースは OpenAI Traces ダッシュボードで確認できます。 - -## 外部トレーシングプロセッサー一覧 - -- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) -- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) -- [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) -- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) -- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file +## 注意事項 +- 無料のトレースは OpenAI Traces ダッシュボードで閲覧できます。 + + +## 外部トレーシング プロセッサー一覧 + +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [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) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) +- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file diff --git a/docs/ja/usage.md b/docs/ja/usage.md index f74472055..e8fd28fba 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -2,23 +2,23 @@ search: exclude: true --- -# 利用状況 +# 使用状況 -Agents SDK は各ランのトークン利用状況を自動で追跡します。ランのコンテキストから参照でき、コストの監視、上限の適用、分析記録に活用できます。 +Agents SDK は、すべての実行についてトークン使用状況を自動追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に使えます。 ## 追跡対象 -- **requests**: 行われた LLM API 呼び出し回数 +- **requests**: 実行された LLM API コール数 - **input_tokens**: 送信された入力トークンの合計 - **output_tokens**: 受信した出力トークンの合計 -- **total_tokens**: 入力 + 出力 +- **total_tokens**: input + output - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## ランからの利用状況へのアクセス +## 実行から使用状況へのアクセス -`Runner.run(...)` の後、`result.context_wrapper.usage` から利用状況にアクセスします。 +`Runner.run(...)` の後、`result.context_wrapper.usage` から使用状況にアクセスします。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -利用状況は、ラン中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 +使用状況は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 -### LiteLLM モデルでの usage 有効化 +### LiteLLM モデルでの使用状況の有効化 -LiteLLM プロバイダーは既定では利用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡して、LiteLLM のレスポンスが `result.context_wrapper.usage` を埋めるようにします。 +LiteLLM プロバイダーはデフォルトでは使用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡すと、LiteLLM のレスポンスが `result.context_wrapper.usage` に反映されます。 ```python from agents import Agent, ModelSettings, Runner @@ -50,9 +50,9 @@ result = await Runner.run(agent, "What's the weather in Tokyo?") print(result.context_wrapper.usage.total_tokens) ``` -## セッションでの利用状況へのアクセス +## セッションでの使用状況へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その特定のランの利用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各ランの利用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しはその実行に固有の使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -64,11 +64,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -セッションはラン間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される利用状況メトリクスは、その実行のみを表します。セッションでは前のメッセージが各ランに入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、その特定の実行のみを表します。セッションでは、前のメッセージが各実行の入力として再投入されることがあり、その結果として後続ターンの入力トークン数に影響します。 -## フックでの利用状況の利用 +## フックでの使用状況の利用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なポイントで利用状況を記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクルのタイミングで使用状況を記録できます。 ```python class MyHooks(RunHooks): @@ -79,8 +79,8 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは次をご覧ください: +詳細な API ドキュメントは次をご覧ください。 -- [`Usage`][agents.usage.Usage] - 利用状況の追跡データ構造 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - ランのコンテキストから利用状況へアクセス -- [`RunHooks`][agents.run.RunHooks] - 利用状況トラッキングのライフサイクルにフックする \ No newline at end of file +- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況にアクセス +- [`RunHooks`][agents.run.RunHooks] - 使用状況トラッキングのライフサイクルにフック \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index 9f3cfd7dd..6cd0ce23c 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,7 +4,7 @@ search: --- # エージェントの可視化 -エージェントの可視化により、**Graphviz** を使ってエージェントとその関係の構造化されたグラフィカル表現を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように連携するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を使用してエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: +`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は次のような有向グラフを作成します: -- **エージェント** は黄色のボックスとして表されます。 -- **MCP サーバー** は灰色のボックスとして表されます。 -- **ツール** は緑色の楕円として表されます。 -- **ハンドオフ** はあるエージェントから別のエージェントへの有向辺として表されます。 +- **エージェント** は黄色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** はあるエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -69,24 +69,24 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これにより、**トリアージ エージェント** の構造と、そのサブエージェントやツールへの接続を視覚的に表すグラフが生成されます。 - +これにより、 **triage agent** の構造と、サブエージェントやツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されるグラフには次が含まれます: +生成されたグラフには次が含まれます: -- 入口を示す **開始ノード**（`__start__`）。 -- 黄色で塗りつぶされた **長方形** としてのエージェント。 -- 緑色で塗りつぶされた **楕円** としてのツール。 -- 灰色で塗りつぶされた **長方形** としての MCP サーバー。 -- 相互作用を示す有向辺: - - エージェント間のハンドオフには **実線の矢印**。 - - ツール呼び出しには **点線の矢印**。 - - MCP サーバー呼び出しには **破線の矢印**。 -- 実行の終了箇所を示す **終了ノード**（`__end__`）。 +- エントリーポイントを示す **開始ノード** (`__start__`) +- 黄色で塗りつぶされた **長方形** として表されるエージェント +- 緑色で塗りつぶされた **楕円** として表されるツール +- 灰色で塗りつぶされた **長方形** として表される MCP サーバー +- 相互作用を示す有向エッジ: + - エージェント間のハンドオフには **実線の矢印** + - ツールの呼び出しには **点線の矢印** + - MCP サーバーの呼び出しには **破線の矢印** +- 実行の終了地点を示す **終了ノード** (`__end__`) -**Note:** MCP サーバーは最近の `agents` パッケージのバージョンでレンダリングされます（**v0.2.8** で確認済み）。可視化に MCP のボックスが表示されない場合は、最新版にアップグレードしてください。 +**注意:** MCP サーバーは最近のバージョンの +`agents` パッケージ（ **v0.2.8** で確認）でレンダリングされます。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 8ce4a09f1..ff6f5aa3e 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント的なワークフローを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力を音声に戻す処理まで担当します。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント型ワークフローを音声アプリに変換しやすくするクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検知、適切なタイミングでのワークフロー呼び出し、そしてワークフローの出力を音声に戻す処理を行います。 ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際には、次の項目を設定できます。 +パイプラインを作成する際、次の項目を設定できます。 -1. 新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]。新しい音声が文字起こしされるたびに実行されるコードです。 2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル -3. 次のような設定を可能にする [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - - モデル名をモデルへマッピングできるモデルプロバイダー - - トレーシング（トレーシングの無効化可否、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） - - プロンプト、言語、使用するデータ型などの TTS と STT のモデル設定 +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。次のような項目を設定できます: + - モデルプロバイダー。モデル名をモデルにマッピングできます + - トレーシング。トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など + - TTS と STT モデルの設定。たとえばプロンプト、言語、使用するデータ型など ## パイプラインの実行 パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声を書き起こしたテキストがあり、その結果だけを生成したい場合に使用します。これは、発話の終了検出が不要なケース、たとえば事前録音の音声や、ユーザーの発話終了が明確なプッシュ・トゥ・トークのアプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検出する必要がある場合に使用します。検出された音声チャンクを逐次プッシュでき、ボイスパイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の文字起こしがあり、その結果だけを生成したい場合に使用します。話者が話し終えたタイミングの検知が不要なケース、たとえば事前録音の音声や、ユーザーが話し終わるタイミングが明確なプッシュトゥトークのアプリで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングの検知が必要な場合に使用します。検知された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検知」と呼ばれるプロセスを通じて、適切なタイミングで自動的にエージェントのワークフローを実行します。 ## 結果 -ボイスパイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 +音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次のようなものがあります。 -1. 音声チャンクを含む [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] -2. ターンの開始や終了などのライフサイクルイベントを知らせる [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] -3. エラーイベントである [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]。音声チャンクを含みます。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]。ターンの開始や終了などのライフサイクルイベントを知らせます。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]。エラーイベントです。 ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -Agents SDK は現時点で、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検出された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みに対応したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] のイベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンの音声がすべてディスパッチされた後にトリガーされます。これらのイベントを用いて、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にアンミュートする、といった制御が可能です。 \ No newline at end of file +Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込みサポートを提供していません。代わりに、検知された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示します。`turn_ended` は該当ターンの音声がすべて送出された後に発火します。これらのイベントを用いて、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべてフラッシュした後にミュートを解除する、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 4231f68e5..a84f3fecb 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK の[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声向けの任意依存関係をインストールします: +Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -ここで知っておくべき主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスです: +主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。 -1. 音声をテキストに変換する音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。 -3. 結果のテキストを音声に戻す音声合成モデルを実行します。 +1. 音声認識モデルを実行して、音声をテキストに変換します。 +2. 通常はエージェント主導のワークフローであるあなたのコードを実行して、結果を生成します。 +3. 音声合成モデルを実行して、結果のテキストを音声に戻します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まずエージェントをいくつか設定します。既にこの SDK でエージェントを作成したことがあれば、馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントを設定します。すでにこの SDK でエージェントを作成したことがあれば、見覚えがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -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 753580a1e..2cf3cca89 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -6,13 +6,13 @@ search: [エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレーシングされます。 -基本的なトレーシング情報は上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを構成できます。 +基本的なトレーシング情報は上記のドキュメントをご参照ください。さらに、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを追加で設定できます。 -主なトレーシング関連フィールドは次のとおりです。 +主なトレーシング関連フィールド: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトでは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしなどの機微なデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、ワークフロー (Workflow) 内部で行われる処理には適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 音声データをトレースに含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるためのトレースの `group_id` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかを制御します。既定では有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしなど、機微なデータをトレースに含めるかを制御します。これは特に音声パイプライン向けであり、あなたの 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/ko/agents.md b/docs/ko/agents.md new file mode 100644 index 000000000..177ecea01 --- /dev/null +++ b/docs/ko/agents.md @@ -0,0 +1,289 @@ +--- +search: + exclude: true +--- +# 에이전트 + +에이전트는 앱의 핵심 빌딩 블록입니다. 에이전트는 instructions 및 tools 로 구성된 대규모 언어 모델(LLM)입니다. + +## 기본 구성 + +에이전트를 구성할 때 가장 흔히 사용하는 속성은 다음과 같습니다: + +- `name`: 에이전트를 식별하는 필수 문자열 +- `instructions`: 개발자 메시지 또는 시스템 프롬프트라고도 함 +- `model`: 사용할 LLM 및 temperature, top_p 등 모델 튜닝 매개변수를 설정하는 선택적 `model_settings` +- `tools`: 에이전트가 작업을 수행하기 위해 사용할 수 있는 도구 + +```python +from agents import Agent, ModelSettings, function_tool + +@function_tool +def get_weather(city: str) -> str: + """returns weather info for the specified city.""" + return f"The weather in {city} is sunny" + +agent = Agent( + name="Haiku agent", + instructions="Always respond in haiku form", + model="gpt-5-nano", + tools=[get_weather], +) +``` + +## 컨텍스트 + +에이전트는 `context` 타입에 대해 제네릭합니다. 컨텍스트는 의존성 주입 도구입니다. 이것은 사용자가 생성하여 `Runner.run()`에 전달하는 객체로, 모든 에이전트, 도구, 핸드오프 등에 전달되며 에이전트 실행을 위한 의존성과 상태 묶음 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다. + +```python +@dataclass +class UserContext: + name: str + uid: str + is_pro_user: bool + + async def fetch_purchases() -> list[Purchase]: + return ... + +agent = Agent[UserContext]( + ..., +) +``` + +## 출력 타입 + +기본적으로 에이전트는 일반 텍스트(즉, `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 래핑할 수 있는 모든 타입을 지원합니다. 예: dataclasses, lists, TypedDict 등 + +```python +from pydantic import BaseModel +from agents import Agent + + +class CalendarEvent(BaseModel): + name: str + date: str + participants: list[str] + +agent = Agent( + name="Calendar extractor", + instructions="Extract calendar events from text", + output_type=CalendarEvent, +) +``` + +!!! note + + `output_type`을 전달하면, 모델은 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하도록 지시받습니다. + +## 멀티 에이전트 시스템 설계 패턴 + +멀티 에이전트 시스템을 설계하는 방법은 다양하지만, 일반적으로 두 가지 폭넓게 적용 가능한 패턴이 있습니다: + +1. 매니저(도구로서의 에이전트): 중앙 매니저/오케스트레이터가 특화된 하위 에이전트를 도구처럼 호출하며 대화의 제어를 유지 +2. 핸드오프: 동등한 에이전트 간에 제어를 특화된 에이전트로 넘겨 해당 에이전트가 대화를 이어받는 탈중앙화 패턴 + +자세한 내용은 [에이전트 구축 실무 가이드](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)를 참고하세요. + +### 매니저(도구로서의 에이전트) + +`customer_facing_agent`는 모든 사용자 상호작용을 처리하고 도구로 노출된 특화된 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 참조하세요. + +```python +from agents import Agent + +booking_agent = Agent(...) +refund_agent = Agent(...) + +customer_facing_agent = Agent( + name="Customer-facing agent", + instructions=( + "Handle all direct user communication. " + "Call the relevant tools when specialized expertise is needed." + ), + tools=[ + booking_agent.as_tool( + tool_name="booking_expert", + tool_description="Handles booking questions and requests.", + ), + refund_agent.as_tool( + tool_name="refund_expert", + tool_description="Handles refund questions and requests.", + ) + ], +) +``` + +### 핸드오프 + +핸드오프는 에이전트가 위임할 수 있는 하위 에이전트입니다. 핸드오프가 발생하면, 위임된 에이전트가 대화 내역을 받아 대화를 이어받습니다. 이 패턴은 단일 작업에 특화되어 뛰어난 성능을 발휘하는 모듈식 에이전트를 가능하게 합니다. 자세한 내용은 [핸드오프](handoffs.md) 문서를 참조하세요. + +```python +from agents import Agent + +booking_agent = Agent(...) +refund_agent = Agent(...) + +triage_agent = Agent( + name="Triage agent", + instructions=( + "Help the user with their questions. " + "If they ask about booking, hand off to the booking agent. " + "If they ask about refunds, hand off to the refund agent." + ), + handoffs=[booking_agent, refund_agent], +) +``` + +## 동적 instructions + +대부분의 경우, 에이전트를 생성할 때 instructions 를 제공하면 됩니다. 그러나 함수로 동적 instructions 를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 입력으로 받고, 프롬프트를 반환해야 합니다. 동기 및 `async` 함수 모두 허용됩니다. + +```python +def dynamic_instructions( + context: RunContextWrapper[UserContext], agent: Agent[UserContext] +) -> str: + return f"The user's name is {context.context.name}. Help them with their questions." + + +agent = Agent[UserContext]( + name="Triage agent", + instructions=dynamic_instructions, +) +``` + +## 수명 주기 이벤트(hooks) + +때로는 에이전트의 수명 주기를 관찰하고 싶을 때가 있습니다. 예를 들어, 이벤트를 로깅하거나 특정 이벤트 발생 시 데이터를 미리 가져올 수 있습니다. `hooks` 속성으로 에이전트 수명 주기에 훅을 걸 수 있습니다. [`AgentHooks`][agents.lifecycle.AgentHooks] 클래스를 서브클래싱하고, 관심 있는 메서드를 오버라이드하세요. + +## 가드레일 + +가드레일은 에이전트가 실행되는 동안 사용자 입력에 대한 검사/검증을 병렬로 수행하고, 에이전트 출력이 생성된 후에도 검사를 실행할 수 있게 합니다. 예를 들어, 사용자 입력과 에이전트 출력을 관련성 기준으로 필터링할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 참조하세요. + +## 에이전트 복제/복사 + +에이전트에서 `clone()` 메서드를 사용하면, 에이전트를 복제하고 원하는 속성을 선택적으로 변경할 수 있습니다. + +```python +pirate_agent = Agent( + name="Pirate", + instructions="Write like a pirate", + model="gpt-4.1", +) + +robot_agent = pirate_agent.clone( + name="Robot", + instructions="Write like a robot", +) +``` + +## 도구 사용 강제 + +도구 목록을 제공한다고 해서 LLM 이 반드시 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다: + +1. `auto`: LLM 이 도구 사용 여부를 스스로 결정 +2. `required`: LLM 이 반드시 도구를 사용하되, 어떤 도구를 사용할지는 지능적으로 결정 +3. `none`: LLM 이 도구를 사용하지 _않도록_ 요구 +4. 특정 문자열 설정 예: `my_tool`은 LLM 이 해당 특정 도구를 사용하도록 요구 + +```python +from agents import Agent, Runner, function_tool, ModelSettings + +@function_tool +def get_weather(city: str) -> str: + """Returns weather info for the specified city.""" + return f"The weather in {city} is sunny" + +agent = Agent( + name="Weather Agent", + instructions="Retrieve weather details.", + tools=[get_weather], + model_settings=ModelSettings(tool_choice="get_weather") +) +``` + +## 도구 사용 동작 + +`Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력이 어떻게 처리되는지를 제어합니다: + +- `"run_llm_again"`: 기본값. 도구가 실행되고, LLM 이 결과를 처리하여 최종 응답을 생성 +- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력을 추가 LLM 처리 없이 최종 응답으로 사용 + +```python +from agents import Agent, Runner, function_tool, ModelSettings + +@function_tool +def get_weather(city: str) -> str: + """Returns weather info for the specified city.""" + return f"The weather in {city} is sunny" + +agent = Agent( + name="Weather Agent", + instructions="Retrieve weather details.", + tools=[get_weather], + tool_use_behavior="stop_on_first_tool" +) +``` + +- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나가 호출되면 중지하고, 해당 도구의 출력을 최종 응답으로 사용 + +```python +from agents import Agent, Runner, function_tool +from agents.agent import StopAtTools + +@function_tool +def get_weather(city: str) -> str: + """Returns weather info for the specified city.""" + return f"The weather in {city} is sunny" + +@function_tool +def sum_numbers(a: int, b: int) -> int: + """Adds two numbers.""" + return a + b + +agent = Agent( + name="Stop At Stock Agent", + instructions="Get weather or sum numbers.", + tools=[get_weather, sum_numbers], + tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]) +) +``` + +- `ToolsToFinalOutputFunction`: 도구 결과를 처리하고 중지할지 LLM 으로 계속할지 결정하는 사용자 정의 함수 + +```python +from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper +from agents.agent import ToolsToFinalOutputResult +from typing import List, Any + +@function_tool +def get_weather(city: str) -> str: + """Returns weather info for the specified city.""" + return f"The weather in {city} is sunny" + +def custom_tool_handler( + context: RunContextWrapper[Any], + tool_results: List[FunctionToolResult] +) -> ToolsToFinalOutputResult: + """Processes tool results to decide final output.""" + for result in tool_results: + if result.output and "sunny" in result.output: + return ToolsToFinalOutputResult( + is_final_output=True, + final_output=f"Final weather: {result.output}" + ) + return ToolsToFinalOutputResult( + is_final_output=False, + final_output=None + ) + +agent = Agent( + name="Weather Agent", + instructions="Retrieve weather details.", + tools=[get_weather], + tool_use_behavior=custom_tool_handler +) +``` + +!!! note + + 무한 루프를 방지하기 위해, 프레임워크는 도구 호출 후 자동으로 `tool_choice`를 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]로 구성할 수 있습니다. 무한 루프의 원인은 도구 결과가 LLM 으로 다시 전송되고, `tool_choice` 때문에 LLM 이 또 다른 도구 호출을 생성하기 때문입니다. \ No newline at end of file diff --git a/docs/ko/config.md b/docs/ko/config.md new file mode 100644 index 000000000..4fadd1515 --- /dev/null +++ b/docs/ko/config.md @@ -0,0 +1,98 @@ +--- +search: + exclude: true +--- +# SDK 구성 + +## API 키와 클라이언트 + +기본적으로 SDK 는 가져오자마자 LLM 요청과 트레이싱을 위해 `OPENAI_API_KEY` 환경 변수를 찾습니다. 앱 시작 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다. + +```python +from agents import set_default_openai_key + +set_default_openai_key("sk-...") +``` + +또한 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK 는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용해 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다. + +```python +from openai import AsyncOpenAI +from agents import set_default_openai_client + +custom_client = AsyncOpenAI(base_url="...", api_key="...") +set_default_openai_client(custom_client) +``` + +마지막으로 사용되는 OpenAI API 를 사용자 지정할 수도 있습니다. 기본적으로 OpenAI Responses API 를 사용합니다. [set_default_openai_api()][agents.set_default_openai_api] 함수를 사용해 Chat Completions API 를 사용하도록 재정의할 수 있습니다. + +```python +from agents import set_default_openai_api + +set_default_openai_api("chat_completions") +``` + +## 트레이싱 + +트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. 트레이싱에 사용할 API 키를 지정하려면 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용하세요. + +```python +from agents import set_tracing_export_api_key + +set_tracing_export_api_key("sk-...") +``` + +[`set_tracing_disabled()`][agents.set_tracing_disabled] 함수를 사용해 트레이싱을 완전히 비활성화할 수도 있습니다. + +```python +from agents import set_tracing_disabled + +set_tracing_disabled(True) +``` + +## 디버그 로깅 + +SDK 에는 핸들러가 설정되지 않은 두 개의 Python 로거가 있습니다. 기본적으로 이는 경고와 오류가 `stdout` 으로 전송되고, 그 외 로그는 억제된다는 의미입니다. + +자세한 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요. + +```python +from agents import enable_verbose_stdout_logging + +enable_verbose_stdout_logging() +``` + +또는 핸들러, 필터, 포매터 등을 추가해 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python logging guide](https://docs.python.org/3/howto/logging.html)를 참고하세요. + +```python +import logging + +logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger + +# To make all logs show up +logger.setLevel(logging.DEBUG) +# To make info and above show up +logger.setLevel(logging.INFO) +# To make warning and above show up +logger.setLevel(logging.WARNING) +# etc + +# You can customize this as needed, but this will output to `stderr` by default +logger.addHandler(logging.StreamHandler()) +``` + +### 로그의 민감한 데이터 + +일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. 이러한 데이터가 로그에 남지 않도록 하려면 다음 환경 변수를 설정하세요. + +LLM 입력 및 출력을 로깅하지 않으려면: + +```bash +export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 +``` + +도구 입력 및 출력을 로깅하지 않으려면: + +```bash +export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 +``` \ No newline at end of file diff --git a/docs/ko/context.md b/docs/ko/context.md new file mode 100644 index 000000000..ae4ed77c8 --- /dev/null +++ b/docs/ko/context.md @@ -0,0 +1,82 @@ +--- +search: + exclude: true +--- +# 컨텍스트 관리 + +컨텍스트는 여러 의미로 사용됩니다. 여기서 중요한 컨텍스트는 두 가지 부류가 있습니다: + +1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수 실행 시, `on_handoff` 같은 콜백, 라이프사이클 훅 등에서 필요할 수 있는 데이터와 의존성 +2. LLM 에서 사용할 수 있는 컨텍스트: LLM 이 응답을 생성할 때 볼 수 있는 데이터 + +## 로컬 컨텍스트 + +이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 동작 방식은 다음과 같습니다: + +1. 원하는 Python 객체를 생성합니다. 일반적으로 dataclass 나 Pydantic 객체를 사용합니다. +2. 해당 객체를 다양한 실행 메서드에 전달합니다(예: `Runner.run(..., **context=whatever**)`). +3. 모든 도구 호출, 라이프사이클 훅 등에 `RunContextWrapper[T]` 래퍼 객체가 전달됩니다. 여기서 `T` 는 컨텍스트 객체 타입을 의미하며 `wrapper.context` 를 통해 접근할 수 있습니다. + +가장 중요한 점: 특정 에이전트 실행에 포함되는 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 _타입_ 의 컨텍스트를 사용해야 합니다. + +컨텍스트는 다음과 같은 용도로 사용할 수 있습니다: + +- 실행에 필요한 컨텍스트 데이터(예: 사용자명/uid 또는 사용자에 대한 기타 정보) +- 의존성(예: 로거 객체, 데이터 페처 등) +- 헬퍼 함수 + +!!! danger "주의" + + 컨텍스트 객체는 LLM 에게 **전송되지 않습니다**. 오직 로컬에서만 읽고, 쓰고, 메서드를 호출할 수 있는 객체입니다. + +```python +import asyncio +from dataclasses import dataclass + +from agents import Agent, RunContextWrapper, Runner, function_tool + +@dataclass +class UserInfo: # (1)! + name: str + uid: int + +@function_tool +async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str: # (2)! + """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) + + agent = Agent[UserInfo]( # (3)! + name="Assistant", + tools=[fetch_user_age], + ) + + result = await Runner.run( # (4)! + starting_agent=agent, + input="What is the age of the user?", + context=user_info, + ) + + print(result.final_output) # (5)! + # The user John is 47 years old. + +if __name__ == "__main__": + asyncio.run(main()) +``` + +1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass 를 사용했지만, 어떤 타입이든 사용할 수 있습니다. +2. 이것은 도구입니다. `RunContextWrapper[UserInfo]` 를 받는 것을 볼 수 있습니다. 도구 구현이 컨텍스트에서 값을 읽습니다. +3. 타입 체커가 오류를 잡을 수 있도록 에이전트에 제네릭 `UserInfo` 를 지정합니다(예를 들어, 다른 컨텍스트 타입을 받는 도구를 전달하려 하면 오류를 잡을 수 있음). +4. 컨텍스트가 `run` 함수로 전달됩니다. +5. 에이전트가 도구를 올바르게 호출하여 나이를 가져옵니다. + +## 에이전트/LLM 컨텍스트 + +LLM 이 호출될 때 볼 수 있는 데이터는 대화 기록에서만 옵니다. 즉, LLM 이 새로운 데이터를 볼 수 있게 하려면 해당 데이터를 대화 기록에 포함되도록 해야 합니다. 이를 위한 방법은 다음과 같습니다: + +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. 리트리벌 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져올 수 있는 특수 도구(리트리벌), 혹은 웹에서 가져오는 도구(웹 검색)입니다. 관련 컨텍스트 데이터로 응답을 “그라운딩” 하는 데 유용합니다. \ No newline at end of file diff --git a/docs/ko/examples.md b/docs/ko/examples.md new file mode 100644 index 000000000..b874c868e --- /dev/null +++ b/docs/ko/examples.md @@ -0,0 +1,49 @@ +--- +search: + exclude: true +--- +# 코드 예제 + +[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 코드 예제 섹션에서 SDK의 다양한 샘플 구현을 확인하세요. 예제는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다. + + +## 카테고리 + +- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** + 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 + + - 결정적 워크플로 + - 도구로서의 에이전트 + - 에이전트 병렬 실행 + +- **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** + 이 예제들은 SDK의 기본 기능을 보여줍니다 + + - 동적 시스템 프롬프트 + - 스트리밍 출력 + - 수명주기 이벤트 + +- **[tool examples](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** + 웹 검색 및 파일 검색 같은 OpenAI 호스트하는 도구를 구현하고, + 이를 에이전트에 통합하는 방법을 알아보세요. + +- **[model providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** + OpenAI 가 아닌 모델을 SDK와 함께 사용하는 방법을 알아보세요. + +- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** + 에이전트 핸드오프의 실용적인 예제를 확인하세요. + +- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** + MCP로 에이전트를 구축하는 방법을 알아보세요. + +- **[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):** + 실제 사용 사례를 보여주는 더 완성도 높은 두 가지 예제 + + - **customer_service**: 항공사를 위한 예시 고객 서비스 시스템. + - **research_bot**: 간단한 딥 리서치 클론. + +- **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** + TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요. + +- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** + SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제. \ No newline at end of file diff --git a/docs/ko/guardrails.md b/docs/ko/guardrails.md new file mode 100644 index 000000000..b8b70d6cc --- /dev/null +++ b/docs/ko/guardrails.md @@ -0,0 +1,158 @@ +--- +search: + exclude: true +--- +# 가드레일 + +가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력에 대한 점검 및 검증을 수행합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고 비용이 많이 드는) 모델을 사용하는 에이전트를 생각해 보세요. 악의적인 사용자가 그 모델에게 수학 숙제를 도와 달라고 요청하는 것은 원치 않을 것입니다. 이때 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜, 비용이 큰 모델의 실행을 중단하고 시간/비용을 절약합니다. + +가드레일에는 두 가지 종류가 있습니다: + +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] 예외가 발생하여, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다 + +!!! Note + + 입력 가드레일은 사용자 입력에 대해 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. 왜 `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] 예외가 발생하여, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다 + +!!! Note + + 출력 가드레일은 최종 에이전트 출력에 대해 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 밀접하게 연관되는 경향이 있으므로, 코드를 한곳에 모아 두면 가독성에 도움이 됩니다. + +## 트립와이어 + +입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 감지하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. + +## 가드레일 구현 + +입력을 받고 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예시에서는 내부적으로 에이전트를 실행하여 이를 수행합니다. + +```python +from pydantic import BaseModel +from agents import ( + Agent, + GuardrailFunctionOutput, + InputGuardrailTripwireTriggered, + RunContextWrapper, + Runner, + TResponseInputItem, + input_guardrail, +) + +class MathHomeworkOutput(BaseModel): + is_math_homework: bool + reasoning: str + +guardrail_agent = Agent( # (1)! + name="Guardrail check", + instructions="Check if the user is asking you to do their math homework.", + output_type=MathHomeworkOutput, +) + + +@input_guardrail +async def math_guardrail( # (2)! + ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] +) -> GuardrailFunctionOutput: + result = await Runner.run(guardrail_agent, input, context=ctx.context) + + return GuardrailFunctionOutput( + output_info=result.final_output, # (3)! + tripwire_triggered=result.final_output.is_math_homework, + ) + + +agent = Agent( # (4)! + name="Customer support agent", + instructions="You are a customer support agent. You help customers with their questions.", + input_guardrails=[math_guardrail], +) + +async def main(): + # This should trip the guardrail + try: + await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?") + print("Guardrail didn't trip - this is unexpected") + + except InputGuardrailTripwireTriggered: + print("Math homework guardrail tripped") +``` + +1. 이 에이전트를 가드레일 함수에서 사용합니다 +2. 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다 +3. 가드레일 결과에 추가 정보를 포함할 수 있습니다 +4. 워크플로우를 정의하는 실제 에이전트입니다 + +출력 가드레일도 유사합니다. + +```python +from pydantic import BaseModel +from agents import ( + Agent, + GuardrailFunctionOutput, + OutputGuardrailTripwireTriggered, + RunContextWrapper, + Runner, + output_guardrail, +) +class MessageOutput(BaseModel): # (1)! + response: str + +class MathOutput(BaseModel): # (2)! + reasoning: str + is_math: bool + +guardrail_agent = Agent( + name="Guardrail check", + instructions="Check if the output includes any math.", + output_type=MathOutput, +) + +@output_guardrail +async def math_guardrail( # (3)! + ctx: RunContextWrapper, agent: Agent, output: MessageOutput +) -> GuardrailFunctionOutput: + result = await Runner.run(guardrail_agent, output.response, context=ctx.context) + + return GuardrailFunctionOutput( + output_info=result.final_output, + tripwire_triggered=result.final_output.is_math, + ) + +agent = Agent( # (4)! + name="Customer support agent", + instructions="You are a customer support agent. You help customers with their questions.", + output_guardrails=[math_guardrail], + output_type=MessageOutput, +) + +async def main(): + # This should trip the guardrail + try: + await Runner.run(agent, "Hello, can you help me solve for x: 2x + 3 = 11?") + print("Guardrail didn't trip - this is unexpected") + + except OutputGuardrailTripwireTriggered: + print("Math output guardrail tripped") +``` + +1. 실제 에이전트의 출력 타입입니다 +2. 가드레일의 출력 타입입니다 +3. 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다 +4. 워크플로우를 정의하는 실제 에이전트입니다 \ No newline at end of file diff --git a/docs/ko/handoffs.md b/docs/ko/handoffs.md new file mode 100644 index 000000000..2456d3823 --- /dev/null +++ b/docs/ko/handoffs.md @@ -0,0 +1,118 @@ +--- +search: + exclude: true +--- +# 핸드오프 + +핸드오프를 사용하면 한 에이전트가 다른 에이전트에게 작업을 위임할 수 있습니다. 이는 서로 다른 영역에 특화된 에이전트들이 있는 시나리오에서 특히 유용합니다. 예를 들어 고객 지원 앱에서는 주문 상태, 환불, FAQ 등과 같은 작업을 각각 전담하는 에이전트가 있을 수 있습니다. + +핸드오프는 LLM 에게 도구로 표시됩니다. 예를 들어 `Refund Agent` 라는 에이전트로 핸드오프가 있다면, 도구 이름은 `transfer_to_refund_agent` 가 됩니다. + +## 핸드오프 생성 + +모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, `Agent` 를 직접 전달하거나, 핸드오프를 사용자 지정하는 `Handoff` 객체를 전달할 수 있습니다. + +Agents SDK 에서 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용해 핸드오프를 생성할 수 있습니다. 이 함수는 핸드오프 대상 에이전트를 지정할 수 있으며, 선택적으로 override 와 입력 필터를 설정할 수 있습니다. + +### 기본 사용 + +간단한 핸드오프를 만드는 방법은 다음과 같습니다. + +```python +from agents import Agent, handoff + +billing_agent = Agent(name="Billing agent") +refund_agent = Agent(name="Refund agent") + +# (1)! +triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) +``` + +1. `billing_agent` 처럼 에이전트를 직접 사용할 수도 있고, `handoff()` 함수를 사용할 수도 있습니다 + +### `handoff()` 함수로 핸드오프 사용자 지정 + +[`handoff()`][agents.handoffs.handoff] 함수로 다양한 항목을 사용자 지정할 수 있습니다. + +- `agent`: 핸드오프 대상 에이전트 +- `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 이 사용되며, 이는 `transfer_to_` 으로 결정됩니다. 이를 재정의할 수 있습니다 +- `tool_description_override`: `Handoff.default_tool_description()` 의 기본 도구 설명을 재정의 +- `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출되는 즉시 데이터 페칭을 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 받고, 선택적으로 LLM 이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다 +- `input_type`: 핸드오프에서 기대하는 입력의 타입(선택 사항) +- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 아래 내용을 참고하세요 +- `is_enabled`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수일 수 있어 런타임에 동적으로 활성화/비활성화할 수 있습니다 + +```python +from agents import Agent, handoff, RunContextWrapper + +def on_handoff(ctx: RunContextWrapper[None]): + print("Handoff called") + +agent = Agent(name="My agent") + +handoff_obj = handoff( + agent=agent, + on_handoff=on_handoff, + tool_name_override="custom_handoff_tool", + tool_description_override="Custom description", +) +``` + +## 핸드오프 입력 + +특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하길 원할 수 있습니다. 예를 들어 "에스컬레이션 에이전트" 로의 핸드오프를 상상해 보세요. 로깅을 위해 사유를 제공받고자 할 수 있습니다. + +```python +from pydantic import BaseModel + +from agents import Agent, handoff, RunContextWrapper + +class EscalationData(BaseModel): + reason: str + +async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData): + print(f"Escalation agent called with reason: {input_data.reason}") + +agent = Agent(name="Escalation agent") + +handoff_obj = handoff( + agent=agent, + on_handoff=on_handoff, + input_type=EscalationData, +) +``` + +## 입력 필터 + +핸드오프가 발생하면 마치 새 에이전트가 대화를 인수하는 것처럼 이전 전체 대화 기록을 볼 수 있습니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter] 를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData] 를 통해 기존 입력을 받고, 새로운 `HandoffInputData` 를 반환해야 하는 함수입니다. + +몇 가지 일반적인 패턴(예: 기록에서 모든 도구 호출 제거)이 있으며, 이는 [`agents.extensions.handoff_filters`][] 에 구현되어 있습니다 + +```python +from agents import Agent, handoff +from agents.extensions import handoff_filters + +agent = Agent(name="FAQ agent") + +handoff_obj = handoff( + agent=agent, + input_filter=handoff_filters.remove_all_tools, # (1)! +) +``` + +1. 이는 `FAQ agent` 가 호출될 때 기록에서 모든 도구를 자동으로 제거합니다 + +## 권장 프롬프트 + +LLM 이 핸드오프를 올바로 이해하도록 하려면, 에이전트에 핸드오프에 대한 정보를 포함하는 것을 권장합니다. [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] 의 권장 접두사를 사용하거나, [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] 를 호출하여 권장 데이터를 프롬프트에 자동으로 추가할 수 있습니다. + +```python +from agents import Agent +from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX + +billing_agent = Agent( + name="Billing agent", + instructions=f"""{RECOMMENDED_PROMPT_PREFIX} + .""", +) +``` \ No newline at end of file diff --git a/docs/ko/index.md b/docs/ko/index.md new file mode 100644 index 000000000..113c7f08f --- /dev/null +++ b/docs/ko/index.md @@ -0,0 +1,58 @@ +--- +search: + exclude: true +--- +# OpenAI 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 +- **핸드오프**: 특정 작업에 대해 다른 에이전트에 위임할 수 있게 함 +- **가드레일**: 에이전트 입력과 출력을 검증할 수 있게 함 +- **세션**: 에이전트 실행 간의 대화 기록을 자동으로 유지 관리함 + +파이썬과 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 충분히 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 만들 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버그할 수 있는 기본 **트레이싱**이 포함되어 있으며, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝하는 것도 가능합니다. + +## Agents SDK 사용 이유 + +SDK는 두 가지 설계 원칙을 따릅니다: + +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 학습이 빠르도록 기본 구성 요소는 최소화 +2. 기본 설정만으로도 잘 동작하지만, 동작을 세밀하게 커스터마이즈 가능 + +SDK의 주요 기능은 다음과 같습니다: + +- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 반복하는 내장 에이전트 루프 +- 파이썬 우선: 새로운 추상화를 배우지 않고도 파이썬 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝 +- 핸드오프: 여러 에이전트 간 협업과 위임을 위한 강력한 기능 +- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 수행하고, 실패 시 조기 중단 +- 세션: 에이전트 실행 간 대화 기록을 자동 관리하여 수동 상태 관리 제거 +- 함수 도구: 모든 Python 함수를 도구로 변환하고, 자동 스키마 생성과 Pydantic 기반 검증 제공 +- 트레이싱: 워크플로를 시각화, 디버그, 모니터링할 수 있는 기본 트레이싱과 OpenAI 평가, 파인튜닝, 증류 도구 활용 + +## 설치 + +```bash +pip install openai-agents +``` + +## Hello World 예제 + +```python +from agents import Agent, Runner + +agent = Agent(name="Assistant", instructions="You are a helpful assistant") + +result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") +print(result.final_output) + +# Code within the code, +# Functions calling themselves, +# Infinite loop's dance. +``` + +(_실행하는 경우 `OPENAI_API_KEY` 환경 변수를 설정했는지 확인하세요_) + +```bash +export OPENAI_API_KEY=sk-... +``` \ No newline at end of file diff --git a/docs/ko/mcp.md b/docs/ko/mcp.md new file mode 100644 index 000000000..2f65e0f68 --- /dev/null +++ b/docs/ko/mcp.md @@ -0,0 +1,327 @@ +--- +search: + exclude: true +--- +# Model context protocol (MCP) + +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP)은 애플리케이션이 도구와 컨텍스트를 언어 모델에 노출하는 방식을 표준화합니다. 공식 문서에서: + +> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB-C 포트로 생각해 보세요. USB-C가 다양한 주변기기와 액세서리에 기기를 연결하는 표준화된 방법을 제공하듯이, MCP는 AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방법을 제공합니다. + +Agents Python SDK 는 여러 MCP 전송 방식을 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 자체 구축하여 파일시스템, HTTP, 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. + +## Choosing an MCP integration + +에이전트에 MCP 서버를 연결하기 전에 도구 호출이 어디에서 실행될지와 사용할 수 있는 전송 방식을 결정하세요. 아래 매트릭스는 Python SDK 가 지원하는 옵션을 요약합니다. + +| What you need | Recommended option | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| Let OpenAI's Responses API call a publicly reachable MCP server on the model's behalf| **호스티드 MCP 서버 도구** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| Connect to Streamable HTTP servers that you run locally or remotely | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Talk to servers that implement HTTP with Server-Sent Events | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| Launch a local process and communicate over stdin/stdout | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | + +아래 섹션에서는 각 옵션을 구성하는 방법과 언제 어떤 전송 방식을 선호해야 하는지 살펴봅니다. + +## 1. Hosted MCP server tools + +Hosted tool 은 전체 도구 왕복을 OpenAI 인프라로 이전합니다. 코드에서 도구를 나열하고 호출하는 대신, +[`HostedMCPTool`][agents.tool.HostedMCPTool] 이 서버 레이블(및 선택적 커넥터 메타데이터)을 Responses API 로 전달합니다. 모델은 원격 서버의 도구를 나열하고, Python 프로세스로의 추가 콜백 없이 도구를 호출합니다. Hosted tool 은 현재 Responses API 의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 동작합니다. + +### Basic hosted MCP tool + +에이전트의 `tools` 리스트에 [`HostedMCPTool`][agents.tool.HostedMCPTool] 을 추가하여 hosted tool 을 생성합니다. `tool_config` +딕셔너리는 REST API 에 보낼 JSON 을 그대로 반영합니다: + +```python +import asyncio + +from agents import Agent, HostedMCPTool, Runner + +async def main() -> None: + agent = Agent( + name="Assistant", + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "never", + } + ) + ], + ) + + result = await Runner.run(agent, "Which language is this repository written in?") + print(result.final_output) + +asyncio.run(main()) +``` + +호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers` 에 추가할 필요가 없습니다. + +### Streaming hosted MCP results + +Hosted tool 은 함수 도구와 완전히 동일한 방식으로 스트리밍 결과를 지원합니다. 모델이 아직 실행 중일 때 점진적인 MCP 출력을 소비하려면 `Runner.run_streamed` 에 `stream=True` 를 전달하세요: + +```python +result = Runner.run_streamed(agent, "Summarise this repository's top languages") +async for event in result.stream_events(): + if event.type == "run_item_stream_event": + print(f"Received: {event.item}") +print(result.final_output) +``` + +### Optional approval flows + +서버가 민감한 작업을 수행할 수 있다면 각 도구 실행 전에 사람 또는 프로그램의 승인을 요구할 수 있습니다. `tool_config` 의 `require_approval` 을 단일 정책(`"always"`, `"never"`) 또는 도구 이름을 정책에 매핑한 딕셔너리로 구성하세요. Python 내부에서 결정을 내리려면 `on_approval_request` 콜백을 제공하세요. + +```python +from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest + +SAFE_TOOLS = {"read_project_metadata"} + +def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult: + if request.data.name in SAFE_TOOLS: + return {"approve": True} + return {"approve": False, "reason": "Escalate to a human reviewer"} + +agent = Agent( + name="Assistant", + tools=[ + HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "gitmcp", + "server_url": "https://gitmcp.io/openai/codex", + "require_approval": "always", + }, + on_approval_request=approve_tool, + ) + ], +) +``` + +모델이 실행을 계속하기 위해 승인 데이터가 필요할 때마다 콜백이(동기 또는 비동기) 호출됩니다. + +### Connector-backed hosted servers + +호스티드 MCP 는 OpenAI 커넥터도 지원합니다. `server_url` 대신 `connector_id` 와 액세스 토큰을 제공하세요. +Responses API 가 인증을 처리하고, 호스티드 서버가 커넥터의 도구를 노출합니다. + +```python +import os + +HostedMCPTool( + tool_config={ + "type": "mcp", + "server_label": "google_calendar", + "connector_id": "connector_googlecalendar", + "authorization": os.environ["GOOGLE_CALENDAR_AUTHORIZATION"], + "require_approval": "never", + } +) +``` + +스트리밍, 승인, 커넥터를 포함한 완전한 hosted tool 샘플은 +[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) 에서 확인할 수 있습니다. + +## 2. Streamable HTTP MCP servers + +네트워크 연결을 직접 관리하려면 +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 를 사용하세요. Streamable HTTP 서버는 전송을 직접 제어하거나, 지연 시간을 낮게 유지하면서 자체 인프라 내에서 서버를 실행하고자 할 때 적합합니다. + +```python +import asyncio +import os + +from agents import Agent, Runner +from agents.mcp import MCPServerStreamableHttp +from agents.model_settings import ModelSettings + +async def main() -> None: + token = os.environ["MCP_SERVER_TOKEN"] + async with MCPServerStreamableHttp( + name="Streamable HTTP Python Server", + params={ + "url": "http://localhost:8000/mcp", + "headers": {"Authorization": f"Bearer {token}"}, + "timeout": 10, + }, + cache_tools_list=True, + max_retry_attempts=3, + ) as server: + agent = Agent( + name="Assistant", + instructions="Use the MCP tools to answer the questions.", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), + ) + + result = await Runner.run(agent, "Add 7 and 22.") + print(result.final_output) + +asyncio.run(main()) +``` + +생성자는 다음 추가 옵션을 받습니다: + +- `client_session_timeout_seconds` 는 HTTP 읽기 타임아웃을 제어합니다 +- `use_structured_content` 는 `tool_result.structured_content` 를 텍스트 출력보다 선호할지 여부를 토글합니다 +- `max_retry_attempts` 및 `retry_backoff_seconds_base` 는 `list_tools()` 와 `call_tool()` 에 대한 자동 재시도를 추가합니다 +- `tool_filter` 를 사용하면 도구의 일부만 노출할 수 있습니다([Tool filtering](#tool-filtering) 참조) + +## 3. HTTP with SSE MCP servers + +MCP 서버가 HTTP with SSE 전송을 구현하는 경우 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] 를 인스턴스화하세요. 전송 방식을 제외하면 API 는 Streamable HTTP 서버와 동일합니다. + +```python + +from agents import Agent, Runner +from agents.model_settings import ModelSettings +from agents.mcp import MCPServerSse + +workspace_id = "demo-workspace" + +async with MCPServerSse( + name="SSE Python Server", + params={ + "url": "http://localhost:8000/sse", + "headers": {"X-Workspace": workspace_id}, + }, + cache_tools_list=True, +) as server: + agent = Agent( + name="Assistant", + mcp_servers=[server], + model_settings=ModelSettings(tool_choice="required"), + ) + result = await Runner.run(agent, "What's the weather in Tokyo?") + print(result.final_output) +``` + +## 4. stdio MCP servers + +로컬 하위 프로세스로 실행되는 MCP 서버의 경우 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 를 사용하세요. SDK 는 프로세스를 생성하고 파이프를 열어두며, 컨텍스트 매니저가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른 개념 증명이나 서버가 커맨드라인 엔트리 포인트만 노출하는 경우에 유용합니다. + +```python +from pathlib import Path +from agents import Agent, Runner +from agents.mcp import MCPServerStdio + +current_dir = Path(__file__).parent +samples_dir = current_dir / "sample_files" + +async with MCPServerStdio( + name="Filesystem Server via npx", + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], + }, +) as server: + agent = Agent( + name="Assistant", + instructions="Use the files in the sample directory to answer questions.", + mcp_servers=[server], + ) + result = await Runner.run(agent, "List the files available to you.") + print(result.final_output) +``` + +## Tool filtering + +각 MCP 서버는 에이전트에 필요한 함수만 노출할 수 있도록 도구 필터를 지원합니다. 필터링은 생성 시점 또는 실행마다 동적으로 수행할 수 있습니다. + +### Static tool filtering + +[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] 를 사용해 간단한 허용/차단 목록을 구성하세요: + +```python +from pathlib import Path + +from agents.mcp import MCPServerStdio, create_static_tool_filter + +samples_dir = Path("/path/to/files") + +filesystem_server = MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], + }, + tool_filter=create_static_tool_filter(allowed_tool_names=["read_file", "write_file"]), +) +``` + +`allowed_tool_names` 와 `blocked_tool_names` 가 모두 제공되면 SDK 는 먼저 허용 목록을 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. + +### Dynamic tool filtering + +보다 정교한 로직이 필요하면 [`ToolFilterContext`][agents.mcp.ToolFilterContext] 를 받는 호출 가능 객체를 전달하세요. 이 호출 가능 객체는 동기 또는 비동기일 수 있으며, 도구를 노출해야 할 때 `True` 를 반환합니다. + +```python +from pathlib import Path + +from agents.mcp import MCPServerStdio, ToolFilterContext + +samples_dir = Path("/path/to/files") + +async def context_aware_filter(context: ToolFilterContext, tool) -> bool: + if context.agent.name == "Code Reviewer" and tool.name.startswith("danger_"): + return False + return True + +async with MCPServerStdio( + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", str(samples_dir)], + }, + tool_filter=context_aware_filter, +) as server: + ... +``` + +필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, 그리고 `server_name` 을 제공합니다. + +## 프롬프트 + +MCP 서버는 에이전트 instructions 를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 메서드를 노출합니다: + +- `list_prompts()` 는 사용 가능한 프롬프트 템플릿을 나열합니다 +- `get_prompt(name, arguments)` 는 필요 시 매개변수와 함께 구체적인 프롬프트를 가져옵니다 + +```python +from agents import Agent + +prompt_result = await server.get_prompt( + "generate_code_review_instructions", + {"focus": "security vulnerabilities", "language": "python"}, +) +instructions = prompt_result.messages[0].content.text + +agent = Agent( + name="Code Reviewer", + instructions=instructions, + mcp_servers=[server], +) +``` + +## 캐싱 + +모든 에이전트 실행은 각 MCP 서버에서 `list_tools()` 를 호출합니다. 원격 서버는 눈에 띄는 지연을 유발할 수 있으므로, 모든 MCP 서버 클래스는 `cache_tools_list` 옵션을 제공합니다. 도구 정의가 자주 변경되지 않는다고 확신할 때에만 `True` 로 설정하세요. 이후 새 목록을 강제로 가져오려면 서버 인스턴스에서 `invalidate_tools_cache()` 를 호출하세요. + +## 트레이싱 + +[트레이싱](./tracing.md)은 다음을 포함해 MCP 활동을 자동으로 캡처합니다: + +1. 도구 목록을 가져오기 위한 MCP 서버 호출 +2. 도구 호출의 MCP 관련 정보 + +![MCP 트레이싱 스크린샷](../assets/images/mcp-tracing.jpg) + +## 추가 자료 + +- [Model Context Protocol](https://modelcontextprotocol.io/) – 명세와 설계 가이드 +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 실행 가능한 stdio, SSE, Streamable HTTP 샘플 +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 승인과 커넥터를 포함한 완전한 호스티드 MCP 데모 \ No newline at end of file diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md new file mode 100644 index 000000000..b929e08b4 --- /dev/null +++ b/docs/ko/models/index.md @@ -0,0 +1,192 @@ +--- +search: + exclude: true +--- +# 모델 + +Agents SDK 는 다음 두 가지 방식으로 OpenAI 모델을 기본 지원합니다: + +- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] + +## OpenAI 모델 + +`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)이며, 에이전트 워크플로에서의 예측 가능성과 낮은 지연 시간의 균형이 좋습니다. + +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) 같은 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요. + +### 기본 OpenAI 모델 + +사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. + +```bash +export OPENAI_DEFAULT_MODEL=gpt-5 +python3 my_awesome_agent.py +``` + +#### GPT-5 모델 + +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 등 GPT-5 의 reasoning 모델을 이 방식으로 사용할 때, SDK 는 기본적으로 합리적인 `ModelSettings` 를 적용합니다. 구체적으로 `reasoning.effort` 와 `verbosity` 를 모두 `"low"` 로 설정합니다. 이러한 설정을 직접 구성하려면 `agents.models.get_default_model_settings("gpt-5")` 를 호출하세요. + +더 낮은 지연 시간이나 특정 요구 사항이 있다면 다른 모델과 설정을 선택할 수 있습니다. 기본 모델의 reasoning effort 를 조정하려면 직접 `ModelSettings` 를 전달하세요: + +```python +from openai.types.shared import Reasoning +from agents import Agent, ModelSettings + +my_agent = Agent( + name="My Agent", + instructions="You're a helpful agent.", + model_settings=ModelSettings(reasoning=Reasoning(effort="minimal"), verbosity="low") + # If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only model_settings works. + # It's also fine to pass a GPT-5 model name explicitly: + # model="gpt-5", +) +``` + +특히 지연 시간을 낮추려면 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 모델을 `reasoning.effort="minimal"` 과 함께 사용하면 기본 설정보다 더 빠르게 응답하는 경우가 많습니다. 다만 Responses API 의 일부 내장 도구(예: 파일 검색과 이미지 생성)는 `"minimal"` reasoning effort 를 지원하지 않으므로, Agents SDK 는 기본값으로 `"low"` 를 사용합니다. + +#### 비 GPT-5 모델 + +사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하면, SDK 는 모든 모델과 호환되는 일반적인 `ModelSettings` 로 되돌립니다. + +## 비 OpenAI 모델 + +대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의 의존성 그룹을 설치하세요: + +```bash +pip install "openai-agents[litellm]" +``` + +그런 다음 `litellm/` 접두사를 사용해 [지원되는 모델](https://docs.litellm.ai/docs/providers) 중 아무 것이나 사용하세요: + +```python +claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) +gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) +``` + +### 비 OpenAI 모델을 사용하는 다른 방법 + +다른 LLM 제공자를 통합하는 방법은 추가로 3 가지가 있습니다(예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다): + +1. [`set_default_openai_client`][agents.set_default_openai_client] 는 전역적으로 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 사용하고자 할 때 유용합니다. 이는 LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고 `base_url` 과 `api_key` 를 설정할 수 있는 경우에 해당합니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) 를 참조하세요. +2. [`ModelProvider`][agents.models.interface.ModelProvider] 는 `Runner.run` 레벨에서 사용합니다. 이를 통해 “이번 실행에 포함된 모든 에이전트에 대해 사용자 지정 모델 제공자를 사용”할 수 있습니다. 구성 가능한 예시는 [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) 설정을 권장합니다. + +!!! note + + 이 예시들에서는 대부분의 LLM 제공자가 아직 Responses API 를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. 사용 중인 LLM 제공자가 이를 지원한다면 Responses 사용을 권장합니다. + +## 모델 혼합 및 매칭 + +단일 워크플로 내에서 에이전트마다 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류(트리아지)에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 하나의 방법으로 특정 모델을 선택할 수 있습니다: + +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] 두 형태를 모두 지원하지만, 각 워크플로에는 단일 모델 형태를 사용할 것을 권장합니다. 두 형태는 지원하는 기능과 도구가 다릅니다. 워크플로에 서로 다른 모델 형태의 혼합이 필요한 경우, 사용하는 모든 기능이 양쪽 모두에서 사용 가능한지 확인하세요. + +```python +from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel +import asyncio + +spanish_agent = Agent( + name="Spanish agent", + instructions="You only speak Spanish.", + model="gpt-5-mini", # (1)! +) + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model=OpenAIChatCompletionsModel( # (2)! + model="gpt-5-nano", + openai_client=AsyncOpenAI() + ), +) + +triage_agent = Agent( + name="Triage agent", + instructions="Handoff to the appropriate agent based on the language of the request.", + handoffs=[spanish_agent, english_agent], + model="gpt-5", +) + +async def main(): + result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?") + print(result.final_output) +``` + +1. OpenAI 모델 이름을 직접 설정합니다 +2. [`Model`][agents.models.interface.Model] 구현체를 제공합니다 + +에이전트에 사용되는 모델을 더 세밀하게 구성하려면 `temperature` 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings] 를 전달할 수 있습니다. + +```python +from agents import Agent, ModelSettings + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model="gpt-4.1", + model_settings=ModelSettings(temperature=0.1), +) +``` + +또한 OpenAI 의 Responses API 를 사용할 때 [다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)들(예: `user`, `service_tier` 등)이 있습니다. 최상위 수준에서 제공되지 않는 경우 `extra_args` 를 사용해 함께 전달할 수 있습니다. + +```python +from agents import Agent, ModelSettings + +english_agent = Agent( + name="English agent", + instructions="You only speak English", + model="gpt-4.1", + model_settings=ModelSettings( + temperature=0.1, + extra_args={"service_tier": "flex", "user": "user_12345"}, + ), +) +``` + +## 다른 LLM 제공자 사용 시 흔한 문제 + +### Tracing 클라이언트 오류 401 + +트레이싱 관련 오류가 발생한다면, 이는 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다: + +1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며, 반드시 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다 +3. 비 OpenAI 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 를 참조하세요 + +### Responses API 지원 + +SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 그 결과 404 등의 문제가 발생할 수 있습니다. 해결을 위해 다음 두 가지 옵션이 있습니다: + +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 를 호출하세요. 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우에 동작합니다 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 을 사용하세요. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다 + +### Structured outputs 지원 + +일부 모델 제공자는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 를 지원하지 않습니다. 이로 인해 다음과 유사한 오류가 발생할 수 있습니다: + +``` + +BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' : value is not one of the allowed values ['text','json_object']", 'type': 'invalid_request_error'}} + +``` + +이는 일부 모델 제공자의 한계로, JSON 출력을 지원하지만 출력에 사용할 `json_schema` 를 지정할 수는 없습니다. 이에 대한 해결책을 마련 중이지만, JSON 스키마 출력을 지원하는 제공자에 의존할 것을 권장합니다. 그렇지 않으면 잘못된 JSON 으로 인해 앱이 자주 깨질 수 있습니다. + +## 제공자 간 모델 혼합 + +모델 제공자 간 기능 차이를 인지하지 못하면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 파일 검색과 웹 검색을 지원하지만, 많은 다른 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요: + +- 지원하지 않는 `tools` 를 이해하지 못하는 제공자에게 보내지 말 것 +- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링할 것 +- structured JSON 출력을 지원하지 않는 제공자는 때때로 잘못된 JSON 을 생성할 수 있음을 유의할 것 \ No newline at end of file diff --git a/docs/ko/models/litellm.md b/docs/ko/models/litellm.md new file mode 100644 index 000000000..505ec11f1 --- /dev/null +++ b/docs/ko/models/litellm.md @@ -0,0 +1,94 @@ +--- +search: + exclude: true +--- +# LiteLLM 를 통한 임의 모델 사용 + +!!! note + + LiteLLM 통합은 베타 단계입니다. 특히 소규모 모델 제공자에서 일부 문제가 발생할 수 있습니다. [GitHub 이슈](https://github.com/openai/openai-agents-python/issues)로 보고해 주시면 신속히 수정하겠습니다. + +[LiteLLM](https://docs.litellm.ai/docs/) 는 단일 인터페이스로 100+ 개 모델을 사용할 수 있게 해주는 라이브러리입니다. 에이전트 SDK 에 LiteLLM 통합을 추가하여 어떤 AI 모델이든 사용할 수 있습니다. + +## 설정 + +`litellm` 이 사용 가능해야 합니다. 선택적 `litellm` 종속성 그룹을 설치하면 됩니다: + +```bash +pip install "openai-agents[litellm]" +``` + +완료되면, 어떤 에이전트에서도 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 을 사용할 수 있습니다. + +## 예제 + +다음은 완전한 동작 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 프롬프트가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: + +- `openai/gpt-4.1` 모델과 OpenAI API 키 +- `anthropic/claude-3-5-sonnet-20240620` 모델과 Anthropic API 키 +- 등 + +LiteLLM 에서 지원하는 모델의 전체 목록은 [litellm providers 문서](https://docs.litellm.ai/docs/providers)를 참고하세요. + +```python +from __future__ import annotations + +import asyncio + +from agents import Agent, Runner, function_tool, set_tracing_disabled +from agents.extensions.models.litellm_model import LitellmModel + +@function_tool +def get_weather(city: str): + print(f"[debug] getting weather for {city}") + return f"The weather in {city} is sunny." + + +async def main(model: str, api_key: str): + agent = Agent( + name="Assistant", + instructions="You only respond in haikus.", + model=LitellmModel(model=model, api_key=api_key), + tools=[get_weather], + ) + + result = await Runner.run(agent, "What's the weather in Tokyo?") + print(result.final_output) + + +if __name__ == "__main__": + # First try to get model/api key from args + import argparse + + parser = argparse.ArgumentParser() + parser.add_argument("--model", type=str, required=False) + parser.add_argument("--api-key", type=str, required=False) + args = parser.parse_args() + + model = args.model + if not model: + model = input("Enter a model name for Litellm: ") + + api_key = args.api_key + if not api_key: + api_key = input("Enter an API key for Litellm: ") + + asyncio.run(main(model, api_key)) +``` + +## 사용량 데이터 추적 + +LiteLLM 응답이 에이전트 SDK 사용량 지표에 채워지도록 하려면 에이전트를 생성할 때 `ModelSettings(include_usage=True)` 를 전달하세요. + +```python +from agents import Agent, ModelSettings +from agents.extensions.models.litellm_model import LitellmModel + +agent = Agent( + name="Assistant", + model=LitellmModel(model="your/model", api_key="..."), + model_settings=ModelSettings(include_usage=True), +) +``` + +`include_usage=True` 를 사용하면, LiteLLM 요청은 기본 제공 OpenAI 모델과 마찬가지로 `result.context_wrapper.usage` 를 통해 토큰 및 요청 수를 보고합니다. \ No newline at end of file diff --git a/docs/ko/multi_agent.md b/docs/ko/multi_agent.md new file mode 100644 index 000000000..a7f19d939 --- /dev/null +++ b/docs/ko/multi_agent.md @@ -0,0 +1,41 @@ +--- +search: + exclude: true +--- +# 멀티 에이전트 오케스트레이션 + +오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트가 어떤 순서로 실행되며, 다음에 무엇을 할지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 방법은 두 가지가 있습니다: + +1. LLM 에 의한 의사결정: LLM 의 지능을 활용해 계획하고 추론하며 그에 따라 다음 단계를 결정 +2. 코드에 의한 오케스트레이션: 코드로 에이전트의 흐름을 결정 + +이 패턴들은 섞어 사용할 수 있습니다. 각각의 트레이드오프는 아래에 설명되어 있습니다. + +## LLM 기반 오케스트레이션 + +에이전트는 instructions, tools, 핸드오프 를 갖춘 LLM 입니다. 이는 개방형 과제가 주어졌을 때, LLM 이 도구를 사용해 행동하고 데이터를 수집하며, 핸드오프 를 통해 하위 에이전트에 작업을 위임하면서 과제를 수행할 계획을 자율적으로 세울 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: + +- 웹 검색 으로 온라인에서 정보 찾기 +- 파일 검색 및 검색 기능으로 사내 데이터와 연결에서 탐색 +- 컴퓨터 사용 으로 컴퓨터에서 행동 수행 +- 코드 실행 으로 데이터 분석 수행 +- 계획 수립, 보고서 작성 등에 특화된 에이전트로의 핸드오프. + +이 패턴은 과제가 개방형이며 LLM 의 지능에 의존하고자 할 때 유용합니다. 여기서 가장 중요한 전술은 다음과 같습니다: + +1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 운영해야 할 매개변수 를 명확히 하세요. +2. 앱을 모니터링하고 반복하세요. 어디서 문제가 발생하는지 확인하고 프롬프트를 개선하세요. +3. 에이전트가 자가 성찰하고 개선하도록 하세요. 예를 들어, 루프에서 실행하여 스스로 비판하게 하거나, 오류 메시지를 제공하여 개선하도록 하세요. +4. 모든 것에 능한 범용 에이전트 대신 하나의 작업에 뛰어난 특화 에이전트를 두세요. +5. [evals](https://platform.openai.com/docs/guides/evals) 에 투자하세요. 이를 통해 에이전트를 훈련하여 과제 수행 능력을 개선할 수 있습니다. + +## 코드 기반 오케스트레이션 + +LLM 기반 오케스트레이션은 강력하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정론적이고 예측 가능하게 만듭니다. 여기서 흔한 패턴은 다음과 같습니다: + +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터 를 생성. 예를 들어, 에이전트에게 과제를 몇 가지 카테고리 로 분류하게 한 다음 카테고리 에 따라 다음 에이전트를 선택할 수 있습니다. +- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환하여 여러 에이전트를 체이닝. 블로그 글 작성 같은 과제를 리서치, 개요 작성, 본문 작성, 비평, 개선의 일련의 단계로 분해할 수 있습니다. +- 평가와 피드백을 제공하는 에이전트와 실제 작업을 수행하는 에이전트를 `while` 루프에서 함께 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복 +- `asyncio.gather` 같은 파이썬 기본 구성요소를 통해 여러 에이전트를 병렬로 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용 + +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) 에 여러 code examples 가 있습니다. \ No newline at end of file diff --git a/docs/ko/quickstart.md b/docs/ko/quickstart.md new file mode 100644 index 000000000..36784390a --- /dev/null +++ b/docs/ko/quickstart.md @@ -0,0 +1,203 @@ +--- +search: + exclude: true +--- +# 빠른 시작 + +## 프로젝트 및 가상 환경 생성 + +한 번만 수행하면 됩니다. + +```bash +mkdir my_project +cd my_project +python -m venv .venv +``` + +### 가상 환경 활성화 + +새 터미널 세션을 시작할 때마다 수행하세요. + +```bash +source .venv/bin/activate +``` + +### Agents SDK 설치 + +```bash +pip install openai-agents # or `uv add openai-agents`, etc +``` + +### OpenAI API 키 설정 + +API 키가 없다면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라 OpenAI API 키를 생성하세요. + +```bash +export OPENAI_API_KEY=sk-... +``` + +## 첫 에이전트 생성 + +에이전트는 instructions, 이름, 선택적 config(예: `model_config`)로 정의됩니다. + +```python +from agents import Agent + +agent = Agent( + name="Math Tutor", + instructions="You provide help with math problems. Explain your reasoning at each step and include examples", +) +``` + +## 에이전트 추가 + +추가 에이전트도 동일한 방식으로 정의할 수 있습니다. `handoff_descriptions`는 핸드오프 라우팅을 결정하는 데 필요한 추가 컨텍스트를 제공합니다. + +```python +from agents import Agent + +history_tutor_agent = Agent( + name="History Tutor", + handoff_description="Specialist agent for historical questions", + instructions="You provide assistance with historical queries. Explain important events and context clearly.", +) + +math_tutor_agent = Agent( + name="Math Tutor", + handoff_description="Specialist agent for math questions", + instructions="You provide help with math problems. Explain your reasoning at each step and include examples", +) +``` + +## 핸드오프 정의 + +각 에이전트에서, 작업 진행 방식을 결정하기 위해 선택할 수 있는 아웃바운드 핸드오프 옵션의 목록을 정의할 수 있습니다. + +```python +triage_agent = Agent( + name="Triage Agent", + instructions="You determine which agent to use based on the user's homework question", + handoffs=[history_tutor_agent, math_tutor_agent] +) +``` + +## 에이전트 오케스트레이션 실행 + +워크플로가 실행되고 분류 에이전트가 두 전문 에이전트 간에 올바르게 라우팅하는지 확인해 봅시다. + +```python +from agents import Runner + +async def main(): + result = await Runner.run(triage_agent, "What is the capital of France?") + print(result.final_output) +``` + +## 가드레일 추가 + +입력 또는 출력에 대해 실행할 사용자 정의 가드레일을 정의할 수 있습니다. + +```python +from agents import GuardrailFunctionOutput, Agent, Runner +from pydantic import BaseModel + + +class HomeworkOutput(BaseModel): + is_homework: bool + reasoning: str + +guardrail_agent = Agent( + name="Guardrail check", + instructions="Check if the user is asking about homework.", + output_type=HomeworkOutput, +) + +async def homework_guardrail(ctx, agent, input_data): + result = await Runner.run(guardrail_agent, input_data, context=ctx.context) + final_output = result.final_output_as(HomeworkOutput) + return GuardrailFunctionOutput( + output_info=final_output, + tripwire_triggered=not final_output.is_homework, + ) +``` + +## 전체 통합 + +모두 통합하여 핸드오프와 입력 가드레일을 사용해 전체 워크플로를 실행해 봅시다. + +```python +from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner +from agents.exceptions import InputGuardrailTripwireTriggered +from pydantic import BaseModel +import asyncio + +class HomeworkOutput(BaseModel): + is_homework: bool + reasoning: str + +guardrail_agent = Agent( + name="Guardrail check", + instructions="Check if the user is asking about homework.", + output_type=HomeworkOutput, +) + +math_tutor_agent = Agent( + name="Math Tutor", + handoff_description="Specialist agent for math questions", + instructions="You provide help with math problems. Explain your reasoning at each step and include examples", +) + +history_tutor_agent = Agent( + name="History Tutor", + handoff_description="Specialist agent for historical questions", + instructions="You provide assistance with historical queries. Explain important events and context clearly.", +) + + +async def homework_guardrail(ctx, agent, input_data): + result = await Runner.run(guardrail_agent, input_data, context=ctx.context) + final_output = result.final_output_as(HomeworkOutput) + return GuardrailFunctionOutput( + output_info=final_output, + tripwire_triggered=not final_output.is_homework, + ) + +triage_agent = Agent( + name="Triage Agent", + instructions="You determine which agent to use based on the user's homework question", + handoffs=[history_tutor_agent, math_tutor_agent], + input_guardrails=[ + InputGuardrail(guardrail_function=homework_guardrail), + ], +) + +async def main(): + # 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)로 이동해 실행 트레이스를 확인하세요. + +## 다음 단계 + +더 복잡한 에이전트 플로우를 만드는 방법을 알아보세요: + +- 에이전트 구성 방법을 알아보세요: [에이전트](agents.md) +- 에이전트 실행에 대해 알아보세요: [에이전트 실행](running_agents.md) +- [도구](tools.md), [가드레일](guardrails.md), [모델](models/index.md)에 대해 알아보세요. \ No newline at end of file diff --git a/docs/ko/realtime/guide.md b/docs/ko/realtime/guide.md new file mode 100644 index 000000000..0b632d7b9 --- /dev/null +++ b/docs/ko/realtime/guide.md @@ -0,0 +1,176 @@ +--- +search: + exclude: true +--- +# 가이드 + +이 가이드는 OpenAI Agents SDK의 실시간 기능을 사용하여 음성 지원 AI 에이전트를 구축하는 방법을 자세히 설명합니다. + +!!! warning "Beta feature" +실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 호환성이 깨지는 변경이 발생할 수 있습니다. + +## 개요 + +실시간 에이전트는 실시간으로 오디오와 텍스트 입력을 처리하고 실시간 오디오로 응답하는 대화 흐름을 제공합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 지연 시간이 낮은 자연스러운 음성 대화를 가능하게 하고, 인터럽션(중단 처리)을 우아하게 처리할 수 있습니다. + +## 아키텍처 + +### 핵심 구성 요소 + +실시간 시스템은 다음과 같은 핵심 구성 요소로 이루어집니다: + +- **RealtimeAgent**: instructions, tools 및 핸드오프로 구성된 에이전트 +- **RealtimeRunner**: 구성을 관리합니다. `runner.run()`을 호출해 세션을 가져올 수 있습니다 +- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 생성하고 대화가 끝날 때까지 유지합니다 +- **RealtimeModel**: 기본 모델 인터페이스(일반적으로 OpenAI의 WebSocket 구현) + +### 세션 흐름 + +일반적인 실시간 세션의 흐름은 다음과 같습니다: + +1. instructions, tools 및 핸드오프로 **RealtimeAgent(들)을 생성** +2. 에이전트와 구성 옵션으로 **RealtimeRunner 설정** +3. `await runner.run()`을 사용해 **세션 시작**하고 RealtimeSession을 반환받음 +4. `send_audio()` 또는 `send_message()`로 **오디오 또는 텍스트 메시지 전송** +5. 세션을 순회(iterate)하여 **이벤트 수신** - 오디오 출력, 전사, 도구 호출, 핸드오프, 오류 등을 포함 +6. 사용자가 에이전트 말에 겹쳐 말할 때 **인터럽션 처리**, 현재 오디오 생성을 자동으로 중단 + +세션은 대화 이력을 유지하고 실시간 모델과의 지속 연결을 관리합니다. + +## 에이전트 구성 + +RealtimeAgent는 일반 Agent 클래스와 유사하게 동작하지만 몇 가지 중요한 차이점이 있습니다. 전체 API 세부 정보는 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 레퍼런스를 참조하세요. + +일반 에이전트와의 주요 차이점: + +- 모델 선택은 에이전트 수준이 아니라 세션 수준에서 구성됨 +- structured output 지원 없음 (`outputType`은 지원되지 않음) +- 음성(voice)은 에이전트별로 구성할 수 있으나, 첫 번째 에이전트가 말하기 시작한 후에는 변경 불가 +- 도구, 핸드오프, instructions 등 기타 기능은 동일하게 동작 + +## 세션 구성 + +### 모델 설정 + +세션 구성으로 기본 실시간 모델의 동작을 제어할 수 있습니다. 모델 이름(예: `gpt-realtime`), 음성 선택(alloy, echo, fable, onyx, nova, shimmer), 지원 모달리티(텍스트 및/또는 오디오)를 설정할 수 있습니다. 오디오 형식은 입력과 출력 모두에 대해 설정할 수 있으며, 기본값은 PCM16입니다. + +### 오디오 구성 + +오디오 설정은 세션이 음성 입력과 출력을 처리하는 방식을 제어합니다. Whisper와 같은 모델로 입력 오디오 전사를 구성하고, 언어를 지정하며, 도메인 특화 용어의 정확성을 높이기 위한 전사 프롬프트를 제공할 수 있습니다. 턴 감지 설정으로 에이전트가 언제 응답을 시작하고 멈춰야 하는지 제어하며, 음성 활동 감지 임계값, 침묵 지속 시간, 감지된 음성 주변 패딩 옵션을 제공합니다. + +## 도구 및 함수 + +### 도구 추가 + +일반 에이전트와 마찬가지로, 실시간 에이전트는 대화 중 실행되는 함수 도구를 지원합니다: + +```python +from agents import function_tool + +@function_tool +def get_weather(city: str) -> str: + """Get current weather for a city.""" + # Your weather API logic here + return f"The weather in {city} is sunny, 72°F" + +@function_tool +def book_appointment(date: str, time: str, service: str) -> str: + """Book an appointment.""" + # Your booking logic here + return f"Appointment booked for {service} on {date} at {time}" + +agent = RealtimeAgent( + name="Assistant", + instructions="You can help with weather and appointments.", + tools=[get_weather, book_appointment], +) +``` + +## 핸드오프 + +### 핸드오프 생성 + +핸드오프를 사용하면 특화된 에이전트 간에 대화를 전환할 수 있습니다. + +```python +from agents.realtime import realtime_handoff + +# Specialized agents +billing_agent = RealtimeAgent( + name="Billing Support", + instructions="You specialize in billing and payment issues.", +) + +technical_agent = RealtimeAgent( + name="Technical Support", + instructions="You handle technical troubleshooting.", +) + +# Main agent with handoffs +main_agent = RealtimeAgent( + name="Customer Service", + instructions="You are the main customer service agent. Hand off to specialists when needed.", + handoffs=[ + realtime_handoff(billing_agent, tool_description="Transfer to billing support"), + realtime_handoff(technical_agent, tool_description="Transfer to technical support"), + ] +) +``` + +## 이벤트 처리 + +세션은 세션 객체를 순회하여 수신할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작/종료, 에이전트 핸드오프, 오류가 포함됩니다. 특히 처리해야 할 주요 이벤트는 다음과 같습니다: + +- **audio**: 에이전트 응답의 원시 오디오 데이터 +- **audio_end**: 에이전트 발화 종료 +- **audio_interrupted**: 사용자가 에이전트를 중단함 +- **tool_start/tool_end**: 도구 실행 라이프사이클 +- **handoff**: 에이전트 핸드오프 발생 +- **error**: 처리 중 오류 발생 + +전체 이벤트 세부 정보는 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]를 참조하세요. + +## 가드레일 + +실시간 에이전트는 출력 가드레일만 지원합니다. 실시간 생성 중 성능 문제를 방지하기 위해 이 가드레일은 디바운스되어 주기적으로 실행되며(모든 단어마다 실행되지 않음), 기본 디바운스 길이는 100자이며 구성 가능합니다. + +가드레일은 `RealtimeAgent`에 직접 연결하거나 세션의 `run_config`를 통해 제공할 수 있습니다. 두 소스의 가드레일은 함께 실행됩니다. + +```python +from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail + +def sensitive_data_check(context, agent, output): + return GuardrailFunctionOutput( + tripwire_triggered="password" in output, + output_info=None, + ) + +agent = RealtimeAgent( + name="Assistant", + instructions="...", + output_guardrails=[OutputGuardrail(guardrail_function=sensitive_data_check)], +) +``` + +가드레일이 트리거되면 `guardrail_tripped` 이벤트를 생성하고 에이전트의 현재 응답을 인터럽트할 수 있습니다. 디바운스 동작은 안전성과 실시간 성능 요구 간의 균형을 맞추는 데 도움이 됩니다. 텍스트 에이전트와 달리, 실시간 에이전트는 가드레일이 작동해도 예외를 발생시키지 않습니다. + +## 오디오 처리 + +[`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] 인터페이스에 직접 접근할 수 있습니다. + +## 코드 예제 + +완전한 동작 code examples는 UI 구성 요소가 있는 경우와 없는 경우의 데모를 포함한 [examples/realtime 디렉터리](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)를 확인하세요. \ No newline at end of file diff --git a/docs/ko/realtime/quickstart.md b/docs/ko/realtime/quickstart.md new file mode 100644 index 000000000..acbb356e6 --- /dev/null +++ b/docs/ko/realtime/quickstart.md @@ -0,0 +1,232 @@ +--- +search: + exclude: true +--- +# 빠른 시작 + +실시간 에이전트는 OpenAI의 Realtime API를 사용해 AI 에이전트와 음성 대화를 가능하게 합니다. 이 가이드는 첫 실시간 음성 에이전트를 만드는 과정을 안내합니다. + +!!! warning "베타 기능" +실시간 에이전트는 베타 단계입니다. 구현을 개선하는 동안 호환성 깨짐이 발생할 수 있습니다. + +## 사전 준비 + +- 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. 러너 설정 + +```python +runner = RealtimeRunner( + starting_agent=agent, + config={ + "model_settings": { + "model_name": "gpt-realtime", + "voice": "ash", + "modalities": ["audio"], + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": {"model": "gpt-4o-mini-transcribe"}, + "turn_detection": {"type": "semantic_vad", "interrupt_response": True}, + } + } +) +``` + +### 4. 세션 시작 + +```python +# 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: + try: + if event.type == "agent_start": + print(f"Agent started: {event.agent.name}") + elif event.type == "agent_end": + print(f"Agent ended: {event.agent.name}") + elif event.type == "handoff": + print(f"Handoff from {event.from_agent.name} to {event.to_agent.name}") + elif event.type == "tool_start": + print(f"Tool started: {event.tool.name}") + elif event.type == "tool_end": + print(f"Tool ended: {event.tool.name}; output: {event.output}") + elif event.type == "audio_end": + print("Audio ended") + elif event.type == "audio": + # Enqueue audio for callback-based playback with metadata + # Non-blocking put; queue is unbounded, so drops won’t occur. + pass + elif event.type == "audio_interrupted": + print("Audio interrupted") + # Begin graceful fade + flush in the audio callback and rebuild jitter buffer. + elif event.type == "error": + print(f"Error: {event.error}") + elif event.type == "history_updated": + pass # Skip these frequent events + elif event.type == "history_added": + pass # Skip these frequent events + elif event.type == "raw_model_event": + print(f"Raw model event: {_truncate_str(str(event.data), 200)}") + else: + print(f"Unknown event type: {event.type}") + except Exception as e: + print(f"Error processing event: {_truncate_str(str(e), 200)}") + +def _truncate_str(s: str, max_length: int) -> str: + if len(s) > max_length: + return s[:max_length] + "..." + return s +``` + +## 전체 코드 예제 + +다음은 완전한 동작 예제입니다: + +```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-realtime", + "voice": "ash", + "modalities": ["audio"], + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": {"model": "gpt-4o-mini-transcribe"}, + "turn_detection": {"type": "semantic_vad", "interrupt_response": True}, + } + }, + ) + # 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: + try: + if event.type == "agent_start": + print(f"Agent started: {event.agent.name}") + elif event.type == "agent_end": + print(f"Agent ended: {event.agent.name}") + elif event.type == "handoff": + print(f"Handoff from {event.from_agent.name} to {event.to_agent.name}") + elif event.type == "tool_start": + print(f"Tool started: {event.tool.name}") + elif event.type == "tool_end": + print(f"Tool ended: {event.tool.name}; output: {event.output}") + elif event.type == "audio_end": + print("Audio ended") + elif event.type == "audio": + # Enqueue audio for callback-based playback with metadata + # Non-blocking put; queue is unbounded, so drops won’t occur. + pass + elif event.type == "audio_interrupted": + print("Audio interrupted") + # Begin graceful fade + flush in the audio callback and rebuild jitter buffer. + elif event.type == "error": + print(f"Error: {event.error}") + elif event.type == "history_updated": + pass # Skip these frequent events + elif event.type == "history_added": + pass # Skip these frequent events + elif event.type == "raw_model_event": + print(f"Raw model event: {_truncate_str(str(event.data), 200)}") + else: + print(f"Unknown event type: {event.type}") + except Exception as e: + print(f"Error processing event: {_truncate_str(str(e), 200)}") + +def _truncate_str(s: str, max_length: int) -> str: + if len(s) > max_length: + return s[:max_length] + "..." + return s + +if __name__ == "__main__": + # Run the session + asyncio.run(main()) +``` + +## 구성 옵션 + +### 모델 설정 + +- `model_name`: 사용 가능한 실시간 모델 중 선택 (예: `gpt-realtime`) +- `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`: 발화 전 오디오 패딩 + +## 다음 단계 + +- [실시간 에이전트 더 알아보기](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/ko/release.md b/docs/ko/release.md new file mode 100644 index 000000000..8c1b7499c --- /dev/null +++ b/docs/ko/release.md @@ -0,0 +1,32 @@ +--- +search: + exclude: true +--- +# 릴리스 프로세스/변경 로그 + +이 프로젝트는 `0.Y.Z` 형태의 약간 수정된 시맨틱 버전 관리를 따릅니다. 선행 `0`은 SDK가 여전히 빠르게 발전 중임을 나타냅니다. 각 구성 요소는 다음과 같이 증가합니다: + +## 마이너(`Y`) 버전 + +베타로 표시되지 않은 모든 퍼블릭 인터페이스에 **호환성 파괴 변경**이 있을 경우 마이너 버전 `Y`를 증가시킵니다. 예를 들어, `0.0.x`에서 `0.1.x`로의 변경에는 호환성 파괴 변경이 포함될 수 있습니다. + +호환성 파괴 변경을 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. + +## 패치(`Z`) 버전 + +호환성 파괴가 없는 변경에 대해 `Z`를 증가시킵니다: + +- 버그 수정 +- 새로운 기능 +- 프라이빗 인터페이스 변경 +- 베타 기능 업데이트 + +## 호환성 파괴 변경 로그 + +### 0.2.0 + +이 버전에서는 이전에 `Agent`를 인자로 받던 몇몇 위치가 이제 `AgentBase`를 인자로 받도록 변경되었습니다. 예: MCP 서버의 `list_tools()` 호출. 이는 순수하게 타입 관련 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트하려면 타입 오류를 `Agent`를 `AgentBase`로 대체하여 수정하면 됩니다. + +### 0.1.0 + +이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 두 개의 새로운 매개변수 `run_context`와 `agent`가 추가되었습니다. `MCPServer`를 상속하는 모든 클래스에 이 매개변수들을 추가해야 합니다. \ No newline at end of file diff --git a/docs/ko/repl.md b/docs/ko/repl.md new file mode 100644 index 000000000..3e1fcfb6b --- /dev/null +++ b/docs/ko/repl.md @@ -0,0 +1,23 @@ +--- +search: + exclude: true +--- +# REPL 유틸리티 + +SDK 는 터미널에서 에이전트의 동작을 빠르고 상호작용적으로 테스트할 수 있도록 `run_demo_loop` 를 제공합니다. + +```python +import asyncio +from agents import Agent, run_demo_loop + +async def main() -> None: + agent = Agent(name="Assistant", instructions="You are a helpful assistant.") + await run_demo_loop(agent) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +`run_demo_loop` 는 루프에서 사용자 입력을 요청하며, 턴 사이의 대화 기록을 유지합니다. 기본적으로 생성되는 대로 모델 출력을 스트리밍합니다. 위의 예제를 실행하면, run_demo_loop 가 대화형 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 사이의 전체 대화 기록을 기억하여(에이전트가 어떤 내용이 논의되었는지 알 수 있도록) 생성되는 즉시 에이전트의 응답을 실시간으로 자동 스트리밍합니다. + +이 채팅 세션을 종료하려면 `quit` 또는 `exit` 를 입력하고 Enter 를 누르거나 `Ctrl-D` 키보드 단축키를 사용하세요. \ No newline at end of file diff --git a/docs/ko/results.md b/docs/ko/results.md new file mode 100644 index 000000000..bc7647e18 --- /dev/null +++ b/docs/ko/results.md @@ -0,0 +1,56 @@ +--- +search: + exclude: true +--- +# 결과 + +`Runner.run` 메서드를 호출하면 다음 중 하나를 받습니다: + +- [`RunResult`][agents.result.RunResult] (`run` 또는 `run_sync` 호출 시) +- [`RunResultStreaming`][agents.result.RunResultStreaming] (`run_streamed` 호출 시) + +이 둘은 모두 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, 대부분의 유용한 정보가 여기에 포함됩니다. + +## 최종 출력 + +[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이는 다음 중 하나입니다: + +- 마지막 에이전트에 `output_type`이 정의되지 않은 경우 `str` +- 에이전트에 출력 타입이 정의된 경우 `last_agent.output_type` 타입의 객체 + +!!! note + + `final_output`의 타입은 `Any`입니다. 핸드오프 때문에 정적으로 타입을 지정할 수 없습니다. 핸드오프가 발생하면 어떤 에이전트든 마지막 에이전트가 될 수 있으므로, 가능한 출력 타입 집합을 정적으로 알 수 없습니다. + +## 다음 턴 입력 + +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list]를 사용해 결과를 입력 리스트로 변환할 수 있습니다. 이는 사용자가 제공한 원래 입력과 에이전트 실행 중 생성된 항목들을 이어붙인 것입니다. 이를 통해 한 번의 에이전트 실행 결과를 다음 실행에 전달하거나, 루프에서 실행하면서 매번 새로운 사용자 입력을 추가하기에 편리합니다. + +## 마지막 에이전트 + +[`last_agent`][agents.result.RunResultBase.last_agent] 속성에는 마지막으로 실행된 에이전트가 들어 있습니다. 애플리케이션에 따라 다음에 사용자 입력이 들어올 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. + +## 새 항목 + +[`new_items`][agents.result.RunResultBase.new_items] 속성에는 실행 중에 생성된 새 항목이 들어 있습니다. 항목은 [`RunItem`][agents.items.RunItem]입니다. 실행 항목은 LLM이 생성한 원문 항목을 래핑합니다. + +- [`MessageOutputItem`][agents.items.MessageOutputItem]은 LLM의 메시지를 나타냅니다. 원문 항목은 생성된 메시지입니다 +- [`HandoffCallItem`][agents.items.HandoffCallItem]은 LLM이 핸드오프 도구를 호출했음을 나타냅니다. 원문 항목은 LLM의 도구 호출 항목입니다 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem]은 핸드오프가 발생했음을 나타냅니다. 원문 항목은 핸드오프 도구 호출에 대한 도구 응답입니다. 항목에서 소스/타깃 에이전트에도 접근할 수 있습니다 +- [`ToolCallItem`][agents.items.ToolCallItem]은 LLM이 도구를 호출했음을 나타냅니다 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]은 도구가 호출되었음을 나타냅니다. 원문 항목은 도구 응답입니다. 항목에서 도구 출력에도 접근할 수 있습니다 +- [`ReasoningItem`][agents.items.ReasoningItem]은 LLM의 추론 항목을 나타냅니다. 원문 항목은 생성된 추론입니다 + +## 기타 정보 + +### 가드레일 결과 + +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] 및 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] 속성에는 (있는 경우) 가드레일의 결과가 들어 있습니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 포함될 수 있어, 이를 제공해 드립니다. + +### 원문 응답 + +[`raw_responses`][agents.result.RunResultBase.raw_responses] 속성에는 LLM이 생성한 [`ModelResponse`][agents.items.ModelResponse]가 들어 있습니다. + +### 원래 입력 + +[`input`][agents.result.RunResultBase.input] 속성에는 `run` 메서드에 제공한 원래 입력이 들어 있습니다. 대부분의 경우 필요하지 않지만, 필요한 경우를 대비해 제공됩니다. \ No newline at end of file diff --git a/docs/ko/running_agents.md b/docs/ko/running_agents.md new file mode 100644 index 000000000..175a0323b --- /dev/null +++ b/docs/ko/running_agents.md @@ -0,0 +1,142 @@ +--- +search: + exclude: true +--- +# 에이전트 실행 + +에이전트는 [`Runner`][agents.run.Runner] 클래스를 통해 실행할 수 있습니다. 옵션은 3가지입니다: + +1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult] 를 반환 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드로, 내부적으로 `.run()` 을 실행 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환. LLM 을 스트리밍 모드로 호출하고, 수신되는 대로 이벤트를 스트리밍 + +```python +from agents import Agent, Runner + +async def main(): + agent = Agent(name="Assistant", instructions="You are a helpful assistant") + + result = await Runner.run(agent, "Write a haiku about recursion in programming.") + print(result.final_output) + # Code within the code, + # Functions calling themselves, + # Infinite loop's dance +``` + +자세한 내용은 [결과 가이드](results.md)를 참고하세요. + +## 에이전트 루프 + +`Runner` 의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API 의 입력 항목 리스트가 될 수 있습니다. + +런너는 다음과 같은 루프를 실행합니다: + +1. 현재 에이전트와 현재 입력으로 LLM 을 호출합니다 +2. LLM 이 출력을 생성합니다 + 1. LLM 이 `final_output` 을 반환하면 루프가 종료되고 결과를 반환합니다 + 2. LLM 이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 다시 실행합니다 + 3. LLM 이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프를 다시 실행합니다 +3. 전달된 `max_turns` 를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생시킵니다 + +!!! note + + LLM 출력이 "최종 출력"으로 간주되는 규칙은, 원하는 유형의 텍스트 출력을 생성했고 도구 호출이 없는 경우입니다. + +## 스트리밍 + +스트리밍을 사용하면 LLM 이 실행되는 동안 스트리밍 이벤트를 추가로 수신할 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming] 에는 실행에 대한 완전한 정보와 생성된 모든 새 출력이 포함됩니다. 스트리밍 이벤트는 `.stream_events()` 를 호출하여 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)에서 확인하세요. + +## 실행 구성 + +`run_config` 매개변수로 에이전트 실행에 대한 전역 설정을 구성할 수 있습니다: + +- [`model`][agents.run.RunConfig.model]: 각 Agent 가 가진 `model` 과 무관하게 사용할 전역 LLM 모델을 설정 +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름을 조회하는 모델 프로바이더로, 기본값은 OpenAI +- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의. 예를 들어 전역 `temperature` 또는 `top_p` 를 설정 가능 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 리스트 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 입력 필터가 이미 없는 경우 모든 핸드오프에 적용할 전역 입력 필터. 입력 필터는 새 에이전트에 전달되는 입력을 수정할 수 있게 합니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고하세요 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md) 비활성화 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM 및 도구 호출의 입력/출력 등 민감할 수 있는 데이터가 트레이스에 포함될지 여부를 구성 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, 트레이스 ID, 트레이스 그룹 ID 를 설정. 최소한 `workflow_name` 설정을 권장. 그룹 ID 는 선택 사항으로 여러 실행에 걸쳐 트레이스를 연결할 수 있음 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터 + +## 대화/채팅 스레드 + +어떤 run 메서드를 호출하든 하나 이상의 에이전트가 실행될 수 있으며(따라서 하나 이상의 LLM 호출), 채팅 대화의 단일 논리적 턴을 나타냅니다. 예: + +1. 사용자 턴: 사용자가 텍스트 입력 +2. Runner 실행: 첫 번째 에이전트가 LLM 을 호출하고 도구를 실행하고 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성 + +에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어, 에이전트가 생성한 모든 새 항목을 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있고, 그 경우 run 메서드를 다시 호출하면 됩니다. + +### 수동 대화 관리 + +다음 턴의 입력을 얻기 위해 [`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?") + print(result.final_output) + # San Francisco + + # Second turn + new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}] + result = await Runner.run(agent, new_input) + print(result.final_output) + # 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") + + 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?", 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)를 참고하세요. + +## 장기 실행 에이전트 & 휴먼인더루프 (HITL) + +Agents SDK 의 [Temporal](https://temporal.io/) 통합을 사용하면 휴먼인더루프 작업을 포함한 내구성 있는 장기 실행 워크플로를 실행할 수 있습니다. 장기 실행 작업을 완료하기 위해 Temporal 과 Agents SDK 가 함께 동작하는 데모를 [이 영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 확인하고, [문서는 여기](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)에서 확인하세요. + +## 예외 + +SDK 는 특정 경우 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][] 에 있습니다. 개요는 다음과 같습니다: + +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 내에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 구체적 예외가 파생되는 일반적인 타입입니다 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과했을 때 발생합니다. 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기반 모델(LLM) 이 예기치 않거나 유효하지 않은 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다: + - 잘못된 JSON: 특히 특정 `output_type` 이 정의된 경우, 모델이 도구 호출 또는 직접 출력에 대해 잘못된 JSON 구조를 제공하는 경우 + - 예기치 않은 도구 관련 실패: 모델이 예상 방식으로 도구를 사용하지 못하는 경우 +- [`UserError`][agents.exceptions.UserError]: SDK 를 사용하는 코드 작성자인 사용자가 SDK 사용 중 오류를 저질렀을 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성, SDK API 오용에서 비롯됩니다 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 각각 입력 가드레일 또는 출력 가드레일 조건이 충족될 때 발생합니다. 입력 가드레일은 처리 전에 들어오는 메시지를 확인하고, 출력 가드레일은 에이전트의 최종 응답을 전달하기 전에 확인합니다 \ No newline at end of file diff --git a/docs/ko/sessions.md b/docs/ko/sessions.md new file mode 100644 index 000000000..0041648d3 --- /dev/null +++ b/docs/ko/sessions.md @@ -0,0 +1,407 @@ +--- +search: + exclude: true +--- +# 세션 + +Agents SDK 는 여러 에이전트 실행(run) 간 대화 기록을 자동으로 유지하는 빌트인 세션 메모리를 제공하여, 턴마다 `.to_input_list()` 를 수동으로 처리할 필요를 없앱니다. + +세션은 특정 세션에 대한 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억하기를 원하는 채팅 애플리케이션이나 멀티 턴 대화를 구축할 때 특히 유용합니다. + +## 빠른 시작 + +```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. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 아이템 앞에 추가합니다 +2. **각 실행 후**: 실행 중 생성된 모든 새 아이템(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 자동으로 세션에 저장됩니다 +3. **컨텍스트 유지**: 동일한 세션으로 이어지는 이후 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다 + +이는 실행 간 대화 상태를 관리하고 `.to_input_list()` 를 수동으로 호출해야 하는 필요를 없앱니다. + +## 메모리 작업 + +### 기본 작업 + +세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다: + +```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") +``` + +### OpenAI Conversations API 메모리 + +[OpenAI Conversations API](https://platform.openai.com/docs/guides/conversational-agents/conversations-api)를 사용하여 +직접 데이터베이스를 관리하지 않고도 대화 상태를 지속합니다. 이미 대화 기록 저장을 위해 OpenAI 호스팅 인프라에 의존하고 있는 경우 유용합니다. + +```python +from agents import OpenAIConversationsSession + +session = OpenAIConversationsSession() + +# Optionally resume a previous conversation by passing a conversation ID +# session = OpenAIConversationsSession(conversation_id="conv_123") + +result = await Runner.run( + agent, + "Hello", + session=session, +) +``` + +### 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 +) +``` + +### SQLAlchemy 기반 세션 + +더 고급 사용 사례의 경우 SQLAlchemy 기반 세션 백엔드를 사용할 수 있습니다. 이를 통해 세션 저장소로 SQLAlchemy 가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 사용할 수 있습니다. + +**예시 1: 인메모리 SQLite 와 `from_url` 사용** + +개발 및 테스트에 적합한 가장 간단한 시작 방법입니다. + +```python +import asyncio +from agents import Agent, Runner +from agents.extensions.memory.sqlalchemy_session import SQLAlchemySession + +async def main(): + agent = Agent("Assistant") + session = SQLAlchemySession.from_url( + "user-123", + url="sqlite+aiosqlite:///:memory:", + create_tables=True, # Auto-create tables for the demo + ) + + result = await Runner.run(agent, "Hello", session=session) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**예시 2: 기존 SQLAlchemy 엔진 사용** + +프로덕션 애플리케이션에서는 이미 SQLAlchemy `AsyncEngine` 인스턴스를 보유하고 있을 가능성이 높습니다. 이를 세션에 직접 전달할 수 있습니다. + +```python +import asyncio +from agents import Agent, Runner +from agents.extensions.memory.sqlalchemy_session import SQLAlchemySession +from sqlalchemy.ext.asyncio import create_async_engine + +async def main(): + # In your application, you would use your existing engine + engine = create_async_engine("sqlite+aiosqlite:///conversations.db") + + agent = Agent("Assistant") + session = SQLAlchemySession( + "user-456", + engine=engine, + create_tables=True, # Auto-create tables for the demo + ) + + result = await Runner.run(agent, "Hello", session=session) + print(result.final_output) + + await engine.dispose() + +if __name__ == "__main__": + asyncio.run(main()) +``` + + +## 커스텀 메모리 구현 + +[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다: + +```python +from agents.memory.session import SessionABC +from agents.items import TResponseInputItem +from typing import List + +class MyCustomSession(SessionABC): + """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[TResponseInputItem]: + """Retrieve conversation history for this session.""" + # Your implementation here + pass + + async def add_items(self, items: List[TResponseInputItem]) -> None: + """Store new items for this session.""" + # Your implementation here + pass + + async def pop_item(self) -> TResponseInputItem | 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") +) +``` + +## 세션 관리 + +### 세션 ID 네이밍 + +대화를 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요: + +- User 기반: `"user_12345"` +- 스레드 기반: `"thread_abc123"` +- 컨텍스트 기반: `"support_ticket_456"` + +### 메모리 지속성 + +- 임시 대화에는 인메모리 SQLite (`SQLiteSession("session_id")`) 사용 +- 지속적 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- SQLAlchemy 가 지원하는 기존 데이터베이스를 사용하는 프로덕션 시스템에는 SQLAlchemy 기반 세션 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 +- 기록을 OpenAI Conversations API 에 저장하기를 원할 때는 OpenAI 호스티드 스토리지 (`OpenAIConversationsSession()`) 사용 +- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 맞춘 커스텀 세션 백엔드 구현 고려 + +### 세션 관리 + +```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 +) +``` + +## 전체 예제 + +세션 메모리가 동작하는 전체 예제는 다음과 같습니다: + +```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()) +``` + +## API 레퍼런스 + +자세한 API 문서는 다음을 참고하세요: + +- [`Session`][agents.memory.Session] - 프로토콜 인터페이스 +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 구현 +- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 구현 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 \ No newline at end of file diff --git a/docs/ko/streaming.md b/docs/ko/streaming.md new file mode 100644 index 000000000..34e9eb301 --- /dev/null +++ b/docs/ko/streaming.md @@ -0,0 +1,91 @@ +--- +search: + exclude: true +--- +# 스트리밍 + +스트리밍은 에이전트 실행이 진행되는 동안 업데이트를 구독할 수 있게 해줍니다. 이는 최종 사용자에게 진행 상황 업데이트와 부분 응답을 보여줄 때 유용합니다. + +스트리밍을 위해 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 호출하면 [`RunResultStreaming`][agents.result.RunResultStreaming]을 받습니다. `result.stream_events()`를 호출하면 아래에 설명된 [`StreamEvent`][agents.stream_events.StreamEvent] 객체의 비동기 스트림을 제공합니다. + +## 원문 응답 이벤트 + +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원문 이벤트입니다. 이는 OpenAI Responses API 형식이며, 각 이벤트에는 타입(예: `response.created`, `response.output_text.delta` 등)과 데이터가 있습니다. 이 이벤트는 생성 즉시 사용자에게 응답 메시지를 스트리밍하고 싶을 때 유용합니다. + +예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다. + +```python +import asyncio +from openai.types.responses import ResponseTextDeltaEvent +from agents import Agent, Runner + +async def main(): + agent = Agent( + name="Joker", + instructions="You are a helpful assistant.", + ) + + result = Runner.run_streamed(agent, input="Please tell me 5 jokes.") + async for event in result.stream_events(): + if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent): + print(event.data.delta, end="", flush=True) + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## 실행 항목 이벤트 및 에이전트 이벤트 + +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]s는 더 상위 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰 대신 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황을 전달할 수 있습니다. 유사하게, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과로) 업데이트를 제공합니다. + +예를 들어, 다음은 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. + +```python +import asyncio +import random +from agents import Agent, ItemHelpers, Runner, function_tool + +@function_tool +def how_many_jokes() -> int: + return random.randint(1, 10) + + +async def main(): + agent = Agent( + name="Joker", + instructions="First call the `how_many_jokes` tool, then tell that many jokes.", + tools=[how_many_jokes], + ) + + result = Runner.run_streamed( + agent, + input="Hello", + ) + print("=== Run starting ===") + + async for event in result.stream_events(): + # We'll ignore the raw responses event deltas + if event.type == "raw_response_event": + continue + # When the agent updates, print that + elif event.type == "agent_updated_stream_event": + print(f"Agent updated: {event.new_agent.name}") + continue + # When items are generated, print them + elif event.type == "run_item_stream_event": + if event.item.type == "tool_call_item": + print("-- Tool was called") + elif event.item.type == "tool_call_output_item": + print(f"-- Tool output: {event.item.output}") + elif event.item.type == "message_output_item": + print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}") + else: + pass # Ignore other event types + + print("=== Run complete ===") + + +if __name__ == "__main__": + asyncio.run(main()) +``` \ No newline at end of file diff --git a/docs/ko/tools.md b/docs/ko/tools.md new file mode 100644 index 000000000..620ca6e5a --- /dev/null +++ b/docs/ko/tools.md @@ -0,0 +1,415 @@ +--- +search: + exclude: true +--- +# 도구 + +도구는 에이전트가 동작을 수행하도록 합니다. 예를 들어 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지 가능합니다. Agents SDK 에는 세 가지 클래스의 도구가 있습니다: + +- 호스티드 툴: 이는 AI 모델과 함께 LLM 서버에서 실행됩니다. OpenAI 는 retrieval, 웹 검색 및 컴퓨터 사용을 호스티드 툴로 제공합니다. +- 함수 호출: 임의의 Python 함수를 도구로 사용할 수 있습니다. +- 도구로서의 에이전트: 에이전트를 도구로 사용할 수 있어, 핸드오프 없이도 에이전트가 다른 에이전트를 호출할 수 있습니다. + +## 호스티드 툴 + +OpenAI 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 사용 시 몇 가지 기본 제공 도구를 제공합니다: + +- [`WebSearchTool`][agents.tool.WebSearchTool] 은 에이전트가 웹을 검색하도록 합니다. +- [`FileSearchTool`][agents.tool.FileSearchTool] 은 OpenAI 벡터 스토어에서 정보를 검색할 수 있도록 합니다. +- [`ComputerTool`][agents.tool.ComputerTool] 은 컴퓨터 사용 작업을 자동화할 수 있도록 합니다. +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 은 LLM 이 샌드박스 환경에서 코드를 실행할 수 있게 합니다. +- [`HostedMCPTool`][agents.tool.HostedMCPTool] 은 원격 MCP 서버의 도구를 모델에 노출합니다. +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 은 프롬프트로부터 이미지를 생성합니다. +- [`LocalShellTool`][agents.tool.LocalShellTool] 은 로컬 머신에서 셸 명령을 실행합니다. + +```python +from agents import Agent, FileSearchTool, Runner, WebSearchTool + +agent = Agent( + name="Assistant", + tools=[ + WebSearchTool(), + FileSearchTool( + max_num_results=3, + vector_store_ids=["VECTOR_STORE_ID"], + ), + ], +) + +async def main(): + result = await Runner.run(agent, "Which coffee shop should I go to, taking into account my preferences and the weather today in SF?") + print(result.final_output) +``` + +## 함수 도구 + +임의의 Python 함수를 도구로 사용할 수 있습니다. Agents SDK 가 도구 설정을 자동으로 수행합니다: + +- 도구 이름은 Python 함수 이름이 됩니다(또는 이름을 직접 지정할 수 있음) +- 도구 설명은 함수의 docstring 에서 가져옵니다(또는 설명을 직접 지정할 수 있음) +- 함수 입력을 위한 스키마는 함수의 인자에서 자동으로 생성됩니다 +- 각 입력의 설명은 비활성화하지 않는 한 함수의 docstring 에서 가져옵니다 + +Python 의 `inspect` 모듈로 함수 시그니처를 추출하고, [`griffe`](https://mkdocstrings.github.io/griffe/) 로 docstring 을 파싱하며, 스키마 생성을 위해 `pydantic` 을 사용합니다. + +```python +import json + +from typing_extensions import TypedDict, Any + +from agents import Agent, FunctionTool, RunContextWrapper, function_tool + + +class Location(TypedDict): + lat: float + long: float + +@function_tool # (1)! +async def fetch_weather(location: Location) -> str: + # (2)! + """Fetch the weather for a given location. + + Args: + location: The location to fetch the weather for. + """ + # In real life, we'd fetch the weather from a weather API + return "sunny" + + +@function_tool(name_override="fetch_data") # (3)! +def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str: + """Read the contents of a file. + + Args: + path: The path to the file to read. + directory: The directory to read the file from. + """ + # In real life, we'd read the file from the file system + return "" + + +agent = Agent( + name="Assistant", + tools=[fetch_weather, read_file], # (4)! +) + +for tool in agent.tools: + if isinstance(tool, FunctionTool): + print(tool.name) + print(tool.description) + print(json.dumps(tool.params_json_schema, indent=2)) + print() + +``` + +1. 함수 인자로 임의의 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다. +2. Docstring 이 있으면 설명과 인자 설명을 캡처하는 데 사용됩니다 +3. 함수는 선택적으로 `context` 를 받을 수 있습니다(첫 번째 인자여야 함). 도구 이름, 설명, 사용할 docstring 스타일 등 재정의도 설정할 수 있습니다 +4. 데코레이터가 적용된 함수를 도구 목록에 전달할 수 있습니다 + +??? note "펼쳐서 출력 보기" + + ``` + fetch_weather + Fetch the weather for a given location. + { + "$defs": { + "Location": { + "properties": { + "lat": { + "title": "Lat", + "type": "number" + }, + "long": { + "title": "Long", + "type": "number" + } + }, + "required": [ + "lat", + "long" + ], + "title": "Location", + "type": "object" + } + }, + "properties": { + "location": { + "$ref": "#/$defs/Location", + "description": "The location to fetch the weather for." + } + }, + "required": [ + "location" + ], + "title": "fetch_weather_args", + "type": "object" + } + + fetch_data + Read the contents of a file. + { + "properties": { + "path": { + "description": "The path to the file to read.", + "title": "Path", + "type": "string" + }, + "directory": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "description": "The directory to read the file from.", + "title": "Directory" + } + }, + "required": [ + "path" + ], + "title": "fetch_data_args", + "type": "object" + } + ``` + +### 커스텀 함수 도구 + +때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 이 경우 [`FunctionTool`][agents.tool.FunctionTool] 을 직접 생성할 수 있습니다. 다음을 제공해야 합니다: + +- `name` +- `description` +- `params_json_schema` (인자에 대한 JSON 스키마) +- `on_invoke_tool` ([`ToolContext`][agents.tool_context.ToolContext] 와 인자 JSON 문자열을 받아서, 도구 출력 문자열을 반환해야 하는 async 함수) + +```python +from typing import Any + +from pydantic import BaseModel + +from agents import RunContextWrapper, FunctionTool + + + +def do_some_work(data: str) -> str: + return "done" + + +class FunctionArgs(BaseModel): + username: str + age: int + + +async def run_function(ctx: RunContextWrapper[Any], args: str) -> str: + parsed = FunctionArgs.model_validate_json(args) + return do_some_work(data=f"{parsed.username} is {parsed.age} years old") + + +tool = FunctionTool( + name="process_user", + description="Processes extracted user data", + params_json_schema=FunctionArgs.model_json_schema(), + on_invoke_tool=run_function, +) +``` + +### 자동 인자 및 docstring 파싱 + +앞서 언급했듯이, 도구를 위한 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인자 설명을 얻기 위해 docstring 을 파싱합니다. 참고 사항: + +1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 어노테이션을 사용해 인자의 타입을 파악하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 구성합니다. Python 기본형, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다. +2. docstring 파싱에는 `griffe` 를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy` 입니다. docstring 형식을 자동으로 감지하려 시도하지만, 이는 최선의 시도이며 `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info` 를 `False` 로 설정하여 docstring 파싱을 비활성화할 수도 있습니다. + +스키마 추출에 대한 코드는 [`agents.function_schema`][] 에 있습니다. + +## 도구로서의 에이전트 + +일부 워크플로에서는 제어권을 넘기지 않고, 중앙 에이전트가 특화된 에이전트 네트워크를 오케스트레이션하기를 원할 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다. + +```python +from agents import Agent, Runner +import asyncio + +spanish_agent = Agent( + name="Spanish agent", + instructions="You translate the user's message to Spanish", +) + +french_agent = Agent( + name="French agent", + instructions="You translate the user's message to French", +) + +orchestrator_agent = Agent( + name="orchestrator_agent", + instructions=( + "You are a translation agent. You use the tools given to you to translate." + "If asked for multiple translations, you call the relevant tools." + ), + tools=[ + spanish_agent.as_tool( + tool_name="translate_to_spanish", + tool_description="Translate the user's message to Spanish", + ), + french_agent.as_tool( + tool_name="translate_to_french", + tool_description="Translate the user's message to French", + ), + ], +) + +async def main(): + result = await Runner.run(orchestrator_agent, input="Say 'Hello, how are you?' in Spanish.") + print(result.final_output) +``` + +### 도구-에이전트 커스터마이징 + +`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""" + + agent = Agent(name="My agent", instructions="...") + + result = await Runner.run( + agent, + input="...", + max_turns=5, + run_config=... + ) + + return str(result.final_output) +``` + +### 커스텀 출력 추출 + +일부 경우, 중앙 에이전트에 반환하기 전에 도구-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우에 유용합니다: + +- 하위 에이전트의 채팅 기록에서 특정 정보(예: JSON 페이로드)를 추출 +- 에이전트의 최종 답변을 변환 또는 재포맷(예: Markdown 을 일반 텍스트나 CSV 로 변환) +- 에이전트의 응답이 누락되었거나 잘못된 경우 출력을 검증하거나 폴백 값을 제공 + +`as_tool` 메서드에 `custom_output_extractor` 인자를 제공하여 이를 구현할 수 있습니다: + +```python +async def extract_json_payload(run_result: RunResult) -> str: + # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call. + for item in reversed(run_result.new_items): + if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"): + return item.output.strip() + # Fallback to an empty JSON object if nothing was found + return "{}" + + +json_tool = data_agent.as_tool( + tool_name="get_data_json", + tool_description="Run the data agent and return only its JSON payload", + custom_output_extractor=extract_json_payload, +) +``` + +### 조건부 도구 활성화 + +런타임에 `is_enabled` 매개변수를 사용해 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM 에 제공되는 도구를 동적으로 필터링할 수 있습니다. + +```python +import asyncio +from agents import Agent, AgentBase, Runner, RunContextWrapper +from pydantic import BaseModel + +class LanguageContext(BaseModel): + language_preference: str = "french_spanish" + +def french_enabled(ctx: RunContextWrapper[LanguageContext], agent: AgentBase) -> bool: + """Enable French for French+Spanish preference.""" + return ctx.context.language_preference == "french_spanish" + +# Create specialized agents +spanish_agent = Agent( + name="spanish_agent", + instructions="You respond in Spanish. Always reply to the user's question in Spanish.", +) + +french_agent = Agent( + name="french_agent", + instructions="You respond in French. Always reply to the user's question in French.", +) + +# Create orchestrator with conditional tools +orchestrator = Agent( + name="orchestrator", + instructions=( + "You are a multilingual assistant. You use the tools given to you to respond to users. " + "You must call ALL available tools to provide responses in different languages. " + "You never respond in languages yourself, you always use the provided tools." + ), + tools=[ + spanish_agent.as_tool( + tool_name="respond_spanish", + tool_description="Respond to the user's question in Spanish", + is_enabled=True, # Always enabled + ), + french_agent.as_tool( + tool_name="respond_french", + tool_description="Respond to the user's question in French", + is_enabled=french_enabled, + ), + ], +) + +async def main(): + context = RunContextWrapper(LanguageContext(language_preference="french_spanish")) + result = await Runner.run(orchestrator, "How are you?", context=context.context) + print(result.final_output) + +asyncio.run(main()) +``` + +`is_enabled` 매개변수는 다음을 허용합니다: +- **불리언 값**: `True`(항상 활성) 또는 `False`(항상 비활성) +- **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 +- **비동기 함수**: 복잡한 조건부 로직을 위한 async 함수 + +비활성화된 도구는 런타임에 LLM 에 완전히 숨겨집니다. 다음에 유용합니다: +- 사용자 권한 기반 기능 게이팅 +- 환경별 도구 가용성 제어(dev vs prod) +- 서로 다른 도구 구성을 A/B 테스트 +- 런타임 상태 기반 동적 도구 필터링 + +## 함수 도구의 오류 처리 + +`@function_tool` 로 함수 도구를 만들 때 `failure_error_function` 을 전달할 수 있습니다. 이는 도구 호출이 크래시한 경우 LLM 에 에러 응답을 제공하는 함수입니다. + +- 기본적으로(즉, 아무것도 전달하지 않으면) 오류 발생을 LLM 에 알리는 `default_tool_error_function` 이 실행됩니다. +- 자체 에러 함수를 전달하면 해당 함수가 대신 실행되어 LLM 으로 응답이 전송됩니다. +- 명시적으로 `None` 을 전달하면, 도구 호출 오류가 다시 발생하여 직접 처리할 수 있습니다. 모델이 잘못된 JSON 을 생성한 경우 `ModelBehaviorError`, 코드가 크래시한 경우 `UserError` 등이 될 수 있습니다. + +```python +from agents import function_tool, RunContextWrapper +from typing import Any + +def my_custom_error_function(context: RunContextWrapper[Any], error: Exception) -> str: + """A custom function to provide a user-friendly error message.""" + print(f"A tool call failed with the following error: {error}") + return "An internal server error occurred. Please try again later." + +@function_tool(failure_error_function=my_custom_error_function) +def get_user_profile(user_id: str) -> str: + """Fetches a user profile from a mock API. + This function demonstrates a 'flaky' or failing API call. + """ + if user_id == "user_123": + return "User profile for user_123 successfully retrieved." + else: + raise ValueError(f"Could not retrieve profile for user_id: {user_id}. API returned an error.") + +``` + +`FunctionTool` 객체를 수동으로 생성하는 경우, 오류는 `on_invoke_tool` 함수 내부에서 처리해야 합니다. \ No newline at end of file diff --git a/docs/ko/tracing.md b/docs/ko/tracing.md new file mode 100644 index 000000000..7633efe9d --- /dev/null +++ b/docs/ko/tracing.md @@ -0,0 +1,151 @@ +--- +search: + exclude: true +--- +# 트레이싱 + +Agents SDK에는 내장 트레이싱이 포함되어 있어 에이전트 실행 중 발생하는 이벤트를 포괄적으로 기록합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 발생하는 사용자 지정 이벤트까지 수집합니다. [Traces 대시보드](https://platform.openai.com/traces)를 사용하여 개발 중과 프로덕션 환경에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다. + +!!!note + + 트레이싱은 기본적으로 활성화되어 있습니다. 트레이싱을 비활성화하는 방법은 두 가지입니다: + + 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 설정으로 전역 트레이싱 비활성화 + 2. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][] 를 `True` 로 설정하여 트레이싱 비활성화 + +***OpenAI의 API를 사용하는 Zero Data Retention (ZDR) 정책 하의 조직은 트레이싱을 사용할 수 없습니다.*** + +## 트레이스와 스팬 + +- **트레이스(Traces)** 는 "워크플로"의 단일 엔드투엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스는 다음 속성을 가집니다: + - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service" + - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>` 이어야 합니다 + - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 + - `disabled`: True인 경우 트레이스가 기록되지 않습니다 + - `metadata`: 트레이스에 대한 선택적 메타데이터 +- **스팬(Spans)** 은 시작 및 종료 시간이 있는 작업을 나타냅니다. 스팬은 다음을 가집니다: + - `started_at` 및 `ended_at` 타임스탬프 + - `trace_id`, 이 스팬이 속한 트레이스를 나타냄 + - `parent_id`, 이 스팬의 부모 스팬을 가리킴(있는 경우) + - `span_data`, 스팬에 대한 정보입니다. 예를 들어, `AgentSpanData` 는 에이전트에 대한 정보를, `GenerationSpanData` 는 LLM 생성에 대한 정보를 포함합니다 + +## 기본 트레이싱 + +기본적으로 SDK는 다음을 트레이싱합니다: + +- 전체 `Runner.{run, run_sync, run_streamed}()` 가 `trace()` 로 래핑됨 +- 에이전트가 실행될 때마다 `agent_span()` 으로 래핑됨 +- LLM 생성은 `generation_span()` 으로 래핑됨 +- 함수 도구 호출은 각각 `function_span()` 으로 래핑됨 +- 가드레일은 `guardrail_span()` 으로 래핑됨 +- 핸드오프는 `handoff_span()` 으로 래핑됨 +- 오디오 입력(음성 인식)은 `transcription_span()` 으로 래핑됨 +- 오디오 출력(텍스트 음성 변환)은 `speech_span()` 으로 래핑됨 +- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식 관계로 배치될 수 있음 + +기본적으로 트레이스 이름은 "Agent workflow" 입니다. `trace` 를 사용하면 이 이름을 설정할 수 있으며, 또는 [`RunConfig`][agents.run.RunConfig] 로 이름과 기타 속성을 구성할 수 있습니다. + +추가로, [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 목적지로 전송할 수 있습니다(대체 또는 보조 목적지). + +## 상위 수준 트레이스 + +때때로 `run()` 을 여러 번 호출하더라도 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 전체 코드를 `trace()` 로 감싸면 가능합니다. + +```python +from agents import Agent, Runner, trace + +async def main(): + agent = Agent(name="Joke generator", instructions="Tell funny jokes.") + + with trace("Joke workflow"): # (1)! + first_result = await Runner.run(agent, "Tell me a joke") + second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}") + print(f"Joke: {first_result.final_output}") + print(f"Rating: {second_result.final_output}") +``` + +1. `Runner.run` 에 대한 두 번의 호출이 `with trace()` 로 감싸져 있기 때문에, 각각의 실행이 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다. + +## 트레이스 생성 + +[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요합니다. 방법은 두 가지입니다: + +1. **권장**: 트레이스를 컨텍스트 매니저로 사용합니다. 예: `with trace(...) as my_trace`. 적절한 시점에 자동으로 트레이스를 시작하고 종료합니다 +2. 수동으로 [`trace.start()`][agents.tracing.Trace.start] 와 [`trace.finish()`][agents.tracing.Trace.finish] 를 호출할 수도 있습니다 + +현재 트레이스는 Python의 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 를 통해 추적됩니다. 즉, 자동으로 동시성에 대응합니다. 트레이스를 수동으로 시작/종료하는 경우, 현재 트레이스를 업데이트하기 위해 `start()`/`finish()` 에 `mark_as_current` 와 `reset_current` 를 전달해야 합니다. + +## 스팬 생성 + +여러 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 지정 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수가 제공됩니다. + +스팬은 자동으로 현재 트레이스의 일부가 되며, 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] 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. + +유사하게, 오디오 스팬은 기본적으로 입력 및 출력 오디오에 대해 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 백엔드에 스팬과 트레이스를 내보냅니다 + +기본 설정을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 전송하거나, 익스포터 동작을 수정하려면 두 가지 옵션이 있습니다: + +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 를 사용하면 준비된 트레이스와 스팬을 수신하는 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것과 함께 자체 처리를 수행할 수 있습니다 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 를 사용하면 기본 프로세서를 사용자 지정 트레이스 프로세서로 **대체** 할 수 있습니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는 `TracingProcessor` 를 포함해야 합니다 + +## 비 OpenAI 모델 트레이싱 + +OpenAI의 API 키를 비 OpenAI 모델과 함께 사용하여 트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. + +```python +import os +from agents import set_tracing_export_api_key, Agent, Runner +from agents.extensions.models.litellm_model import LitellmModel + +tracing_api_key = os.environ["OPENAI_API_KEY"] +set_tracing_export_api_key(tracing_api_key) + +model = LitellmModel( + model="your-model-name", + api_key="your-api-key", +) + +agent = Agent( + name="Assistant", + model=model, +) +``` + +## 참고 +- OpenAI Traces 대시보드에서 무료 트레이스를 확인하세요 + +## 외부 트레이싱 프로세서 목록 + +- [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) +- [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) +- [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) +- [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) +- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file diff --git a/docs/ko/usage.md b/docs/ko/usage.md new file mode 100644 index 000000000..987db279b --- /dev/null +++ b/docs/ko/usage.md @@ -0,0 +1,86 @@ +--- +search: + exclude: true +--- +# 사용량 + +Agents SDK 는 모든 실행에 대해 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 접근하여 비용 모니터링, 한도 적용, 분석 기록에 사용할 수 있습니다. + +## 추적 항목 + +- **requests**: 수행된 LLM API 호출 수 +- **input_tokens**: 전송된 입력 토큰 총량 +- **output_tokens**: 수신된 출력 토큰 총량 +- **total_tokens**: 입력 + 출력 +- **details**: + - `input_tokens_details.cached_tokens` + - `output_tokens_details.reasoning_tokens` + +## 실행에서 사용량 액세스 + +`Runner.run(...)` 이후, `result.context_wrapper.usage` 를 통해 사용량에 접근합니다. + +```python +result = await Runner.run(agent, "What's the weather in Tokyo?") +usage = result.context_wrapper.usage + +print("Requests:", usage.requests) +print("Input tokens:", usage.input_tokens) +print("Output tokens:", usage.output_tokens) +print("Total tokens:", usage.total_tokens) +``` + +실행 중의 모든 모델 호출 전반(도구 호출 및 핸드오프 포함)에 걸쳐 사용량이 집계됩니다. + +### LiteLLM 모델에서 사용량 활성화 + +LiteLLM 공급자는 기본적으로 사용량 메트릭을 보고하지 않습니다. [`LitellmModel`](models/litellm.md) 을 사용할 때, 에이전트에 `ModelSettings(include_usage=True)` 를 전달하면 LiteLLM 응답이 `result.context_wrapper.usage` 를 채웁니다. + +```python +from agents import Agent, ModelSettings, Runner +from agents.extensions.models.litellm_model import LitellmModel + +agent = Agent( + name="Assistant", + model=LitellmModel(model="your/model", api_key="..."), + model_settings=ModelSettings(include_usage=True), +) + +result = await Runner.run(agent, "What's the weather in Tokyo?") +print(result.context_wrapper.usage.total_tokens) +``` + +## 세션에서 사용량 액세스 + +`Session`(예: `SQLiteSession`) 을 사용할 때, `Runner.run(...)` 에 대한 각 호출은 해당 실행에 대한 사용량을 반환합니다. 세션은 컨텍스트를 위한 대화 이력을 유지하지만, 각 실행의 사용량은 서로 독립적입니다. + +```python +session = SQLiteSession("my_conversation") + +first = await Runner.run(agent, "Hi!", session=session) +print(first.context_wrapper.usage.total_tokens) # Usage for first run + +second = await Runner.run(agent, "Can you elaborate?", session=session) +print(second.context_wrapper.usage.total_tokens) # Usage for second run +``` + +세션은 실행 간 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출이 반환하는 사용량 메트릭은 해당 실행에만 해당합니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 제공될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다. + +## 훅에서의 사용량 활용 + +`RunHooks` 를 사용하는 경우, 각 훅에 전달되는 `context` 객체에는 `usage` 가 포함됩니다. 이를 통해 수명 주기의 핵심 시점에 사용량을 로그할 수 있습니다. + +```python +class MyHooks(RunHooks): + async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: + u = context.usage + print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") +``` + +## API Reference + +자세한 API 문서는 다음을 참조하세요: + +- [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 액세스 +- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 수명 주기에 훅 연결 \ No newline at end of file diff --git a/docs/ko/visualization.md b/docs/ko/visualization.md new file mode 100644 index 000000000..84d385730 --- /dev/null +++ b/docs/ko/visualization.md @@ -0,0 +1,108 @@ +--- +search: + exclude: true +--- +# 에이전트 시각화 + +에이전트 시각화는 **Graphviz** 를 사용해 에이전트와 그 관계의 구조화된 그래픽 표현을 생성할 수 있게 합니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다. + +## 설치 + +선택적 `viz` 종속성 그룹을 설치하세요: + +```bash +pip install "openai-agents[viz]" +``` + +## 그래프 생성 + +`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 유향 그래프를 생성합니다: + +- **에이전트**는 노란색 상자로 표시됩니다 +- **MCP 서버**는 회색 상자로 표시됩니다 +- **도구**는 녹색 타원으로 표시됩니다 +- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향 에지로 표시됩니다 + +### 사용 예시 + +```python +import os + +from agents import Agent, function_tool +from agents.mcp.server import MCPServerStdio +from agents.extensions.visualization import draw_graph + +@function_tool +def get_weather(city: str) -> str: + return f"The weather in {city} is sunny." + +spanish_agent = Agent( + name="Spanish agent", + instructions="You only speak Spanish.", +) + +english_agent = Agent( + name="English agent", + instructions="You only speak English", +) + +current_dir = os.path.dirname(os.path.abspath(__file__)) +samples_dir = os.path.join(current_dir, "sample_files") +mcp_server = MCPServerStdio( + name="Filesystem Server, via npx", + params={ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir], + }, +) + +triage_agent = Agent( + name="Triage agent", + instructions="Handoff to the appropriate agent based on the language of the request.", + handoffs=[spanish_agent, english_agent], + tools=[get_weather], + mcp_servers=[mcp_server], +) + +draw_graph(triage_agent) +``` + +![Agent Graph](../assets/images/graph.png) + +이는 **triage 에이전트**의 구조와 하위 에이전트 및 도구에 대한 연결을 시각적으로 나타내는 그래프를 생성합니다. + + +## 시각화 이해 + +생성된 그래프에는 다음이 포함됩니다: + +- 진입점을 나타내는 **시작 노드** (`__start__`) +- 노란색 채우기의 **사각형**으로 표시된 에이전트 +- 녹색 채우기의 **타원**으로 표시된 도구 +- 회색 채우기의 **사각형**으로 표시된 MCP 서버 +- 상호작용을 나타내는 유향 에지: + - 에이전트 간 핸드오프는 **실선 화살표** + - 도구 호출은 **점선 화살표** + - MCP 서버 호출은 **파선 화살표** +- 실행 종료 지점을 나타내는 **종료 노드** (`__end__`) + +**참고:** MCP 서버 렌더링은 최근 버전의 +`agents` 패키지에서 지원됩니다 ( **v0.2.8** 검증). 시각화에 MCP 상자가 보이지 않으면 최신 릴리스로 업그레이드하세요. + +## 그래프 사용자 지정 + +### 그래프 표시 +기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 그래프를 별도 창으로 표시하려면 다음을 작성하세요: + +```python +draw_graph(triage_agent).view() +``` + +### 그래프 저장 +기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일명을 지정하세요: + +```python +draw_graph(triage_agent, filename="agent_graph") +``` + +그러면 작업 디렉터리에 `agent_graph.png` 가 생성됩니다. \ No newline at end of file diff --git a/docs/ko/voice/pipeline.md b/docs/ko/voice/pipeline.md new file mode 100644 index 000000000..ea117148a --- /dev/null +++ b/docs/ko/voice/pipeline.md @@ -0,0 +1,79 @@ +--- +search: + exclude: true +--- +# 파이프라인과 워크플로 + +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 기반 워크플로를 음성 앱으로 쉽게 전환할 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오의 음성 인식, 오디오 종료 감지, 적절한 시점에 워크플로 호출, 워크플로 출력의 오디오 변환까지 처리합니다. + +```mermaid +graph LR + %% Input + A["🎤 Audio Input"] + + %% Voice Pipeline + subgraph Voice_Pipeline [Voice Pipeline] + direction TB + B["Transcribe (speech-to-text)"] + C["Your Code"]:::highlight + D["Text-to-speech"] + B --> C --> D + end + + %% Output + E["🎧 Audio Output"] + + %% Flow + A --> Voice_Pipeline + Voice_Pipeline --> E + + %% Custom styling + classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700; + +``` + +## 파이프라인 구성 + +파이프라인을 생성할 때 다음을 설정할 수 있습니다: + +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] 메서드로 실행할 수 있으며, 두 가지 형태의 오디오 입력을 전달할 수 있습니다: + +1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사가 있을 때 이를 바탕으로 결과만 생성하고 싶을 때 사용합니다. 화자가 말을 마쳤는지 감지할 필요가 없는 상황에 유용합니다. 예를 들어, 사전 녹음된 오디오가 있거나, 사용자가 말을 마치는 시점이 명확한 푸시투토크 앱에서 유용합니다. +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 말을 마치는 시점을 감지해야 할 수 있는 경우에 사용합니다. 감지된 대로 오디오 청크를 푸시할 수 있으며, 음성 파이프라인은 "활동 감지(activity detection)"라 불리는 과정을 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다. + +## 결과 + +음성 파이프라인 실행의 결과는 [`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] + +```python + +result = await pipeline.run(input) + +async for event in result.stream(): + if event.type == "voice_stream_event_audio": + # play audio + elif event.type == "voice_stream_event_lifecycle": + # lifecycle + elif event.type == "voice_stream_event_error" + # error + ... +``` + +## 모범 사례 + +### 인터럽션(중단 처리) + +Agents SDK 는 현재 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]에 대한 내장 인터럽션(중단 처리) 기능을 지원하지 않습니다. 대신, 감지된 각 턴마다 워크플로의 별도 실행이 트리거됩니다. 애플리케이션에서 인터럽션을 처리하려면 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 이벤트를 구독하면 됩니다. `turn_started`는 새 턴이 전사되어 처리가 시작되었음을 나타냅니다. `turn_ended`는 해당 턴의 모든 오디오가 전송된 후에 트리거됩니다. 모델이 턴을 시작할 때 화자의 마이크를 음소거하고, 해당 턴의 관련 오디오를 모두 전송한 후 음소거를 해제하는 방식으로 이 이벤트들을 활용할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/voice/quickstart.md b/docs/ko/voice/quickstart.md new file mode 100644 index 000000000..792ebe577 --- /dev/null +++ b/docs/ko/voice/quickstart.md @@ -0,0 +1,198 @@ +--- +search: + exclude: true +--- +# 빠른 시작 + +## 사전 준비 + +Agents SDK의 기본 [빠른 시작 안내](../quickstart.md)를 따라 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택적 음성 관련 종속성을 설치합니다: + +```bash +pip install 'openai-agents[voice]' +``` + +## 개념 + +핵심 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 3단계 프로세스입니다: + +1. 음성을 텍스트로 변환하기 위해 음성 인식 모델을 실행 +2. 결과를 생성하기 위해 보통 에이전트 기반 워크플로인 코드를 실행 +3. 결과 텍스트를 다시 음성으로 변환하기 위해 음성 합성 모델을 실행 + +```mermaid +graph LR + %% Input + A["🎤 Audio Input"] + + %% Voice Pipeline + subgraph Voice_Pipeline [Voice Pipeline] + direction TB + B["Transcribe (speech-to-text)"] + C["Your Code"]:::highlight + D["Text-to-speech"] + B --> C --> D + end + + %% Output + E["🎧 Audio Output"] + + %% Flow + A --> Voice_Pipeline + Voice_Pipeline --> E + + %% Custom styling + classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700; + +``` + +## 에이전트 + +먼저 에이전트를 몇 개 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙할 것입니다. 에이전트 두 개와 핸드오프, 그리고 도구를 사용합니다. + +```python +import asyncio +import random + +from agents import ( + Agent, + function_tool, +) +from agents.extensions.handoff_prompt import prompt_with_handoff_instructions + + + +@function_tool +def get_weather(city: str) -> str: + """Get the weather for a given city.""" + print(f"[debug] get_weather called with city: {city}") + choices = ["sunny", "cloudy", "rainy", "snowy"] + return f"The weather in {city} is {random.choice(choices)}." + + +spanish_agent = Agent( + name="Spanish", + handoff_description="A spanish speaking agent.", + instructions=prompt_with_handoff_instructions( + "You're speaking to a human, so be polite and concise. Speak in Spanish.", + ), + model="gpt-4.1", +) + +agent = Agent( + name="Assistant", + instructions=prompt_with_handoff_instructions( + "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", + ), + model="gpt-4.1", + handoffs=[spanish_agent], + tools=[get_weather], +) +``` + +## 음성 파이프라인 + +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 워크플로로 사용해 간단한 음성 파이프라인을 설정하겠습니다. + +```python +from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline +pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent)) +``` + +## 파이프라인 실행 + +```python +import numpy as np +import sounddevice as sd +from agents.voice import AudioInput + +# For simplicity, we'll just create 3 seconds of silence +# In reality, you'd get microphone data +buffer = np.zeros(24000 * 3, dtype=np.int16) +audio_input = AudioInput(buffer=buffer) + +result = await pipeline.run(audio_input) + +# Create an audio player using `sounddevice` +player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16) +player.start() + +# Play the audio stream as it comes in +async for event in result.stream(): + if event.type == "voice_stream_event_audio": + player.write(event.data) + +``` + +## 모두 합치기 + +```python +import asyncio +import random + +import numpy as np +import sounddevice as sd + +from agents import ( + Agent, + function_tool, + set_tracing_disabled, +) +from agents.voice import ( + AudioInput, + SingleAgentVoiceWorkflow, + VoicePipeline, +) +from agents.extensions.handoff_prompt import prompt_with_handoff_instructions + + +@function_tool +def get_weather(city: str) -> str: + """Get the weather for a given city.""" + print(f"[debug] get_weather called with city: {city}") + choices = ["sunny", "cloudy", "rainy", "snowy"] + return f"The weather in {city} is {random.choice(choices)}." + + +spanish_agent = Agent( + name="Spanish", + handoff_description="A spanish speaking agent.", + instructions=prompt_with_handoff_instructions( + "You're speaking to a human, so be polite and concise. Speak in Spanish.", + ), + model="gpt-4.1", +) + +agent = Agent( + name="Assistant", + instructions=prompt_with_handoff_instructions( + "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.", + ), + model="gpt-4.1", + handoffs=[spanish_agent], + tools=[get_weather], +) + + +async def main(): + pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent)) + buffer = np.zeros(24000 * 3, dtype=np.int16) + audio_input = AudioInput(buffer=buffer) + + result = await pipeline.run(audio_input) + + # Create an audio player using `sounddevice` + player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16) + player.start() + + # Play the audio stream as it comes in + async for event in result.stream(): + if event.type == "voice_stream_event_audio": + player.write(event.data) + + +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 diff --git a/docs/ko/voice/tracing.md b/docs/ko/voice/tracing.md new file mode 100644 index 000000000..77ed18f42 --- /dev/null +++ b/docs/ko/voice/tracing.md @@ -0,0 +1,18 @@ +--- +search: + exclude: true +--- +# 트레이싱 + +[에이전트 트레이싱](../tracing.md)과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다. + +기본적인 트레이싱 정보는 위 문서를 참고하시고, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다. + +트레이싱과 관련된 주요 필드는 다음과 같습니다: + +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱 비활성화 여부를 제어합니다. 기본값은 트레이싱 활성화입니다 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사와 같이 민감할 수 있는 데이터를 트레이스에 포함할지 여부를 제어합니다. 이는 음성 파이프라인에 한정되며, Workflow 내부에서 발생하는 사항에는 적용되지 않습니다 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 트레이스에 오디오 데이터를 포함할지 여부를 제어합니다 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로 이름입니다 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있도록 하는 트레이스의 `group_id` 입니다 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이스에 포함할 추가 메타데이터입니다 \ No newline at end of file