diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 91413f46c..95b8a3013 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは instructions とツールで構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる構成要素です。エージェントは instructions と tools で構成された大規模言語モデル ( LLM ) です。 ## 基本設定 -エージェントでよく設定するプロパティは次のとおりです。 +エージェントで最も一般的に設定するプロパティは次のとおりです。 -- `name`: エージェントを識別する必須の文字列。 -- `instructions`: developer message または 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` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを提供できます。 +エージェントはその `context` 型に対してジェネリックです。Context は依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェントの実行に必要な依存関係や状態をまとめて保持します。任意の Python オブジェクトを context として渡せます。 ```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](handoffs.md) ドキュメントを参照してください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェントの作成時に instructions を指定できますが、関数経由で動的に instructions を提供することも可能です。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方を受け付けます。 +多くの場合、エージェントを作成するときに instructions を指定できますが、関数を介して動的な instructions を提供することもできます。関数はエージェントと context を受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が使用可能です。 ```python def dynamic_instructions( @@ -151,13 +151,13 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント（フック） +## ライフサイクルイベント (hooks) -エージェントのライフサイクルを観測したい場合があります。例えば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりする場合です。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスを継承し、関心のあるメソッドをオーバーライドしてください。 +場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベントが発生したときにデータを事前取得したりできます。`hooks` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行してユーザー入力のチェック/検証を行い、生成後のエージェント出力に対してもチェックを行えます。例えば、ユーザー入力やエージェント出力の関連性をスクリーニングできます。詳しくは[ガードレール](guardrails.md)のドキュメントをご覧ください。 +ガードレールにより、エージェントの実行と並行して ユーザー 入力に対するチェック/バリデーションを行い、エージェントの出力が生成された後にもチェックできます。たとえば、ユーザー の入力やエージェントの出力を関連性でスクリーニングできます。詳細は [guardrails](guardrails.md) ドキュメントを参照してください。 ## エージェントのクローン/コピー @@ -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`）を設定: LLM にその特定のツールを使用するよう要求します。 +1. `auto`: ツールを使用するかどうかを LLM に任せます。 +2. `required`: LLM にツールの使用を必須にします (ただし、どのツールを使うかは賢く判断できます)。 +3. `none`: LLM にツールを使用しないことを必須にします。 +4. 特定の文字列 (例: `my_tool`) を設定: LLM にその特定のツールの使用を必須にします。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -201,12 +201,12 @@ agent = Agent( ) ``` -## ツール使用の動作 +## ツール使用の挙動 -`Agent` の設定にある `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 +`Agent` 設定の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 -- `"run_llm_again"`: 既定。ツールを実行し、その結果を LLM が処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力を最終応答として使用し、追加の LLM 処理は行いません。 +- `"run_llm_again"`: デフォルト。ツールを実行し、その結果を 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` により LLM がさらに別のツール呼び出しを生成し続けることが原因です。 \ No newline at end of file diff --git a/docs/ja/config.md b/docs/ja/config.md index 4a3ac06c7..a78f56737 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -6,7 +6,7 @@ search: ## API キーとクライアント -デフォルトでは、SDK はインポート直後から LLM リクエストと トレーシング 用に `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数でキーを設定できます。 +既定では、SDK はインポートされるとすぐに、LLM リクエストと トレーシング 用の `OPENAI_API_KEY` 環境変数を探します。アプリ起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数または上記のデフォルトキーから API キーを使用して `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 +また、使用する OpenAI クライアントを設定することもできます。既定では、SDK は環境変数または上記で設定した既定キーから API キーを使用して `AsyncOpenAI` インスタンスを作成します。これを変更するには、[set_default_openai_client()][agents.set_default_openai_client] 関数を使用します。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これを上書きして 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 にはハンドラー未設定の Python ロガーが 2 つあります。デフォルトでは、警告とエラーは `stdout` に出力され、それ以外のログは抑制されます。 +SDK にはハンドラーが設定されていない Python ロガーが 2 つあります。既定では、警告とエラーは `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 logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging ガイド](https://docs.python.org/3/howto/logging.html)をご覧ください。 ```python import logging @@ -81,17 +81,17 @@ logger.setLevel(logging.WARNING) logger.addHandler(logging.StreamHandler()) ``` -### ログ内の機微なデータ +### ログ内の機微情報 -一部のログには機微なデータ（例: ユーザー データ）が含まれる場合があります。これらのデータの記録を無効化したい場合は、次の環境変数を設定してください。 +一部のログには機微情報（例: ユーザー データ）が含まれる場合があります。これらのデータがログに出力されないようにするには、次の環境変数を設定してください。 -LLM の入力と出力のロギングを無効化するには: +LLM の入力と出力のログ出力を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -ツールの入力と出力のロギングを無効化するには: +ツールの入力と出力のログ出力を無効化するには: ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/ja/context.md b/docs/ja/context.md index 628ec9fb7..5dff9e30e 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語は多義的です。関心を持つべきコンテキストには主に 2 つのクラスがあります。 +コンテキストという用語は多義的です。気にすべきコンテキストには主に 2 つのクラスがあります。 -1. コードからローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になる可能性があるデータや依存関係です。 -2. LLM に利用できるコンテキスト: 応答生成時に LLM が参照するデータです。 +1. コードからローカルに利用できるコンテキスト: これはツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。 +2. LLM に利用できるコンテキスト: これは応答を生成する際に LLM が参照できるデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作は次のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスとその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的なパターンとして dataclass や Pydantic オブジェクトを使います。 -2. そのオブジェクトを各種の run メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 -3. すべてのツール呼び出しやライフサイクルフックなどに、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 +2. そのオブジェクトを各種の実行メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 +3. すべてのツール呼び出しやライフサイクルフックなどにはラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はあなたのコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -最も **重要** な点: 特定のエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクル等は、同じ型のコンテキストを使用しなければなりません。 + **最も重要** な点は、特定のエージェント実行に関わるあらゆるエージェント、ツール関数、ライフサイクルなどが、同じコンテキストの _型_ を使用しなければならないことです。 コンテキストは次のような用途に使えます。 -- 実行に関するコンテキストデータ（例: ユーザー名/UID や ユーザー に関する他の情報） -- 依存関係（例: ロガーオブジェクト、データ取得器など） +- 実行用のコンテキストデータ（例: ユーザー名/uid など、ユーザーに関する情報） +- 依存関係（例: ロガーオブジェクト、データ取得ロジック など） - ヘルパー関数 !!! danger "注意" - コンテキストオブジェクトは LLM には送信されません。読み取りや書き込み、メソッド呼び出しができる純粋なローカルオブジェクトです。 + コンテキストオブジェクトは LLM に **送信されません**。あくまでローカルのオブジェクトであり、読み取り・書き込み・メソッド呼び出しが可能なものです。 ```python import asyncio @@ -66,9 +66,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることが分かります。ツール実装はコンテキストから読み取ります。 -3. エージェントに総称型 `UserInfo` を付け、型チェッカーがエラーを検出できるようにします（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることが分かります。ツールの実装はコンテキストから読み取ります。 +3. エージェントにジェネリクスとして `UserInfo` を指定し、型チェッカーがエラーを検出できるようにします（例えば、別のコンテキスト型を受け取るツールを渡そうとした場合など）。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 @@ -76,8 +76,8 @@ if __name__ == "__main__": ### 上級: `ToolContext` -場合によっては、実行中のツールに関する追加メタデータ（名前、呼び出し ID、raw 引数文字列など）にアクセスしたいことがあります。 -その場合は、`RunContextWrapper` を拡張した [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。 +場合によっては、実行中のツールに関する追加メタデータ（名前、呼び出し ID、raw な引数文字列など）にアクセスしたいことがあります。 +このために、`RunContextWrapper` を拡張した [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。 ```python from typing import Annotated @@ -106,22 +106,22 @@ agent = Agent( ``` `ToolContext` は `RunContextWrapper` と同じ `.context` プロパティに加えて、 -現在のツール呼び出しに特化した追加フィールドを提供します。 +現在のツール呼び出しに固有の追加フィールドを提供します。 -- `tool_name` – 呼び出されているツール名 -- `tool_call_id` – このツール呼び出しの一意な識別子 -- `tool_arguments` – ツールに渡された raw 引数文字列 +- `tool_name` – 呼び出されるツールの名前 +- `tool_call_id` – このツール呼び出しの一意の識別子 +- `tool_arguments` – ツールに渡された raw な引数文字列 -実行中にツールレベルのメタデータが必要な場合は `ToolContext` を使ってください。 -エージェント間やツール間での一般的なコンテキスト共有には、`RunContextWrapper` で十分です。 +実行時にツールレベルのメタデータが必要な場合は `ToolContext` を使用してください。 +エージェントとツール間の一般的なコンテキスト共有には `RunContextWrapper` で十分です。 --- -## エージェント / LLM のコンテキスト +## エージェント/LLM コンテキスト -LLM が呼び出されるとき、参照できるのは会話履歴のデータだけです。つまり、新しいデータを LLM に利用させたい場合は、その履歴で参照可能になるようにデータを提供する必要があります。方法はいくつかあります。 +LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。つまり、LLM に新しいデータを利用させたい場合は、その履歴で参照できる形で提供する必要があります。次のいくつかの方法があります。 -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは固定文字列でも、コンテキストを受け取って文字列を出力する動的関数でもかまいません。常に有用な情報（例: ユーザー名や現在日付）に適した一般的な手法です。 -2. `Runner.run` を呼び出すときの `input` に追加します。これは `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) において、より下位のメッセージにできます。 -3. 関数ツール を通じて公開します。これはオンデマンドのコンテキストに便利です。LLM が必要に応じてデータ取得のためにツールを呼び出せます。 -4. リトリーバルや Web 検索 を使います。これは、ファイルやデータベース（リトリーバル）または Web（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに有用です。 \ 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（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答を「グラウンディング」するのに役立ちます。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index da5d268c1..6eabb595b 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,90 +4,90 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) のコード例セクションで、SDK のさまざまなサンプル実装をご覧ください。コード例は、異なるパターンや機能を示す複数のカテゴリーに整理されています。 +[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションには、SDK の多様なサンプル実装があります。これらのコード例は、さまざまなパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例は、次のような一般的なエージェント設計パターンを示します + このカテゴリーの例では、一般的なエージェント設計パターンを示します。例えば: - 決定的なワークフロー - - ツールとしてのエージェント - - エージェントの並列実行 + - ツールとしての エージェント + - エージェント の並列実行 - 条件付きツール使用 - - 入出力のガードレール + - 入出力ガードレール - 判定者としての LLM - ルーティング - ストリーミング ガードレール - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらの例は、SDK の基礎的な機能を示します + このカテゴリーの例では、SDK の基礎的な機能を紹介します。例えば: - - Hello world のコード例（デフォルトモデル、 GPT-5 、オープンウェイトモデル） - - エージェントのライフサイクル管理 + - Hello World のコード例（デフォルト モデル、GPT-5、open-weight モデル） + - エージェント のライフサイクル管理 - 動的な システムプロンプト - - ストリーミング出力（テキスト、項目、関数呼び出し引数） - - プロンプトテンプレート + - ストリーミング出力（テキスト、アイテム、function call args） + - プロンプト テンプレート - ファイル処理（ローカルとリモート、画像と PDF） - - 利用状況のトラッキング - - 非厳密な出力型 - - 以前のレスポンス ID の利用 + - 使用状況の追跡 + - 厳密でない出力型 + - 以前の response ID の使用 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** 航空会社向けのカスタマーサービス システムの例。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融データ分析のために、エージェントとツールで構造化されたリサーチ ワークフローを示す金融リサーチ エージェント。 + エージェント とツールを用いた財務データ分析のための、構造化された調査ワークフローを示す金融リサーチ エージェント。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - メッセージ フィルタリングを用いたエージェントのハンドオフの実用例。 + メッセージ フィルタリングを伴うエージェントのハンドオフの実用例。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - ホストされた MCP (Model Context Protocol) コネクタと承認の使い方を示すコード例。 + ホストされた MCP (Model Context Protocol) のコネクタと承認の使い方を示す例。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model Context Protocol) を使ってエージェントを構築する方法。以下を含みます: + MCP (Model Context Protocol) を用いたエージェントの構築方法を学べます。内容: - - ファイルシステムのコード例 - - Git のコード例 - - MCP プロンプト サーバーのコード例 - - SSE (Server-Sent Events) のコード例 - - ストリーム可能な HTTP のコード例 + - ファイルシステムの例 + - Git の例 + - MCP プロンプト サーバーの例 + - SSE (Server-Sent Events) の例 + - ストリーム可能な HTTP の例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - エージェント向けのさまざまなメモリ実装の例。以下を含みます: + エージェント向けのさまざまなメモリ実装の例。内容: - - SQLite セッションストレージ - - 高度な SQLite セッションストレージ - - Redis セッションストレージ - - SQLAlchemy セッションストレージ - - 暗号化セッションストレージ - - OpenAI セッションストレージ + - SQLite セッション ストレージ + - 高度な SQLite セッション ストレージ + - Redis セッション ストレージ + - SQLAlchemy セッション ストレージ + - 暗号化されたセッション ストレージ + - OpenAI セッション ストレージ - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - OpenAI 以外のモデルを、カスタムプロバイダや LiteLLM 連携を含めて SDK で使う方法を学べます。 + カスタム プロバイダーや LiteLLM 連携を含む、OpenAI 以外のモデルを SDK で使う方法。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイム体験を構築する方法のコード例。以下を含みます: + SDK を使ってリアルタイム 体験を構築する方法を示す例。内容: - Web アプリケーション - コマンドライン インターフェース - - Twilio 連携 + - Twilio 連携 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 推論コンテンツと structured outputs を扱う方法のコード例。 + 推論コンテンツと structured outputs を扱う方法を示す例。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 複雑な複数 エージェントのリサーチ ワークフローを示す、シンプルな ディープリサーチ クローン。 + 複雑なマルチエージェント リサーチ ワークフローを示す、ディープリサーチの簡易クローン。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 次のような OpenAI がホストするツールの実装方法を学べます: + 次のような OpenAI がホストするツール の実装方法を学べます: - - Web 検索 と フィルタ付きの Web 検索 + - Web 検索 と フィルター付き Web 検索 - ファイル検索 - - Code interpreter + - Code Interpreter - コンピュータ操作 - 画像生成 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 音声 エージェントのコード例。 TTS と STT のモデルを使用し、ストリーミング音声のコード例も含みます。 \ No newline at end of file + TTS と STT モデルを使った音声 エージェントの例。ストリーミング音声のコード例を含みます。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index f9819ab43..a573d7675 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,54 +4,54 @@ search: --- # ガードレール -ガードレールは、 ユーザー 入力と エージェント 出力に対してチェックと検証を行えるようにします。例えば、カスタマーリクエストを支援するために非常に賢い（そのぶん遅く/高価な）モデルを使う エージェント を想像してください。悪意のある ユーザー がそのモデルに数学の宿題を手伝わせるような依頼をするのは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが不正使用を検知した場合、即座にエラーを発生させて高価なモデルの実行を防ぎ、時間とコストを節約できます（**ブロッキング型のガードレール使用時。並列ガードレールでは、ガードレール完了前に高価なモデルがすでに実行を開始している可能性があります。詳細は下記「実行モード」を参照**）。 +ガードレールは、ユーザー入力およびエージェント出力に対するチェックとバリデーションを可能にします。たとえば、非常に賢い（つまり遅く/高価な）モデルを使ってカスタマーリクエストを支援するエージェントがあるとします。悪意あるユーザーが、そのモデルに数学の宿題を手伝わせるような依頼をするのは望ましくありません。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが不正な使用を検知した場合、即座にエラーを発生させ、高価なモデルの実行を防ぐことで時間とコストを節約できます（ **ブロッキング型ガードレールを使用する場合。並列ガードレールでは、ガードレールが完了する前に高価なモデルがすでに実行を開始している可能性があります。詳細は以下の「実行モード」を参照してください** ）。 ガードレールには 2 種類あります: -1. 入力ガードレールは初期の ユーザー 入力で実行されます -2. 出力ガードレールは最終的な エージェント 出力で実行されます +1. 入力ガードレールは初回のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 ステップで動作します: +入力ガードレールは 3 つのステップで実行されます: -1. まず、ガードレールは エージェント に渡されたものと同じ入力を受け取ります。 +1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるため、 ユーザー への適切な応答や例外処理が可能です。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 入力ガードレールは ユーザー 入力に対して実行されることを意図しているため、 エージェント のガードレールは、その エージェント が「最初の」 エージェント の場合にのみ実行されます。なぜ `guardrails` プロパティが エージェント 側にあり、`Runner.run` に渡さないのかと疑問に思うかもしれません。これは、ガードレールが実際の エージェント に密接に関連する傾向があるからです。 エージェント ごとに異なるガードレールを実行するため、コードを同じ場所に置いておくと可読性が向上します。 + 入力ガードレールはユーザー入力で実行されることを想定しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントである場合にのみ実行されます。「`guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのはなぜか？」と思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所にまとめることで可読性が向上します。 ### 実行モード 入力ガードレールは 2 つの実行モードをサポートします: -- **並列実行**（デフォルト、`run_in_parallel=True`）: ガードレールは エージェント の実行と同時に並行して実行されます。両者が同時に開始するため、レイテンシは最小になります。ただし、ガードレールが失敗した場合でも、キャンセルされる前に エージェント がすでにトークンを消費し、ツールを実行している可能性があります。 +- **並列実行**（デフォルト、`run_in_parallel=True`）: ガードレールはエージェントの実行と同時に並行して実行されます。両者が同時に開始されるため、最良のレイテンシーを提供します。ただし、ガードレールが失敗した場合でも、キャンセルされるまでにエージェントがすでにトークンを消費し、ツールを実行している可能性があります。 -- **ブロッキング実行**（`run_in_parallel=False`）: ガードレールは エージェント の開始「前」に実行・完了します。ガードレールのトリップワイヤーが発火した場合、 エージェント は実行されず、トークン消費やツール実行を防げます。これはコスト最適化や、ツール呼び出しによる副作用を避けたい場合に最適です。 +- **ブロッキング実行**（`run_in_parallel=False`）: ガードレールはエージェントが開始する *前に* 実行・完了します。ガードレールのトリップワイヤーが発火した場合、エージェントは一切実行されず、トークン消費やツール実行を防止します。これはコスト最適化や、ツール呼び出しによる副作用を避けたい場合に最適です。 ## 出力ガードレール -出力ガードレールは 3 ステップで動作します: +出力ガードレールは 3 つのステップで実行されます: -1. まず、ガードレールは エージェント によって生成された出力を受け取ります。 +1. まず、ガードレールはエージェントによって生成された出力を受け取ります。 2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるため、 ユーザー への適切な応答や例外処理が可能です。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 出力ガードレールは最終的な エージェント の出力に対して実行されることを意図しているため、 エージェント のガードレールは、その エージェント が「最後の」 エージェント の場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際の エージェント に密接に関連する傾向があるため、コードを同じ場所に置いておくと可読性が向上します。 + 出力ガードレールは最終的なエージェント出力で実行されることを想定しているため、エージェントのガードレールはそのエージェントが *最後* のエージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所にまとめると可読性が向上します。 - 出力ガードレールは常に エージェント の完了後に実行されるため、`run_in_parallel` パラメーターはサポートされません。 + 出力ガードレールは常にエージェントの完了後に実行されるため、`run_in_parallel` パラメーターはサポートしません。 ## トリップワイヤー -入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが発火したガードレールを検知するとすぐに、{Input,Output}GuardrailTripwireTriggered 例外を送出し、 エージェント の実行を停止します。 +入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでそれを通知できます。トリップワイヤーが発火したガードレールを検出すると、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、水面下で エージェント を実行することでこれを行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、内部でエージェントを実行してこれを行います。 ```python from pydantic import BaseModel @@ -104,10 +104,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. この エージェント をガードレール関数内で使用します。 -2. これは エージェント の入力/コンテキストを受け取り、結果を返すガードレール関数です。 +1. このエージェントをガードレール関数内で使用します。 +2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 3. ガードレール結果に追加情報を含めることができます。 -4. これはワークフローを定義する実際の エージェント です。 +4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 @@ -162,7 +162,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 c9f57ebbb..71ddb23e5 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`: 引き渡し先となるエージェントです。 +- `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`: ハンドオフが有効かどうか。真偽値または真偽値を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 +- `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 @@ -60,7 +60,7 @@ handoff_obj = handoff( ## ハンドオフの入力 -状況によっては、ハンドオフを呼び出す際に LLM に何らかのデータを提供してほしいことがあります。たとえば、「Escalation agent」へのハンドオフを想像してみてください。ログのために理由を提供してほしい場合があります。 +状況によっては、ハンドオフ呼び出し時に 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` を返す関数です。 -既定では、runner は直前のトランスクリプトを 1 つのアシスタント要約メッセージに折りたたむようになりました（[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を参照）。この要約は、同一の実行中に複数のハンドオフが発生した場合に新しいターンを追加し続ける `` ブロック内に表示されます。完全な `input_filter` を書かずに生成されたメッセージを置き換えるには、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] で独自のマッピング関数を提供できます。これは、ハンドオフ側と実行側のいずれも明示的な `input_filter` を提供しない場合にのみ適用されるため、すでにペイロードをカスタマイズしている既存のコード（このリポジトリ内の code examples を含む）は、変更なしで現在の動作を維持します。単一のハンドオフに対してネスト動作を上書きするには、[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡します。これは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を設定します。生成された要約のラッパーテキストだけを変更したい場合は、エージェントを実行する前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 +既定では、Runner は前の書き起こしを 1 つのアシスタント要約メッセージに折りたたむようになりました（[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を参照）。この要約は、同じ実行中に複数回のハンドオフが発生した場合に新しいターンを追加し続ける `` ブロック内に表示されます。完全な `input_filter` を書かずに生成されたメッセージを置き換えたい場合は、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] を指定して独自のマッピング関数を提供できます。この既定は、ハンドオフ側と実行側のどちらも明示的な `input_filter` を提供しない場合にのみ適用されるため、ペイロードをすでにカスタマイズしている既存のコード（このリポジトリの code examples を含む）は、変更なしで現在の動作を維持します。単一のハンドオフに対してネストの挙動を上書きしたい場合は、[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡して、[`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を設定します。生成された要約のラッパーテキストだけを変更する必要がある場合は、エージェントを実行する前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 いくつかの一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 @@ -102,11 +102,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 4f12c104c..441bf40cc 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 と組み合わせることで、これらの基本コンポーネントは tools と エージェント の複雑な関係を表現でき、学習コストを抑えつつ実運用レベルのアプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェント フローの可視化・デバッグ・評価に加えて、アプリケーション向けにモデルのファインチューニングも行えます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、急な学習曲線なしに実運用アプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェント フローの可視化とデバッグ、評価、さらにはアプリケーション向けモデルのファインチューニングまで行えます。 ## Agents SDK を使う理由 -この SDK は次の 2 つの設計原則に基づいています。 +SDK には 2 つの設計原則があります。 -1. 使う価値があるだけの機能は備えるが、学習を素早くするため基本コンポーネントは少数に保つ。 -2. そのままでも優れた動作をするが、挙動を細部までカスタマイズできる。 +1. 使う価値のある十分な機能を備えつつ、少数の基本コンポーネントで素早く学べること。 +2. すぐに使えて優れた体験を提供しつつ、動作を細部までカスタマイズできること。 SDK の主な機能は次のとおりです。 -- エージェント ループ: tools の呼び出し、結果の LLM への送信、LLM の完了までのループを処理する組み込みループ。 -- Python ファースト: 新しい抽象化を学ぶのではなく、言語の標準機能で エージェント のオーケストレーションや連鎖を実現。 -- ハンドオフ: 複数の エージェント 間での調整と委任を可能にする強力な機能。 -- ガードレール: エージェント と並行して入力の検証やチェックを実行し、失敗時には早期中断。 -- セッション: エージェント 実行間での会話履歴を自動管理し、手動での状態管理を不要に。 -- 関数ツール: 任意の Python 関数を tool に変換し、自動スキーマ生成と Pydantic ベースの検証を提供。 -- トレーシング: ワークフローの可視化・デバッグ・監視に加え、OpenAI の評価・ファインチューニング・蒸留ツール群を活用できる組み込みのトレーシング。 +- エージェント ループ: ツールの呼び出し、結果の LLM への送信、LLM が完了するまでのループ処理を内蔵。 +- Python ファースト: 新しい抽象概念を学ぶのではなく、言語組み込み機能でエージェントのオーケストレーションと連鎖を実現。 +- ハンドオフ: 複数エージェント間の調整と委譲を可能にする強力な機能。 +- ガードレール: エージェントと並行して入力検証やチェックを実行し、失敗時は早期に中断。 +- セッション: エージェント実行間の会話履歴を自動管理し、手動の状態管理を排除。 +- 関数ツール: 任意の Python 関数をツール化し、自動スキーマ生成と Pydantic ベースの検証を提供。 +- トレーシング: ワークフローの可視化、デバッグ、モニタリングに加え、OpenAI の評価、ファインチューニング、蒸留ツール群を活用可能。 ## インストール @@ -36,7 +36,7 @@ SDK の主な機能は次のとおりです。 pip install openai-agents ``` -## Hello World の例 +## Hello world のサンプル ```python from agents import Agent, Runner diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index d5514fb4d..434349370 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,34 +4,34 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに提供する方法を標準化します。公式ドキュメントより: > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI > applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP > provides a standardized way to connect AI models to different data sources and tools. -Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、独自のサーバーを構築して、ファイルシステム、HTTP、またはコネクタを基盤とするツールをエージェントに公開できます。 +Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、独自に構築して、ファイルシステム、HTTP、またはコネクタ バックエンドのツールを エージェント に公開できます。 ## Choosing an MCP integration -MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションの概要です。 +MCP サーバーを エージェント に組み込む前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションをまとめたものです。 -| 必要なこと | 推奨オプション | +| What you need | Recommended option | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| OpenAI の Responses API に、モデルの代理でパブリック到達可能な MCP サーバーを呼ばせたい | **Hosted MCP server tools**（ホスト型 MCP ツール） via [`HostedMCPTool`][agents.tool.HostedMCPTool] | -| ローカルまたはリモートで稼働する Streamable HTTP サーバーに接続したい | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | -| Server-Sent Events を実装する HTTP サーバーと通信したい | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | -| ローカルプロセスを起動し、stdin/stdout で通信したい | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | +| OpenAI の Responses API がモデルの代わりに、公開到達可能な MCP サーバーを呼び出せるようにする | **Hosted MCP server tools** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | **Streamable HTTP MCP servers** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Server-Sent Events を伴う HTTP を実装するサーバーと通信する | **HTTP with SSE MCP servers** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| ローカルプロセスを起動し、stdin/stdout 経由で通信する | **stdio MCP servers** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -以下のセクションでは、それぞれのオプション、設定方法、どのトランスポートを選ぶべきかを説明します。 +以下のセクションでは、各オプションの設定方法と、どのトランスポートを優先すべきかを説明します。 ## 1. Hosted MCP server tools -Hosted ツールは、ツールの往復をすべて OpenAI のインフラに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] は サーバーラベル（およびオプションのコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを一覧し、あなたの Python プロセスへの追加コールバックなしでそれらを呼び出します。Hosted ツールは現在、Responses API の hosted MCP 連携をサポートする OpenAI モデルで動作します。 +ホスト型ツールは、ツールの往復処理全体を OpenAI のインフラに移します。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバーラベル（および任意のコネクタ メタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを一覧し、あなたの Python プロセスへの追加のコールバックなしにそれらを呼び出します。ホスト型ツールは現在、Responses API の hosted MCP 統合をサポートする OpenAI モデルで動作します。 ### Basic hosted MCP tool -エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` の dict は、REST API に送信する JSON を反映します: +エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` の dict は、REST API に送る JSON を反映します: ```python import asyncio @@ -59,11 +59,11 @@ async def main() -> None: asyncio.run(main()) ``` -Hosted サーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 +ホストされたサーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 ### Streaming hosted MCP results -Hosted ツールは、関数ツールとまったく同じ方法で結果の ストリーミング をサポートします。`Runner.run_streamed` に `stream=True` を渡して、モデルが処理中でも増分的な MCP 出力を消費します: +ホスト型ツールは、関数ツールとまったく同じ方法で ストリーミング 結果をサポートします。`Runner.run_streamed` に `stream=True` を渡して、モデルが処理を続けている間に増分の MCP 出力を消費します: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -75,7 +75,7 @@ print(result.final_output) ### Optional approval flows -サーバーが機微な操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を要求できます。`tool_config` の `require_approval` を単一のポリシー（`"always"`, `"never"`）またはツール名からポリシーへの dict で設定します。Python 内で判断するには、`on_approval_request` コールバックを提供します。 +サーバーが機微な操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を必須にできます。`tool_config` の `require_approval` を単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict で設定します。判断を Python 内で行うには、`on_approval_request` コールバックを指定します。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -103,11 +103,11 @@ agent = Agent( ) ``` -コールバックは同期または非同期のどちらでもかまいません。モデルが実行を続けるために承認データを必要とするたびに呼び出されます。 +コールバックは同期/非同期のどちらでもよく、モデルが実行を継続するために承認データを必要とするたびに呼び出されます。 ### Connector-backed hosted servers -Hosted MCP は OpenAI コネクタにも対応しています。`server_url` を指定する代わりに、`connector_id` とアクセス トークンを指定します。Responses API が認証を処理し、hosted サーバーがコネクタのツールを公開します。 +Hosted MCP は OpenAI コネクタもサポートします。`server_url` を指定する代わりに、`connector_id` とアクセス トークンを指定します。Responses API が認証を処理し、ホストされたサーバーがコネクタのツールを公開します。 ```python import os @@ -123,12 +123,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 @@ -163,16 +164,17 @@ async def main() -> None: 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) を参照）。 +- `tool_filter` は、公開するツールをサブセットに制限できます（[Tool filtering](#tool-filtering) を参照）。 ## 3. HTTP with SSE MCP servers -MCP サーバーが HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 +MCP サーバーが HTTP with SSE トランスポートを実装している場合は、 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 ```python @@ -201,7 +203,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 +231,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 @@ -251,11 +253,11 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後で残りの集合からブロック対象のツールを削除します。 +`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK は先に許可リストを適用し、その後で残りの集合からブロックされたツールを除外します。 ### Dynamic tool filtering -より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る callable を渡します。callable は同期または非同期のいずれでもよく、ツールを公開すべき場合に `True` を返します。 +より詳しいロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。これは同期/非同期のどちらでもよく、ツールを公開すべき場合に `True` を返します。 ```python from pathlib import Path @@ -279,14 +281,14 @@ async with MCPServerStdio( ... ``` -フィルターコンテキストには、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` が提供されます。 +フィルター コンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 ## Prompts MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 つのメソッドを公開します: -- `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。 +- `list_prompts()` は利用可能なプロンプト テンプレートを列挙します。 +- `get_prompt(name, arguments)` は、必要に応じて パラメーター を指定して具体的なプロンプトを取得します。 ```python from agents import Agent @@ -306,19 +308,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.md) は MCP のアクティビティを自動的に捕捉します。含まれるもの: +[Tracing](./tracing.md) は MCP のアクティビティを自動的に取得し、次を含みます: -1. ツール一覧のための MCP サーバーへの呼び出し。 +1. ツールを一覧表示するための MCP サーバーへの呼び出し。 2. ツール呼び出しに関する MCP 関連情報。 ![MCP Tracing Screenshot](../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 4ac8806dd..6c1c27994 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、次の 2 つの形式で OpenAI モデルのサポートが標準で含まれています。 +Agents SDK には、OpenAI モデルに対するすぐに使えるサポートが 2 種類あります。 -- **推奨**: 新しい [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] +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 -## OpenAI モデル +## OpenAI のモデル -`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_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 のいずれかの推論モデル（[`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 のいずれかの推論モデル（[`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")` を呼び出してください。 -レイテンシをさらに下げたい場合や特定の要件がある場合は、別のモデルや設定を選べます。デフォルトモデルの推論負荷を調整するには、独自の `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"` の推論負荷をサポートしていないため、この 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 つあります（[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) に code examples があります）。 -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 をまだサポートしていない LLM プロバイダーが多いため、Chat Completions API/モデルを使用しています。プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。 + これらの例では、ほとんどの LLM プロバイダーが Responses API をまだサポートしていないため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses をサポートしている場合は、Responses の使用をおすすめします。 ## モデルの組み合わせ -単一のワークフローの中で、エージェントごとに異なるモデルを使いたい場合があります。例えば、トリアージには小型で高速なモデルを、複雑なタスクにはより大きく高性能なモデルを使うといった具合です。[`Agent`][agents.Agent] を設定するとき、特定のモデルを次のいずれかの方法で選べます。 +単一のワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小型で高速なモデルを、複雑なタスクには大型で高機能なモデルを使うことができます。[`Agent`][agents.Agent] を構成する際、次のいずれかの方法で特定のモデルを選べます。 -1. モデル名を渡す。 -2. 任意のモデル名と、その名前を Model インスタンスへマップできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +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] の両方の形をサポートしますが、両者で対応する機能やツールのセットが異なるため、各ワークフローでは単一のモデル形を使用することを推奨します。ワークフロー上、モデル形を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは単一のモデル形状を使用することをおすすめします。ワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -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 -トレーシング関連のエラーが発生する場合、トレースは 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/) のものを使用する必要があります。 +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 などの問題が発生することがあります。解決するには、次の 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] を使用します。[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) に例があります。 -### structured outputs のサポート +### Structured outputs のサポート -一部のモデルプロバイダーは、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 +一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。 ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダー側の制約で、JSON 出力はサポートしていても、出力に使用する `json_schema` を指定できないというものです。現在この点の改善に取り組んでいますが、JSON スキーマ出力をサポートしているプロバイダーに依存することを推奨します。そうでない場合、不正な JSON によりアプリが頻繁に壊れてしまいます。 +これは一部のモデルプロバイダー側の不足によるもので、JSON 出力はサポートしているものの、出力に使用する `json_schema` を指定できません。現在この点の修正に取り組んでいますが、アプリが不正な JSON により壊れることが頻発するため、JSON スキーマ出力をサポートしているプロバイダーに依存することをおすすめします。 -## プロバイダー間でのモデル混在 +## プロバイダー間でのモデルの混在 -モデルプロバイダー間の機能差を把握していないと、エラーに遭遇する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 +モデルプロバイダー間での機能差に注意しないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索および Web 検索をサポートしますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 -- サポートしていないプロバイダーに対しては、理解されない `tools` を送らないでください -- テキスト専用モデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- structured JSON 出力をサポートしていないプロバイダーでは、無効な JSON が時折生成されることに注意してください。 \ No newline at end of file +- サポートしていないプロバイダーに対して、未対応の `tools` を送らないでください +- テキストのみのモデルを呼び出す前に、マルチモーダル入力を除外してください +- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を生成する場合があります \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index c60894d01..295430ceb 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM による任意モデルの利用 +# LiteLLM による任意モデルの使用 !!! note - LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する場合があります。問題は [GitHub issues](https://github.com/openai/openai-agents-python/issues) で報告してください。迅速に対応します。 + LiteLLM の統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する場合があります。問題は [Github issues](https://github.com/openai/openai-agents-python/issues) にご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100 以上のモデルを利用できるライブラリです。Agents SDK に LiteLLM 連携を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM の統合を追加し、任意の AI モデルを利用できるようにしました。 ## セットアップ -`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 +`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください: ```bash pip install "openai-agents[litellm]" ``` -完了したら、任意の エージェント で [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 +完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 -## コード例 +## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば次を入力できます。 +これは完全に動作するサンプルです。実行すると、モデル名と API キーの入力を求められます。例えば次のように入力できます: -- `openai/gpt-4.1`（モデル）と、あなたの OpenAI API キー -- `anthropic/claude-3-5-sonnet-20240620`（モデル）と、あなたの Anthropic API キー +- `openai/gpt-4.1`（モデル）とご自身の OpenAI API キー +- `anthropic/claude-3-5-sonnet-20240620`（モデル）とご自身の Anthropic API キー - など -LiteLLM でサポートされているモデルの全一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM でサポートされているモデルの一覧は、[litellm のプロバイダー ドキュメント](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 @@ -91,4 +91,4 @@ agent = Agent( ) ``` -`include_usage=True` を指定すると、LiteLLM のリクエストは、組み込みの OpenAI モデルと同様に、`result.context_wrapper.usage` を通じてトークン数とリクエスト数を報告します。 \ No newline at end of file +`include_usage=True` を指定すると、LiteLLM のリクエストは組み込みの OpenAI モデルと同様に、`result.context_wrapper.usage` を通じてトークン数とリクエスト数を報告します。 \ No newline at end of file diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index caf7f6a5b..8eb225ec0 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、ツール、ハンドオフ を備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はツールを使ってアクションやデータ取得を行い、ハンドオフ でサブエージェントに委任しながら、タスクに取り組む計画を自律的に立てられます。たとえば、リサーチ用の エージェント には以下のようなツールを備えられます。 +エージェントは、 instructions、 tools、そして ハンドオフ を備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的に計画を立て、ツールを使って行動・データ取得を行い、ハンドオフ によってサブエージェントにタスクを委譲できることを意味します。たとえば、リサーチ用エージェントには次のようなツールを備えられます。 -- Web 検索 によるオンライン情報の収集 -- ファイル検索 と取得によるプロプライエタリデータや接続先の検索 -- コンピュータ操作 によるコンピュータ上でのアクション実行 -- コード実行 によるデータ分析 -- 計画立案、レポート執筆などに長けた特化型 エージェント への ハンドオフ +- Web 検索でオンライン情報を見つける +- ファイル検索 と取得でプロプライエタリなデータや接続を検索する +- コンピュータ操作 でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画策定、レポート作成などに優れた特化エージェントへの ハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知性に依拠したい場合に適しています。重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知性に依拠したい場合に有効です。重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、遵守すべき パラメーター を明確にします。 -2. アプリを監視して改善を繰り返す。うまくいかない箇所を見極め、プロンプトを反復改善します。 -3. エージェント に内省と改善を許可する。たとえばループで実行して自己批判させる、あるいはエラーメッセージを与えて改善させます。 -4. 何でもできる汎用 エージェント を期待するのではなく、特定のタスクに特化して卓越する エージェント を用意する。 -5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資する。これにより エージェント を訓練して性能を高められます。 +1. 良いプロンプトに投資する。利用可能なツール、使い方、そしてどのパラメーター内で動作すべきかを明確にします。 +2. アプリをモニタリングし、反復改善する。問題が起きる箇所を確認し、プロンプトを改善します。 +3. エージェントに内省と改善を許可する。たとえば、ループで実行して自己批評させる、またはエラーメッセージを与えて改善させます。 +4. なんでもできる汎用エージェントではなく、単一タスクに特化して優れたエージェントを用意します。 +5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資します。これにより、エージェントを訓練してタスク達成能力を向上できます。 -## コード によるオーケストレーション +## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コード によるオーケストレーションは、速度・コスト・性能の面でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは速度、コスト、パフォーマンスの観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を用いて、コードで検査できる 適切な形式のデータ を生成する。たとえば、タスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次の エージェント を選ぶ、といった使い方です。 -- ある エージェント の出力を次の エージェント の入力に変換して連鎖させる。ブログ記事の執筆のようなタスクを、調査→アウトライン作成→本文執筆→批評→改善といった一連のステップに分解できます。 -- タスクを実行する エージェント と、それを評価してフィードバックする エージェント を `while` ループで回し、評価者が所定の基準を満たしたと判断するまで繰り返す。 -- 複数の エージェント を並列実行する（例: 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 diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 562c4e528..375c30e2b 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -これは 1 回だけ行えば十分です。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -お持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +まだお持ちでない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 ```bash export OPENAI_API_KEY=sk-... ``` -## 最初のエージェントの作成 +## 最初の エージェント の作成 -エージェントは instructions、名前、およびオプションの設定（`model_config` など）で定義します。 +エージェント は instructions、名前、オプションの設定（例えば `model_config`）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## エージェントの追加 +## いくつかの エージェント の追加 -追加のエージェントも同様に定義できます。`handoff_descriptions` は、ハンドオフのルーティングを判断するための追加コンテキストを提供します。 +追加の エージェント も同様に定義できます。`handoff_descriptions` はハンドオフ ルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## ハンドオフの定義 +## ハンドオフ の定義 -各エージェントで、タスクを前進させる方法を決める際に選択できる送信側ハンドオフの候補一覧を定義できます。 +各 エージェント ごとに、タスクを進める方法を決める際に選択できる送信側のハンドオフ オプションの一覧を定義できます。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ triage_agent = Agent( ) ``` -## エージェントのオーケストレーションの実行 +## エージェント オーケストレーションの実行 -ワークフローが実行され、トリアージ用エージェントが 2 つの専門エージェント間を正しくルーティングすることを確認します。 +ワークフローが実行され、トリアージ エージェント が 2 つの専門 エージェント 間を正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## まとめて実行 +## すべてを組み合わせる -ハンドオフと入力用ガードレールを使って、すべてをまとめてワークフロー全体を実行します。 +ハンドオフ と入力 ガードレール を使い、すべてを組み合わせてワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの表示 +## トレースの閲覧 -エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して実行のトレースを表示します。 +エージェント 実行中に何が起きたかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces) に移動して、エージェント 実行のトレースを表示します。 ## 次のステップ -より複雑なエージェント フローの構築方法を学びましょう: +より複雑な エージェント フローの構築方法を学びましょう: -- [エージェント](agents.md) の設定方法について学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [tools](tools.md)、[ガードレール](guardrails.md)、および [モデル](models/index.md) について学びます。 \ No newline at end of file +- Learn about how to configure [エージェント](agents.md). +- Learn about [エージェントの実行](running_agents.md). +- Learn about [ツール](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 1f35ee95e..1c4e265df 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,59 +4,59 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、 OpenAI Agents SDK の realtime 機能を用いて音声対応の AI エージェントを構築する方法を詳しく解説します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的な変更が発生する可能性があります。 +Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 ## 概要 -Realtime エージェントは、音声とテキストの入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを可能にします。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声会話を実現し、割り込みにも適切に対処します。 +Realtime エージェントは、音声およびテキスト入力をリアルタイムに処理し、リアルタイム音声で応答する会話フローを可能にします。 OpenAI の Realtime API との永続的な接続を維持し、低遅延で自然な音声対話と、割り込みへのスムーズな対応が可能です。 ## アーキテクチャ ### コアコンポーネント -realtime システムは、次の主要コンポーネントで構成されます。 +realtime システムは、いくつかの主要コンポーネントで構成されます。 - **RealtimeAgent**: instructions、tools、handoffs を設定したエージェント。 - **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデル インターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeSession**: 単一の対話セッション。通常、ユーザーが会話を開始するたびに作成し、会話が完了するまで維持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（一般的には OpenAI の WebSocket 実装） ### セッションフロー -一般的な realtime セッションは次の流れに従います。 +一般的な realtime セッションは次のフローに従います。 1. **RealtimeAgent を作成** し、instructions、tools、handoffs を設定します。 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 モデルとの永続的な接続を管理します。 +セッションは会話履歴を保持し、 realtime モデルとの永続的な接続を管理します。 ## エージェント設定 -RealtimeAgent は、通常の Agent クラスと同様に動作しますが、いくつかの重要な違いがあります。完全な API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 +RealtimeAgent は、通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。完全な API の詳細については、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 -通常のエージェントとの主な相違点: +通常のエージェントとの主な違い: -- モデル選択はエージェント レベルではなくセッション レベルで設定します。 +- モデル選択はエージェントレベルではなく、セッションレベルで設定します。 - structured outputs はサポートされません（`outputType` はサポートされません）。 -- ボイスはエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- その他の機能（tools、handoffs、instructions）は同様に動作します。 +- 音声はエージェントごとに設定できますが、最初のエージェントが発話した後は変更できません。 +- その他、tools、handoffs、instructions などの機能は同様に動作します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-realtime` など）、ボイス選択（alloy、echo、fable、onyx、nova、shimmer）、対応モダリティ（テキストおよび／または音声）を設定できます。音声フォーマットは入力と出力の両方で設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-realtime` など）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、対応するモダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力と出力の両方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、ドメイン固有用語の精度を高めるための書き起こしプロンプトを設定できます。ターン検出設定では、エージェントがいつ応答を開始・終了すべきかを制御し、音声活動検出のしきい値、無音時間、検出された発話の前後のパディングなどを指定できます。 +音声設定では、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使った入力音声の文字起こし、言語設定、ドメイン特有の用語の精度を高めるための文字起こしプロンプトを設定できます。ターン検出設定では、音声活動検出のしきい値、無音時間、検出された発話の前後のパディングなどを用いて、エージェントが応答を開始・終了するタイミングを制御します。 ## ツールと関数 @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフによって、専門化されたエージェント間で会話を引き継ぐことができます。 +ハンドオフでは、会話を専門化されたエージェント間で移譲できます。 ```python from agents.realtime import realtime_handoff @@ -119,12 +119,12 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはイベントをストリーミングし、セッション オブジェクトを反復処理してリッスンできます。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に処理すべき主要イベントは次のとおりです。 +セッションは、セッションオブジェクトをイテレートすることでリッスンできるイベントをストリーミングします。イベントには、音声出力チャンク、文字起こしの結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に処理すべき主要イベントは次のとおりです。 -- **audio**: エージェントの応答からの Raw 音声データ +- **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( ## ガードレール -realtime エージェントでサポートされるのは出力 ガードレール のみです。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために（毎語ではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 +realtime エージェントでサポートされるのは出力ガードレールのみです。これらのガードレールはデバウンスされ、パフォーマンス問題を避けるために（単語ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` 経由で提供できます。両方のソースのガードレールは併せて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースのガードレールは併用されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,19 +152,19 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能要件のバランスが保たれます。テキスト エージェントと異なり、realtime エージェントはガードレールが作動しても例外を **発生させません**。 +ガードレールがトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキストエージェントと異なり、realtime エージェントはガードレール発火時に **Exception を** 送出しません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用して音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使って音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使ってテキストを送信します。 -音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで音声データを再生します。ユーザーがエージェントを割り込んだ際に即座に再生を停止し、キューされた音声をクリアするために、必ず `audio_interrupted` イベントもリッスンしてください。 +音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで再生します。ユーザーがエージェントに割り込んだときに即座に再生を停止し、キューにある音声をクリアできるよう、`audio_interrupted` イベントも必ずリッスンしてください。 ## SIP 連携 -[Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip) 経由で着信する電話に realtime エージェントを接続できます。SDK は [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] を提供しており、SIP 上でメディアをネゴシエートしつつ、同じエージェント フローを再利用します。 +[Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip) 経由で着信する電話に realtime エージェントを接続できます。 SDK は [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] を提供しており、SIP 上でメディアをネゴシエートしつつ、同じエージェントフローを再利用します。 -使用するには、ランナーにモデル インスタンスを渡し、セッション開始時に SIP の `call_id` を指定します。コール ID は、着信を通知する Webhook によって送達されます。 +使用するには、モデルインスタンスを runner に渡し、セッション開始時に SIP の `call_id` を指定します。コール ID は、着信を通知する Webhook によって渡されます。 ```python from agents.realtime import RealtimeAgent, RealtimeRunner @@ -187,19 +187,19 @@ async with await runner.run( ... ``` -発信者が電話を切ると、SIP セッションは終了し、realtime 接続は自動的にクローズされます。完全なテレフォニーの code examples は、[`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) を参照してください。 +発信者が切断すると、SIP セッションは終了し、realtime 接続は自動的に閉じられます。完全なテレフォニーの code examples については、[`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) を参照してください。 -## モデルへの直接アクセス +## 直接モデルアクセス -基盤となるモデルにアクセスして、カスタム リスナーの追加や高度な操作を実行できます。 +基盤となるモデルにアクセスして、カスタムリスナーを追加したり高度な操作を実行できます。 ```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] インターフェースへの直接アクセスを提供します。 ## コード例 -完全な動作する code examples は、UI コンポーネントあり／なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 \ No newline at end of file +動作する完全な code examples は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 UI コンポーネントの有無それぞれのデモを含みます。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 6abbeaee7..2f23a8acd 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,26 +4,26 @@ search: --- # クイックスタート -Realtime エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声会話を可能にします。このガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。 +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. ランナーの設定 +### 3. Runner のセットアップ ```python runner = RealtimeRunner( @@ -109,9 +109,9 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 完全なコード例 +## 完全なサンプル -以下は動作する完全な例です: +動作する完全なサンプルはこちらです: ```python import asyncio @@ -192,40 +192,40 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択 (例: `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) フォルダの動作する code examples を確認 -- エージェントにツールを追加 -- エージェント間のハンドオフを実装 -- 安全性のためのガードレールを設定 +- [Realtime エージェントの詳細](guide.md) +- 動作するサンプルは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダを参照してください +- エージェントにツールを追加する +- エージェント間のハンドオフを実装する +- 安全性のためにガードレールを設定する ## 認証 -OpenAI API キーが環境に設定されていることを確認してください: +環境変数に OpenAI API キーが設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション作成時に直接渡します: +またはセッション作成時に直接渡します: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 0b9651177..5ae5c30c6 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,49 +4,49 @@ 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` を増やします: -- バグ修正 +- Bug 修正 - 新機能 -- 非公開インターフェースへの変更 +- 非公開インターフェースの変更 - ベータ機能の更新 ## 破壊的変更の変更履歴 ### 0.6.0 -このバージョンでは、既定のハンドオフ履歴が、生の user/assistant のターンを公開する代わりに、単一のアシスタントメッセージにまとめられるようになり、下流の エージェント に簡潔で予測可能な要約を提供します。 -- 既存の単一メッセージによるハンドオフ記録は、既定で `` ブロックの前に「For context, here is the conversation so far between the user and the previous agent:」という文から始まるようになり、下流の エージェント が明確にラベル付けされた要約を受け取れるようになりました +このバージョンでは、デフォルトのハンドオフ 履歴が、生の ユーザー/アシスタント の会話ターンを公開するのではなく、単一のアシスタント メッセージにまとめられるようになり、下流のエージェントに簡潔で予測可能な要約を提供します +- 既存の単一メッセージのハンドオフ 書き起こしは、デフォルトで `` ブロックの前に "For context, here is the conversation so far between the user and the previous agent:" で始まるようになりました。これにより、下流のエージェントは明確にラベル付けされた要約を受け取れます ### 0.5.0 -このバージョンでは目に見える破壊的変更はありませんが、新機能の追加と内部的にいくつかの重要な更新が含まれています。 +このバージョンは目に見える破壊的変更を導入していませんが、新機能と内部的な重要な更新をいくつか含みます: -- `RealtimeRunner` が [SIP protocol connections](https://platform.openai.com/docs/guides/realtime-sip) を扱えるようになりました -- Python 3.14 互換性のために、`Runner#run_sync` の内部ロジックを大幅に見直しました +- `RealtimeRunner` が [SIP protocol connections](https://platform.openai.com/docs/guides/realtime-sip) を扱えるようサポートを追加 +- Python 3.14 との互換性のため、`Runner#run_sync` の内部ロジックを大幅に改訂 ### 0.4.0 -このバージョンでは、[openai](https://pypi.org/project/openai/) パッケージの v1.x バージョンはサポートされなくなりました。代わりに本 SDK とともに openai v2.x を使用してください。 +このバージョンでは、[openai](https://pypi.org/project/openai/) パッケージの v1.x バージョンはサポートされなくなりました。この SDK とともに openai v2.x を使用してください。 ### 0.3.0 -このバージョンでは、Realtime API のサポートが gpt-realtime モデルおよびその API インターフェース ( GA バージョン ) に移行します。 +このバージョンでは、Realtime API のサポートが gpt-realtime モデルとその API インターフェース (GA バージョン) に移行します。 ### 0.2.0 -このバージョンでは、これまで `Agent` を引数として受け取っていた箇所の一部が、代わりに `AgentBase` を引数として受け取るようになりました。例として、MCP サーバーの `list_tools()` 呼び出しがあります。これは型に関する変更のみで、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正してください。 +このバージョンでは、これまで `Agent` を引数として受け取っていた箇所の一部が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、MCP サーバーでの `list_tools()` 呼び出しなどです。これは純粋に型付け上の変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正してください。 ### 0.1.0 -このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新たに 2 つの params が追加されました: `run_context` と `agent`。`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 096634360..c0934c210 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 ac496f853..d7fcde379 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,48 +4,48 @@ search: --- # 実行結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返ります: +`Runner.run` メソッドを呼び出すと、次のいずれかが得られます。 -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ここに多くの有用な情報が含まれます。 +これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、そこにほとんどの有用な情報が含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は `last_agent.output_type` 型のオブジェクト +- `str`（最後のエージェントに `output_type` が定義されていない場合） +- `last_agent.output_type` 型のオブジェクト（エージェントに出力タイプが定義されている場合） !!! note - `final_output` は型 `Any` です。ハンドオフがあるため、静的型付けはできません。ハンドオフが発生すると、どのエージェントが最後になるか分からないため、可能な出力タイプの集合を静的には特定できません。 + `final_output` の型は `Any` です。ハンドオフがあるため、静的型付けはできません。ハンドオフが発生した場合、どのエージェントでも最後のエージェントになり得るため、可能な出力タイプの集合を静的には把握できません。 -## 次ターンへの入力 +## 次ターンの入力 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、エージェントの実行中に生成されたアイテムを、あなたが提供した元の入力に連結した入力リストに変換できます。これにより、あるエージェント実行の出力を別の実行へ渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが便利になります。 +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] を使うと、実行結果を入力リストに変換し、あなたが提供した元の入力に、エージェントの実行中に生成されたアイテムを連結できます。これにより、あるエージェント実行の出力を別の実行に渡したり、ループで実行して毎回新しい ユーザー 入力を追加したりするのが便利になります。 ## 最後のエージェント -[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、次回 ユーザー が何か入力する際に役立つことがよくあります。たとえば、フロントラインのトリアージ エージェントが言語別のエージェントへハンドオフする場合、最後のエージェントを保存しておき、次回 ユーザー がメッセージを送る際に再利用できます。 +[`last_agent`][agents.result.RunResultBase.last_agent] プロパティには、最後に実行されたエージェントが含まれます。アプリケーションによっては、これは ユーザー が次回入力する際によく役立ちます。たとえば、フロントラインのトリアージ エージェントが言語特化のエージェントにハンドオフする場合、最後のエージェントを保存しておき、次回 ユーザー がエージェントにメッセージを送るときに再利用できます。 ## 新規アイテム -[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。RunItem は、LLM が生成した raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem]: LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem]: LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem]: LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]: ツールが呼び出されたことを示します。raw アイテムはツールの応答です。アイテムからツールの出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem]: LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] は、LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムから送信元/送信先のエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツールのレスポンスです。アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem] は、LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 -### ガードレール結果 +### ガードレールの実行結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、該当する場合にガードレールの実行結果が含まれます。ガードレール結果には、記録や保存をしたい有用な情報が含まれることがあるため、これらを参照できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの実行結果（存在する場合）が含まれます。ガードレールの実行結果には、ログに記録または保存したい有用な情報が含まれることがあるため、これらを参照できるようにしています。 ### raw 応答 @@ -53,4 +53,4 @@ search: ### 元の入力 -[`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 5503f12fb..a962e6160 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -8,7 +8,7 @@ search: 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,59 +23,59 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) を参照してください。 +詳しくは [結果ガイド](results.md) をご覧ください。 ## エージェントループ -`Runner` の run メソッドを使用する際、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージとして扱われます）か、OpenAI Responses API の入力アイテムのリストのいずれかです。 +`Runner` の run メソッドを使うときは、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）か、OpenAI Responses API のアイテムのリストのいずれかです。 -その後、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` パラメーターにより、エージェント実行のグローバル設定を構成できます: +`run_config` パラメーターで、エージェント実行のグローバル設定をいくつか構成できます: -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` 設定に関わらず、使用するグローバルな LLM モデルを設定します。 +- [`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] のドキュメントを参照してください。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: `True`（デフォルト）の場合、runner は次のエージェントを呼び出す前に、直前のやり取りを単一の assistant メッセージに折りたたみます。ヘルパーは内容を `` ブロックに配置し、以降のハンドオフで新しいターンを追記します。過去の raw トランスクリプトをそのまま渡したい場合は、`False` に設定するか、カスタムのハンドオフフィルターを指定してください。すべての [`Runner` methods](agents.run.Runner) は `RunConfig` を未指定時に自動生成するため、クイックスタートや code examples はこのデフォルトを自動的に利用し、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続き優先されます。個々のハンドオフは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] でこの設定を上書きできます。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: 省略可能な呼び出し可能オブジェクトで、`nest_handoff_history` が `True` のときに正規化済みトランスクリプト（履歴 + ハンドオフ アイテム）を受け取り、次のエージェントに転送する入力アイテムのリストを正確に返す必要があります。これにより、完全なハンドオフフィルターを書くことなく、組み込みの要約を置き換えられます。 -- [`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]: すべてのトレースに含めるメタデータ。 - -デフォルトでは、SDK は、エージェントが別のエージェントへハンドオフする際、以前のターンを単一の assistant 要約メッセージ内に入れ子にします。これにより assistant メッセージの重複を減らし、新しいエージェントがすばやくスキャンできるように、完全なトランスクリプトを 1 つのブロック内に保持します。従来の動作に戻したい場合は、`RunConfig(nest_handoff_history=False)` を渡すか、会話を必要なとおりに転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定してください。特定のハンドオフについては、`handoff(..., nest_handoff_history=False)` または `True` を設定して個別にオプトアウト（またはオプトイン）できます。カスタム マッパーを書かずに生成される要約に使うラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（およびデフォルトへ戻す [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 +- [`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] のドキュメントを参照してください。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: `True`（デフォルト）の場合、次のエージェントを呼び出す前に、ランナーはそれまでの記録を 1 つの assistant メッセージに折りたたみます。ヘルパーは内容を `` ブロック内に配置し、以降の ハンドオフ ごとに新しいターンを追記していきます。生の記録をそのまま渡したい場合は、これを `False` にするか、カスタムの ハンドオフ フィルターを指定してください。いずれの [`Runner` メソッド](agents.run.Runner) も、未指定の場合は自動で `RunConfig` を作成します。そのため、クイックスタートや code examples ではこのデフォルトが自動的に適用され、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックがある場合は引き続きそれが優先されます。個々の ハンドオフ は [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] でこの設定を上書きできます。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: 省略可能な呼び出し可能オブジェクトで、`nest_handoff_history` が `True` のときに正規化された記録（履歴 + ハンドオフ アイテム）を受け取ります。次のエージェントへ転送する入力アイテムのリストを正確に返す必要があり、完全な ハンドオフ フィルターを書かずに組み込み要約を置き換えられます。 +- [`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]: すべてのトレースに含めるメタデータです。 + +デフォルトでは、SDK はあるエージェントが別のエージェントに ハンドオフ する際、以前のターンを 1 つの assistant 要約メッセージの中に入れ子にします。これにより、assistant メッセージの重複が減り、完全な記録を新しいエージェントがすばやく走査できる 1 つのブロックに保持できます。従来の動作に戻したい場合は、`RunConfig(nest_handoff_history=False)` を渡すか、会話を必要なとおりにそのまま転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定してください。特定の ハンドオフ については、`handoff(..., nest_handoff_history=False)` または `True` を設定して個別にオプトアウト（またはオプトイン）できます。カスタム マッパーを書かずに生成される要約のラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] を呼び出してください（デフォルトに戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 ## 会話/チャットスレッド -いずれかの run メソッドの呼び出しは、1 つ以上のエージェントの実行（すなわち 1 回以上の LLM 呼び出し）を伴う場合がありますが、チャット会話における 1 回の論理的なターンを表します。例: +任意の run メソッドの呼び出しは、1 回以上のエージェント実行（つまり 1 回以上の LLM 呼び出し）を引き起こす可能性がありますが、チャット会話における 1 回の論理的なターンを表します。例: 1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへハンドオフ、2 つ目のエージェントがさらにツールを実行し、出力を生成 +2. ランナーの実行: 最初のエージェントが 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(): @@ -97,7 +97,7 @@ async def main(): ### Sessions による自動会話管理 -より簡単な方法として、[Sessions](sessions/index.md) を使用すれば、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動的に処理できます: +より簡単な方法として、[Sessions](sessions/index.md) を使えば、`.to_input_list()` を手動で呼び出すことなく、会話履歴を自動処理できます: ```python from agents import Agent, Runner, SQLiteSession @@ -121,24 +121,24 @@ async def main(): # California ``` -Sessions は自動で次を行います: +Sessions は自動で以下を行います: - 各実行前に会話履歴を取得 -- 各実行後に新規メッセージを保存 +- 各実行後に新しいメッセージを保存 - セッション ID ごとに別々の会話を維持 -詳細は [Sessions のドキュメント](sessions/index.md) を参照してください。 +詳細は [Sessions のドキュメント](sessions/index.md) をご覧ください。 ### サーバー管理の会話 -OpenAI の conversation state 機能に会話状態の管理を任せ、`to_input_list()` や `Sessions` でローカル管理を行わないこともできます。これにより、過去のメッセージをすべて手動で再送せずに会話履歴を保持できます。詳細は [OpenAI Conversation state ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 +`to_input_list()` や `Sessions` でローカルに扱う代わりに、OpenAI の conversation state 機能により サーバー 側で会話状態を管理することもできます。これにより、過去のメッセージをすべて手動で再送しなくても、会話履歴を保持できます。詳しくは [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 -OpenAI はターン間で状態を追跡する 2 つの方法を提供しています: +OpenAI はターン間の状態を追跡する 2 つの方法を提供しています: -#### 1. `conversation_id` を使用 +#### 1. `conversation_id` の使用 -最初に OpenAI Conversations API で会話を作成し、その ID を以後の各呼び出しで再利用します: +まず OpenAI Conversations API を使って会話を作成し、その ID を以降のすべての呼び出しで再利用します: ```python from agents import Agent, Runner @@ -168,9 +168,9 @@ async def main(): # California ``` -#### 2. `previous_response_id` を使用 +#### 2. `previous_response_id` の使用 -もう 1 つの方法は **response chaining** で、各ターンが前のターンのレスポンス ID に明示的にリンクします。 +もう 1 つの方法は **response chaining** で、各ターンを前のターンの response ID に明示的にリンクします。 ```python from agents import Agent, Runner @@ -194,18 +194,18 @@ async def main(): ``` -## 長時間稼働のエージェントと human-in-the-loop +## 長時間実行エージェントと human-in-the-loop -Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop のタスクを含む永続的で長時間稼働のワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了させるデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で確認でき、[こちらのドキュメント](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)も参照してください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop タスクを含む、耐久性のある長時間実行のワークフローを構築できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) をご覧ください。ドキュメントは [こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) にあります。 ## 例外 -SDK は特定の場合に例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです: +SDK は特定の場合に例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです: -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外はここから派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えた場合に送出されます。これは、指定したやり取り回数内にタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成したときに発生します。これには次が含まれます: - - 不正な JSON: 特定の `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: 特定の `output_type` が定義されている場合に特に、ツール呼び出しや直接出力で不正な JSON 構造を返した場合。 + - 予期しないツール関連の失敗: モデルが期待どおりにツールを使用できなかった場合 +- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（この SDK を用いてコードを書く人）が SDK の使用中に誤りを犯したときに送出されます。これは通常、誤ったコード実装、無効な構成、または SDK の API の誤用が原因です。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ、入力 ガードレール または出力 ガードレール の条件が満たされたときに送出されます。入力 ガードレール は処理前に受信メッセージを検査し、出力 ガードレール はエージェントの最終応答を配信前に検査します。 \ No newline at end of file diff --git a/docs/ja/sessions/advanced_sqlite_session.md b/docs/ja/sessions/advanced_sqlite_session.md index 524a39412..97a9bc051 100644 --- a/docs/ja/sessions/advanced_sqlite_session.md +++ b/docs/ja/sessions/advanced_sqlite_session.md @@ -4,15 +4,15 @@ search: --- # 高度な SQLite セッション -`AdvancedSQLiteSession` は、基本の `SQLiteSession` を拡張したもので、会話の分岐、高度な使用状況分析、構造化された会話クエリなど、進んだ会話管理機能を提供します。 +`AdvancedSQLiteSession` は、基本の `SQLiteSession` を強化したもので、会話の分岐、詳細な使用状況分析、構造化された会話クエリなど、高度な会話管理機能を提供します。 ## 機能 - **会話の分岐**: 任意の ユーザー メッセージから代替の会話パスを作成 - **使用状況の追跡**: 各ターンごとの詳細なトークン使用分析と完全な JSON 内訳 - **構造化クエリ**: ターンごとの会話取得、ツール使用統計など -- **ブランチ管理**: 独立したブランチの切り替えと管理 -- **メッセージ構造メタデータ**: メッセージ種別、ツール使用、会話フローを追跡 +- **ブランチ管理**: 独立したブランチ切り替えと管理 +- **メッセージ構造メタデータ**: メッセージ種類、ツール使用状況、会話フローを追跡 ## クイックスタート @@ -84,14 +84,14 @@ session = AdvancedSQLiteSession( ### パラメーター -- `session_id` (str): 会話セッションの一意の識別子 -- `db_path` (str | Path): SQLite データベースファイルへのパス。メモリ内ストレージの場合は `:memory:` がデフォルト -- `create_tables` (bool): 高度なテーブルを自動作成するかどうか。デフォルトは `False` -- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガー +- `session_id` ( str ): 会話セッションの一意の識別子 +- `db_path` ( str | Path ): SQLite データベースファイルへのパス。インメモリ保存の場合は `:memory:` が既定 +- `create_tables` ( bool ): 高度なテーブルを自動作成するかどうか。既定は `False` +- `logger` ( logging.Logger | None ): セッション用のカスタムロガー。既定はモジュールロガー ## 使用状況の追跡 -AdvancedSQLiteSession は、会話の各ターンごとにトークン使用データを保存して詳細な使用状況分析を提供します。**これは各 エージェント 実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。** +AdvancedSQLiteSession は、各会話ターンごとのトークン使用データを保存することで詳細な使用状況分析を提供します。**これは、各 エージェント 実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。** ### 使用データの保存 @@ -137,7 +137,7 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2) ## 会話の分岐 -AdvancedSQLiteSession の重要な機能の 1 つは、任意の ユーザー メッセージから会話ブランチを作成し、代替の会話パスを探索できることです。 +AdvancedSQLiteSession の主要機能の 1 つは、任意の ユーザー メッセージから会話のブランチを作成し、代替の会話パスを探索できることです。 ### ブランチの作成 @@ -245,17 +245,17 @@ for turn in matching_turns: ### メッセージ構造 -セッションは以下を含むメッセージ構造を自動的に追跡します: +セッションは次の内容を含むメッセージ構造を自動的に追跡します。 -- メッセージ種別 (user、assistant、tool_call など) +- メッセージ種類（user, assistant, tool_call など） - ツール呼び出しのツール名 - ターン番号とシーケンス番号 -- ブランチ関連付け +- ブランチの関連付け - タイムスタンプ ## データベーススキーマ -AdvancedSQLiteSession は、基本の SQLite スキーマを拡張し、2 つの追加テーブルを提供します。 +AdvancedSQLiteSession は、基本の SQLite スキーマを 2 つの追加テーブルで拡張します。 ### message_structure テーブル @@ -300,7 +300,8 @@ CREATE TABLE turn_usage ( すべての機能を包括的に示す [完全なコード例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py) をご覧ください。 + ## API リファレンス - [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - メインクラス -- [`Session`][agents.memory.session.Session] - ベースのセッションプロトコル \ No newline at end of file +- [`Session`][agents.memory.session.Session] - ベースセッションプロトコル \ No newline at end of file diff --git a/docs/ja/sessions/encrypted_session.md b/docs/ja/sessions/encrypted_session.md index 72b9622a9..85326b7d6 100644 --- a/docs/ja/sessions/encrypted_session.md +++ b/docs/ja/sessions/encrypted_session.md @@ -4,18 +4,18 @@ search: --- # 暗号化セッション -`EncryptedSession` は、任意のセッション実装に対して透過的な暗号化を提供し、自動的に古いアイテムの有効期限切れを処理して会話データを保護します。 +`EncryptedSession` は、あらゆるセッション実装に対して透過的な暗号化を提供し、自動的に古い項目を期限切れにして会話データを保護します。 ## 機能 - **透過的な暗号化**: 任意のセッションを Fernet 暗号化でラップします -- **セッションごとの鍵**: HKDF による鍵導出でセッションごとに一意の暗号鍵を使用します -- **自動有効期限**: TTL が切れた古いアイテムは静かにスキップされます -- **ドロップイン置き換え**: 既存の任意のセッション実装で動作します +- **セッションごとの鍵**: 一意のセッションごとに HKDF による鍵導出を使用します +- **自動有効期限**: TTL が切れた古い項目はサイレントにスキップされます +- **ドロップイン置換**: 既存の任意のセッション実装で機能します ## インストール -暗号化セッションには `encrypt` 追加機能が必要です: +暗号化セッションには `encrypt` の extra が必要です: ```bash pip install openai-agents[encrypt] @@ -57,7 +57,7 @@ if __name__ == "__main__": ### 暗号鍵 -暗号鍵は Fernet キーでも、任意の文字列でも使用できます: +暗号鍵は Fernet キーまたは任意の文字列を使用できます: ```python from agents.extensions.memory import EncryptedSession @@ -79,9 +79,9 @@ session = EncryptedSession( ) ``` -### TTL（有効期間） +### TTL (Time To Live) -暗号化されたアイテムが有効な期間を設定します: +暗号化された項目が有効な期間を設定します: ```python # Items expire after 1 hour @@ -101,7 +101,7 @@ session = EncryptedSession( ) ``` -## さまざまなセッションタイプでの使用 +## 異なるセッションタイプでの使用 ### SQLite セッションでの使用 @@ -142,28 +142,28 @@ session = EncryptedSession( `EncryptedSession` を `AdvancedSQLiteSession` のような高度なセッション実装と併用する場合、次の点に注意してください: - - メッセージ内容が暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に機能しません - - コンテンツベースの検索は暗号化データ上で動作するため、その有効性が制限されます + - メッセージ内容が暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に動作しません + - コンテンツベースの検索は暗号化データ上で実行されるため、効果が制限されます ## 鍵導出 -EncryptedSession は HKDF（HMAC-based Key Derivation Function）を使用して、セッションごとに一意の暗号鍵を導出します: +EncryptedSession は HKDF (HMAC ベースの Key Derivation Function) を使用して、セッションごとに一意の暗号鍵を導出します: -- **マスターキー**: 提供された暗号鍵 +- **マスターキー**: 提供した暗号鍵 - **セッションソルト**: セッション ID -- **Info 文字列**: `"agents.session-store.hkdf.v1"` +- **情報文字列**: `"agents.session-store.hkdf.v1"` - **出力**: 32 バイトの Fernet キー -これにより次のことが保証されます: +これにより、次のことが保証されます: - 各セッションには一意の暗号鍵があります -- マスターキーなしに鍵を導出することはできません -- セッション間でデータを復号することはできません +- マスターキーなしでは鍵を導出できません +- 異なるセッション間でセッションデータを復号できません ## 自動有効期限 -アイテムが TTL を超えた場合、取得時に自動的にスキップされます: +項目が TTL を超えた場合、取得時に自動的にスキップされます: ```python # Items older than TTL are silently ignored diff --git a/docs/ja/sessions/index.md b/docs/ja/sessions/index.md index 41f488d21..da0994892 100644 --- a/docs/ja/sessions/index.md +++ b/docs/ja/sessions/index.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 +Agents SDK は、複数の エージェント 実行にわたって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で手動で `.to_input_list()` を扱う必要をなくします。 -セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを保持できるようにします。これは、エージェントに過去のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしで エージェント がコンテキストを維持できるようにします。これは、エージェント に前回のやり取りを記憶してほしいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -51,17 +51,17 @@ 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 @@ -88,7 +88,7 @@ await session.clear_session() ### 修正のための pop_item の使用 -`pop_item` メソッドは、会話の最後のアイテムを取り消したり修正したりしたい場合に特に有用です: +`pop_item` メソッドは、会話の最後のアイテムを取り消したり変更したりしたい場合に特に便利です: ```python from agents import Agent, Runner, SQLiteSession @@ -119,11 +119,11 @@ print(f"Agent: {result.final_output}") ## セッションの種類 -SDK は、用途に応じて複数のセッション実装を提供します: +SDK は、用途に応じた複数のセッション実装を提供します: ### OpenAI Conversations API セッション -`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。 +`OpenAIConversationsSession` を通じて [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。 ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -159,7 +159,7 @@ print(result.final_output) # "California" ### SQLite セッション -デフォルトの軽量な SQLite ベースのセッション実装です: +デフォルトの軽量な SQLite を使ったセッション実装です: ```python from agents import SQLiteSession @@ -180,7 +180,7 @@ result = await Runner.run( ### SQLAlchemy セッション -SQLAlchemy がサポートする任意のデータベースを利用できる本番運用向けセッションです: +任意の SQLAlchemy がサポートするデータベースを利用できる本番運用向けセッションです: ```python from agents.extensions.memory import SQLAlchemySession @@ -204,7 +204,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ### 高度な SQLite セッション -会話の分岐、使用状況分析、構造化クエリを備えた強化版 SQLite セッションです: +会話の分岐、使用状況分析、構造化クエリを備えた拡張 SQLite セッションです: ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -263,20 +263,19 @@ result = await Runner.run(agent, "Hello", session=session) 会話の整理に役立つ意味のあるセッション ID を使用します: -- User ベース: `"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 サポートデータベースを持つ本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 -- 本番のクラウドネイティブ展開には Dapr ステートストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用。組み込みのテレメトリー、トレーシング、データ分離を備えた -30+ のデータベースバックエンドをサポート +- 既存の SQLAlchemy がサポートするデータベースを用いた本番環境には SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用 +- クラウドネイティブな本番デプロイには Dapr ステートストアのセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用。組み込みのテレメトリ、トレーシング、データ分離を備えた 30+ のデータベースバックエンドをサポート - 履歴を OpenAI Conversations API に保存したい場合は OpenAI ホスト型ストレージ（`OpenAIConversationsSession()`）を使用 -- 任意のセッションを透過的な暗号化と TTL ベースの有効期限でラップするには暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用 -- より高度なユースケース向けに、他の本番システム（Redis、Django など）用のカスタムセッションバックエンドの実装を検討 +- 透過的な暗号化と TTL ベースの有効期限で任意のセッションをラップするには暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用 +- より高度なユースケースのために、他の本番システム（Redis、Django など）向けのカスタムセッションバックエンドの実装を検討 ### 複数セッション @@ -324,7 +323,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリがどのように機能するかを示す完全な例です: +セッションメモリがどのように動作するかを示す完全な例です: ```python import asyncio @@ -431,6 +430,16 @@ result = await Runner.run( ) ``` +## コミュニティのセッション実装 + +コミュニティによって、追加のセッション実装が開発されています: + +| パッケージ | 説明 | +|---------|-------------| +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django がサポートするデータベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション | + +セッション実装を作成された場合は、ぜひドキュメントの PR を送ってここに追加してください。 + ## API リファレンス 詳細な API ドキュメントは以下を参照してください: @@ -440,5 +449,5 @@ result = await Runner.run( - [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本的な SQLite 実装 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr ステートストア実装 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた強化版 SQLite +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite - [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向け暗号化ラッパー \ No newline at end of file diff --git a/docs/ja/sessions/sqlalchemy_session.md b/docs/ja/sessions/sqlalchemy_session.md index e0d09edfb..f72b3a8ed 100644 --- a/docs/ja/sessions/sqlalchemy_session.md +++ b/docs/ja/sessions/sqlalchemy_session.md @@ -4,11 +4,11 @@ search: --- # SQLAlchemy セッション -`SQLAlchemySession` は SQLAlchemy を使用して本番運用向けのセッション実装を提供し、セッションストレージとして SQLAlchemy がサポートする任意のデータベース（ PostgreSQL、MySQL、SQLite など）を使用できます。 +`SQLAlchemySession` は SQLAlchemy を使用して本番運用向けのセッション実装を提供し、SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）をセッションの保存に使用できます。 ## インストール -SQLAlchemy セッションには `sqlalchemy` の extra が必要です: +SQLAlchemy セッションには `sqlalchemy` エクストラが必要です: ```bash pip install openai-agents[sqlalchemy] @@ -44,7 +44,7 @@ if __name__ == "__main__": ### 既存のエンジンの使用 -既存の SQLAlchemy エンジンを持つアプリケーション向け: +既存の SQLAlchemy エンジンを使用するアプリケーション向け: ```python import asyncio @@ -77,4 +77,4 @@ if __name__ == "__main__": ## API リファレンス - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - メインクラス -- [`Session`][agents.memory.session.Session] - ベースセッションプロトコル \ No newline at end of file +- [`Session`][agents.memory.session.Session] - セッションの基底プロトコル \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index fb1475591..2dfc79908 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 response イベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。生成され次第、ユーザーへ応答メッセージをストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式であり、各イベントには（`response.created`、`response.output_text.delta` などの）type と data が含まれます。これらのイベントは、生成され次第ユーザーに応答メッセージをストリーミングしたい場合に便利です。 -たとえば、これは LLM が生成したテキストをトークンごとに出力します。 +たとえば、次のコードは LLM が生成するテキストをトークン単位で出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 実行アイテムイベントとエージェントイベント +## Run item イベントと エージェント イベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より上位レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」といったレベルで進捗を通知できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果）に更新を通知します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークンではなく「メッセージが生成された」、「ツールが実行された」などのレベルで進行状況をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更された際（たとえばハンドオフの結果として）に更新を提供します。 -たとえば、これは raw イベントを無視してユーザーに更新をストリーミングします。 +たとえば、次のコードは raw イベントを無視し、ユーザーに更新をストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index a517c01b8..9bc2bfdcb 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行するための手段です。データ取得、コード実行、外部 API 呼び出し、さらにはコンピュータ操作 まで可能にします。Agent SDK には 3 つの種類のツールがあります: +ツールはエージェントにアクションを実行させます。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 つのツールのクラスがあります。 -- Hosted ツール: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を Hosted ツールとして提供します。 -- Function calling: 任意の Python 関数 をツールとして利用できます。 -- ツールとしてのエージェント: エージェントをツールとして利用でき、ハンドオフ なしに他の エージェント を呼び出せます。 +- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 +- Function calling: 任意の Python 関数をツールとして使えるようにします。 +- ツールとしてのエージェント: エージェントをツールとして使用でき、ハンドオフなしでエージェントが他のエージェントを呼び出せます。 ## ホスト型ツール -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 から取得します（任意で説明を指定可能） -- 関数入力のスキーマは関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り関数の docstring から取得されます +- ツール名は Python 関数名になります（または名前を指定できます） +- ツールの説明は関数の docstring から取得します（または説明を指定できます） +- 関数入力のスキーマは関数の引数から自動で作成されます +- 各入力の説明は、無効化しない限り、関数の docstring から取得されます -関数シグネチャの抽出には Python の `inspect` モジュールを使用し、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/)、スキーマ生成には `pydantic` を使用します。 +Python の `inspect` モジュールで関数シグネチャを抽出し、[`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、スキーマ作成には `pydantic` を使用します。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型 を使用でき、同期/非同期のどちらにも対応します。 -2. docstring がある場合、その内容を説明文および各引数の説明として使用します。 -3. 関数は任意で `context`（最初の引数である必要があります）を受け取れます。ツール名や説明、docstring スタイルなどのオーバーライドも設定できます。 -4. デコレートした関数を tools のリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期/非同期いずれでも構いません。 +2. docstring があれば、説明と引数の説明に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数でなければなりません）。ツール名、説明、docstring スタイルなどの上書きも設定できます。 +4. デコレートした関数をツールのリストに渡せます。 -??? note "出力を表示" +??? note "出力を見るには展開" ``` fetch_weather @@ -179,20 +179,20 @@ for tool in agent.tools: ### 関数ツールからの画像やファイルの返却 -テキスト出力に加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返せます。次のいずれかを返してください: +テキスト出力に加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返すこともできます。そのためには、次のいずれかを返します。 -- 画像: [`ToolOutputImage`][agents.tool.ToolOutputImage]（TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict] でも可） -- ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict] でも可） -- テキスト: 文字列または文字列化可能なオブジェクト、あるいは [`ToolOutputText`][agents.tool.ToolOutputText]（TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict] でも可） +- 画像: [`ToolOutputImage`][agents.tool.ToolOutputImage]（または TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） +- ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（または TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） +- テキスト: 文字列または文字列化可能オブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） ### カスタム関数ツール -Python 関数をツールとして使いたくない場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。以下を指定する必要があります: +Python 関数をツールとして使いたくない場合もあります。必要に応じて直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。以下を指定する必要があります。 -- `name` -- `description` -- 引数の JSON スキーマである `params_json_schema` -- [`ToolContext`][agents.tool_context.ToolContext] と引数（JSON 文字列）を受け取り、ツールの出力を文字列で返す非同期関数 `on_invoke_tool` +- `name` +- `description` +- `params_json_schema`（引数の JSON スキーマ） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツールの出力を文字列で返す非同期関数） ```python from typing import Any @@ -227,16 +227,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマ抽出のために関数シグネチャを自動解析し、ツールおよび個々の引数の説明抽出のために docstring を解析します。補足: +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。補足事項は次のとおりです。 -1. シグネチャ解析は `inspect` モジュールで行います。型アノテーションから引数の型を把握し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など多くの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますがベストエフォートであり、`function_tool` 呼び出し時に明示的に設定できます。`use_docstring_info` を `False` に設定して 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 @@ -277,7 +277,7 @@ async def main(): ### ツール化したエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェント を簡単にツール化するためのユーティリティです。ただしすべての設定をサポートしているわけではありません。例えば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: +`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための簡便メソッドです。ただし、すべての設定をサポートしているわけではありません。たとえば、`max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 ```python @function_tool @@ -298,13 +298,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: @@ -323,9 +323,9 @@ json_tool = data_agent.as_tool( ) ``` -### ツールの条件付き有効化 +### 条件付きのツール有効化 -実行時に `is_enabled` パラメーター を使って エージェント ツールを条件付きで有効化/無効化できます。これにより、コンテキスト、ユーザー の設定、実行時条件に応じて LLM に提供するツールを動的に絞り込めます。 +`is_enabled` パラメーターを使用して、実行時にエージェントのツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザーの好み、実行時条件に基づいて LLM に利用可能なツールを動的にフィルタリングできます。 ```python import asyncio @@ -380,26 +380,26 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーター は次を受け付けます: +`is_enabled` パラメーターは次を受け付けます。 -- **ブーリアン値**: `True`（常に有効）または `False`（常に無効） -- **呼び出し可能関数**: `(context, agent)` を受け取り、ブール値を返す関数 -- **非同期関数**: 複雑な条件ロジック用の async 関数 +- **ブール値** : `True`（常に有効）または `False`（常に無効） +- **呼び出し可能関数** : `(context, agent)` を取り、真偽値を返す関数 +- **非同期関数** : 複雑な条件ロジック向けの非同期関数 -無効化されたツールは実行時に LLM から完全に隠されます。次の用途に有用です: +無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です。 -- ユーザー 権限に基づく機能のゲーティング -- 環境ごとのツール提供可否（dev vs prod） -- 異なるツール構成の A/B テスト -- 実行時状態に基づく動的ツールフィルタリング +- ユーザー権限に基づく機能ゲーティング +- 環境別のツール可用性（開発 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 diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 75be28490..9908cf9ea 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録（ LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、カスタムイベントまで）を収集します。 [Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングがあり、エージェント実行中に発生するイベントの包括的な記録（ LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベント）を収集します。[Traces ダッシュボード](https://platform.openai.com/traces)を使用して、開発中や本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。トレーシングを無効にする方法は 2 つあります。 + トレーシングはデフォルトで有効です。トレーシングを無効化する方法は 2 つあります: - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化できます - 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してトレーシングをグローバルに無効化できます + 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します - ***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーで運用する組織では、トレーシングは利用できません。*** +***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（スパン）** は開始時刻と終了時刻を持つ操作を表します。スパンには次のものがあります: + - `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 の生成に関する情報を含みます。 + - このスパンの親スパン（ある場合）を指す `parent_id` + - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます。 -## 既定のトレーシング +## デフォルトのトレーシング -既定では、 SDK は次をトレースします: +デフォルトでは、 SDK は次をトレースします: -- 全体の `Runner.{run, run_sync, run_streamed}()` は `trace()` でラップされます -- エージェントが実行されるたびに `agent_span()` でラップされます +- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。 +- エージェントが実行されるたびに、`agent_span()` でラップされます - LLM 生成は `generation_span()` でラップされます -- 関数ツール呼び出しはそれぞれ `function_span()` でラップされます +- 関数ツールの呼び出しはそれぞれ `function_span()` でラップされます - ガードレールは `guardrail_span()` でラップされます - ハンドオフは `handoff_span()` でラップされます - 音声入力（音声認識）は `transcription_span()` でラップされます -- 音声出力（音声合成）は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_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()` への複数回の呼び出しを 1 つのトレースの一部にしたい場合があります。その場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -68,42 +68,42 @@ async def main(): ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。実行方法は 2 つあります: +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: -1. 【推奨】トレースをコンテキストマネージャとして使用します（例: `with trace(...) as my_trace`）。これにより適切なタイミングでトレースが自動的に開始・終了します。 +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` には、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。`BackendSpanExporter` は OpenAI のバックエンドにスパンとトレースをバッチでエクスポートします。 +- `TraceProvider` を、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成します。`BackendSpanExporter` はスパンとトレースを OpenAI のバックエンドにバッチでエクスポートします。 -既定のセットアップをカスタマイズして、別のバックエンドへの送信や追加のバックエンドへの送信、エクスポータの動作変更を行うには、次の 2 つの方法があります。 +このデフォルト構成をカスタマイズして、別の送信先や追加のバックエンドにトレースを送る、またはエクスポーターの動作を変更するには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備でき次第受け取る、**追加の** トレースプロセッサーを追加できます。これにより、OpenAI のバックエンドへの送信に加えて独自の処理を行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、既定のプロセッサーを独自のトレースプロセッサーで**置き換え**できます。OpenAI のバックエンドにトレースを送信するには、その役割を担う `TracingProcessor` を含める必要があります。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、トレースやスパンが準備できたタイミングで受け取る追加入力の **トレースプロセッサー** を追加できます。これにより、 OpenAI のバックエンドにトレースを送ることに加えて独自の処理が可能になります。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトのプロセッサーを独自のトレースプロセッサーに **置き換え** られます。これは、送信を行う `TracingProcessor` を含めない限り、トレースが OpenAI のバックエンドに送信されないことを意味します。 ## 非 OpenAI モデルでのトレーシング -OpenAI 以外のモデルでも OpenAI API キーを使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 +OpenAI の API キーを非 OpenAI モデルで使用して、トレーシングを無効にすることなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。 ```python import os @@ -124,8 +124,8 @@ agent = Agent( ) ``` -## 注記 -- Openai Traces ダッシュボードで無料のトレースを表示します。 +## Notes +- 無料のトレースは Openai Traces ダッシュボードで確認できます。 ## 外部トレーシングプロセッサー一覧 diff --git a/docs/ja/usage.md b/docs/ja/usage.md index a45385ce7..62208b925 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -4,22 +4,22 @@ search: --- # 使用状況 -Agents SDK は、各実行ごとにトークン使用状況を自動で追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。 +Agents SDK は、すべての実行におけるトークン使用状況を自動的に追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。 -## 追跡対象 +## 追跡項目 - **requests**: 実行された LLM API 呼び出し回数 - **input_tokens**: 送信された入力トークン合計 - **output_tokens**: 受信した出力トークン合計 -- **total_tokens**: 入力 + 出力 -- **request_usage_entries**: リクエストごとの使用状況内訳の一覧 +- **total_tokens**: input + output +- **request_usage_entries**: リクエストごとの使用状況の内訳リスト - **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?") @@ -31,11 +31,11 @@ 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` に反映されるようにします。 +LiteLLM プロバイダーはデフォルトでは使用状況メトリクスを報告しません。[`LitellmModel`](models/litellm.md) を使用する場合、エージェントに `ModelSettings(include_usage=True)` を渡すと、LiteLLM のレスポンスが `result.context_wrapper.usage` に反映されます。 ```python from agents import Agent, ModelSettings, Runner @@ -53,7 +53,7 @@ print(result.context_wrapper.usage.total_tokens) ## リクエスト単位の使用状況トラッキング -SDK は、各 API リクエストの使用状況を `request_usage_entries` に自動で記録します。詳細なコスト計算やコンテキストウィンドウ消費の監視に役立ちます。 +SDK は `request_usage_entries` に各 API リクエストの使用状況を自動追跡します。詳細なコスト計算やコンテキストウィンドウ消費の監視に便利です。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -62,9 +62,9 @@ for request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## セッションでの使用状況の参照 +## セッションでの使用状況の取得 -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に特有の使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキスト用の会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,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): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは次を参照してください: +詳細な API ドキュメントは以下をご覧ください。 -- [`Usage`][agents.usage.Usage] - 使用状況トラッキングのデータ構造 -- [`RequestUsage`][agents.usage.RequestUsage] - リクエストごとの使用状況の詳細 +- [`Usage`][agents.usage.Usage] - 使用状況追跡のデータ構造 +- [`RequestUsage`][agents.usage.RequestUsage] - リクエスト単位の使用状況の詳細 - [`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 f67dd0750..08337c43e 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 サーバー** は灰色のボックスで表されます。 - **ツール** は緑色の楕円で表されます。 -- **ハンドオフ** は、あるエージェントから別のエージェントへの向き付きエッジです。 +- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -69,36 +69,36 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -これは、 **トリアージ エージェント** と、そのサブエージェントやツールへの接続の構造を視覚的に表すグラフを生成します。 +これは、**トリアージ エージェント** とサブエージェントやツールへの接続の構造を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されたグラフには次が含まれます: +生成されるグラフには次が含まれます: -- 入口を示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた **長方形** で表されるエージェント。 -- 緑で塗りつぶされた **楕円** で表されるツール。 -- 灰色で塗りつぶされた **長方形** で表される MCP サーバー。 -- 相互作用を示す向き付きエッジ: +- エントリポイントを示す **開始ノード**（`__start__`）。 +- 黄色で塗りつぶされた **長方形** のエージェント。 +- 緑色で塗りつぶされた **楕円** のツール。 +- 灰色で塗りつぶされた **長方形** の MCP サーバー。 +- 相互作用を示す有向エッジ: - エージェント間のハンドオフには **実線の矢印**。 - ツール呼び出しには **点線の矢印**。 - MCP サーバー呼び出しには **破線の矢印**。 -- 実行終了位置を示す **終了ノード** (`__end__`)。 +- 実行の終了箇所を示す **終了ノード**（`__end__`）。 -**注意:** MCP サーバーは、最近の `agents` パッケージのバージョンでレンダリングされます（ **v0.2.8** で確認済み）。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**注:** MCP サーバーは最近の `agents` パッケージのバージョンで描画されます（**v0.2.8** で確認済み）。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ ### グラフの表示 -既定では、`draw_graph` はグラフをインライン表示します。別ウィンドウでグラフを表示するには、次のように記述します: +デフォルトでは、`draw_graph` はグラフをインラインで表示します。別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -既定では、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: +デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index fe53cf08b..e5be0c545 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,28 +34,28 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際、次の項目を設定できます: +パイプラインを作成する際に、次の項目を設定できます。 1. 新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] の各モデル -3. 次のような事項を設定できる [`config`][agents.voice.pipeline_config.VoicePipelineConfig] +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル +3. 次のような項目を設定できる [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - モデル名をモデルにマッピングできるモデルプロバイダー - - トレーシング（トレーシングを無効化するか、音声ファイルをアップロードするか、ワークフロー名、トレース ID など） - - TTS および STT モデルの設定（プロンプト、言語、使用するデータ型 など） + - トレーシング（トレーシングの無効化、音声ファイルのアップロード有無、ワークフロー名、トレース ID など） + - TTS と STT モデルの設定（プロンプト、言語、使用するデータ型など） ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます: +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声をすでに文字起こし済みで、その結果に対して出力を生成したい場合に使います。これは、話者が話し終えたタイミングを検知する必要がないケース、たとえば事前録音の音声や、ユーザーが話し終えるタイミングが明確なプッシュ・トゥ・トークのアプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングの検知が必要な場合に使います。検出された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検出」によって適切なタイミングで自動的にエージェントのワークフローを実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声の文字起こしがあり、その結果だけを生成したい場合に使用します。これは、話者が話し終わったタイミングの検知が不要なケース（例: 事前録音の音声、発話終了が明確なプッシュ・トゥ・トークのアプリ）で有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングの検知が必要な場合に使用します。検出した音声チャンクを逐次プッシュでき、ボイスパイプラインは「activity detection（音声活動検知）」と呼ばれるプロセスにより、適切なタイミングでエージェントのワークフローを自動実行します。 ## 結果 -音声パイプラインの実行結果は [`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] +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 02d29eb8a..fd7ba0ff8 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 でエージェントを作成したことがあれば馴染みがあるはずです。ここでは 2 つのエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使い、シンプルな音声パイプラインをセットアップします。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインをセットアップします。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## まとめて実行 +## 統合 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -このサンプルを実行すると、エージェントがあなたに話しかけます。自分で エージェント と会話できるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) にある例をご覧ください。 \ No newline at end of file +この例を実行すると、エージェント があなたに話しかけます。自分でエージェント に話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 1ea04a1ef..76d556192 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェント がトレーシングされる方法](../tracing.md)と同様に、音声パイプラインも自動でトレーシングされます。 +[エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動でトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントを参照できますが、追加で [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を使ってパイプラインのトレーシングを設定できます。 +基本的なトレーシング情報は上記のドキュメントをご参照ください。加えて、パイプラインのトレーシングは [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] で設定できます。 -トレーシングに関連する主なフィールドは次のとおりです。 +トレーシングに関する主なフィールドは次のとおりです。 -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしのような、潜在的に機微なデータをトレースに含めるかどうかを制御します。これは音声パイプラインに特化した設定で、Workflow の内部で行われる処理には適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 音声データをトレースに含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースをリンクできる、トレースの `group_id` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。既定ではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに音声書き起こしなどの機微なデータを含めるかどうかを制御します。これは音声パイプライン専用で、ワークフロー内部で行われる処理には適用されません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるために使用できる、トレースの `group_id` です。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータです。 \ No newline at end of file diff --git a/docs/ko/agents.md b/docs/ko/agents.md index 27eca5e90..da9c342df 100644 --- a/docs/ko/agents.md +++ b/docs/ko/agents.md @@ -4,16 +4,16 @@ search: --- # 에이전트 -에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions 와 tools 로 구성된 대규모 언어 모델(LLM)입니다. +에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions 와 도구로 구성된 대규모 언어 모델 (LLM) 입니다. ## 기본 구성 -에이전트에서 가장 일반적으로 설정하는 속성은 다음과 같습니다: +에이전트를 설정할 때 가장 일반적으로 구성하는 속성은 다음과 같습니다: - `name`: 에이전트를 식별하는 필수 문자열 - `instructions`: 개발자 메시지 또는 시스템 프롬프트라고도 함 - `model`: 사용할 LLM 및 temperature, top_p 등 모델 튜닝 매개변수를 설정하는 선택적 `model_settings` -- `tools`: 에이전트가 작업을 수행하기 위해 사용할 수 있는 도구들 +- `tools`: 에이전트가 작업을 수행하기 위해 사용할 수 있는 도구 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## 컨텍스트 -에이전트는 `context` 타입에 대해 제네릭합니다. 컨텍스트는 의존성 주입 도구로, 사용자가 생성하여 `Runner.run()` 에 전달하는 객체입니다. 이는 모든 에이전트, tool, handoff 등에 전달되며, 에이전트 실행을 위한 의존성과 상태를 담는 가방 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다. +에이전트는 `context` 타입에 대해 제네릭합니다. 컨텍스트는 의존성 주입 도구로, 사용자가 생성하여 `Runner.run()` 에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되어 에이전트 실행을 위한 의존성과 상태를 저장하는 바구니 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다. ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 출력 타입 -기본적으로, 에이전트는 일반 텍스트(즉, `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 로 감쌀 수 있는 모든 타입(데이터클래스, 리스트, TypedDict 등)을 지원합니다. +기본적으로 에이전트는 일반 텍스트(즉, `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 로 래핑할 수 있는 모든 타입(데이터클래스, 리스트, 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) 를 사용하도록 지시합니다. ## 멀티 에이전트 시스템 설계 패턴 -멀티 에이전트 시스템을 설계하는 방법은 다양하지만, 일반적으로 다음 두 가지 널리 적용 가능한 패턴이 있습니다: +멀티 에이전트 시스템을 설계하는 방법은 다양하지만, 일반적으로 두 가지 널리 적용 가능한 패턴이 있습니다: -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 를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 인수로 받고, 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수 모두 허용됩니다. +대부분의 경우, 에이전트를 생성할 때 instructions 를 제공할 수 있습니다. 그러나 함수로 동적 instructions 를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 입력으로 받아 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수 모두 허용됩니다. ```python def dynamic_instructions( @@ -153,15 +153,15 @@ agent = Agent[UserContext]( ## 라이프사이클 이벤트(hooks) -때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어, 이벤트를 로깅하거나 특정 이벤트 발생 시 데이터를 미리 가져오고 싶을 수 있습니다. `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`)을 설정: LLM 이 해당 특정 도구를 사용하도록 요구 +2. `required`: LLM 이 도구를 반드시 사용하도록 강제(어떤 도구를 사용할지는 지능적으로 결정) +3. `none`: LLM 이 도구를 사용하지 않도록 강제 +4. 특정 문자열(예: `my_tool`)을 설정하여 해당 도구를 반드시 사용하도록 강제 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -205,8 +205,8 @@ agent = Agent( `Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력 처리 방식을 제어합니다: -- `"run_llm_again"`: 기본값. 도구를 실행하고, LLM 이 그 결과를 처리하여 최종 응답을 생성 -- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력을 추가적인 LLM 처리 없이 최종 응답으로 사용 +- `"run_llm_again"`: 기본값. 도구를 실행하고, LLM 이 결과를 처리해 최종 응답을 생성 +- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력을 추가 LLM 처리 없이 최종 응답으로 사용 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -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` 때문에 LLM 이 다시 도구 호출을 생성하는 과정이 반복되면서 발생합니다. \ No newline at end of file diff --git a/docs/ko/config.md b/docs/ko/config.md index 2710c05e7..41904ad21 100644 --- a/docs/ko/config.md +++ b/docs/ko/config.md @@ -6,7 +6,7 @@ search: ## API 키와 클라이언트 -기본적으로 SDK는 가져오는 즉시 LLM 요청과 트레이싱을 위해 `OPENAI_API_KEY` 환경 변수를 찾습니다. 앱이 시작되기 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다. +기본적으로 SDK는 가져오자마자 LLM 요청과 트레이싱을 위해 `OPENAI_API_KEY` 환경 변수를 찾습니다. 앱 시작 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다. ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수 또는 위에서 설정한 기본 키에서 API 키를 사용해 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다. +또는 사용할 OpenAI 클라이언트를 직접 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용하여 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다. ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -마지막으로, 사용되는 OpenAI API를 커스터마이즈할 수도 있습니다. 기본적으로 OpenAI Responses API를 사용합니다. [set_default_openai_api()][agents.set_default_openai_api] 함수를 사용해 Chat Completions API를 사용하도록 재정의할 수 있습니다. +마지막으로, 사용되는 OpenAI API를 커스터마이즈할 수도 있습니다. 기본값은 OpenAI Responses API입니다. [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 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용해 트레이싱에 사용할 API 키를 별도로 설정할 수 있습니다. +트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. 트레이싱에 사용할 API 키를 별도로 지정하려면 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용하세요. ```python from agents import set_tracing_export_api_key @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## 디버그 로깅 -SDK에는 핸들러가 설정되지 않은 두 개의 Python 로거가 있습니다. 기본적으로 이는 경고와 오류는 `stdout`으로 전송되지만, 다른 로그는 억제됨을 의미합니다. +SDK에는 핸들러가 설정되지 않은 두 개의 Python 로거가 있습니다. 기본적으로 이는 경고와 오류가 `stdout`으로 전송되고, 그 외 로그는 억제됨을 의미합니다. -자세한 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요. +상세 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요. ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -또는 핸들러, 필터, 포매터 등을 추가해 로그를 커스터마이즈할 수 있습니다. 자세한 내용은 [Python logging 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. +또는 핸들러, 필터, 포매터 등을 추가하여 로그를 커스터마이즈할 수 있습니다. 더 자세한 내용은 [Python logging guide](https://docs.python.org/3/howto/logging.html)를 참고하세요. ```python import logging @@ -83,7 +83,7 @@ logger.addHandler(logging.StreamHandler()) ### 로그의 민감한 데이터 -일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. 이러한 데이터가 로그에 기록되지 않도록 하려면 다음 환경 변수를 설정하세요. +일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. 이러한 데이터의 로깅을 비활성화하려면 다음 환경 변수를 설정하세요. LLM 입력과 출력을 로깅하지 않으려면: diff --git a/docs/ko/context.md b/docs/ko/context.md index faaf5231e..60730f056 100644 --- a/docs/ko/context.md +++ b/docs/ko/context.md @@ -4,30 +4,30 @@ search: --- # 컨텍스트 관리 -컨텍스트는 여러 의미로 쓰입니다. 여기에서 중요한 컨텍스트는 두 가지 부류가 있습니다: +컨텍스트는 다의어입니다. 여기서 중요하게 볼 수 있는 컨텍스트는 두 가지 클래스가 있습니다: -1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수 실행 시, `on_handoff` 같은 콜백 중, 라이프사이클 훅 등에서 필요할 수 있는 데이터와 의존성 -2. LLM 에 제공되는 컨텍스트: LLM 이 응답을 생성할 때 볼 수 있는 데이터 +1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수 실행 시, `on_handoff` 같은 콜백 동안, 라이프사이클 훅 등에서 필요할 수 있는 데이터와 의존성 +2. LLM이 사용할 수 있는 컨텍스트: LLM이 응답을 생성할 때 볼 수 있는 데이터 ## 로컬 컨텍스트 -이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 동작 방식은 다음과 같습니다: +이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 프로퍼티로 표현됩니다. 동작 방식은 다음과 같습니다: -1. 원하는 어떤 Python 객체든 만듭니다. 보통 dataclass 나 Pydantic 객체를 사용합니다 -2. 해당 객체를 다양한 run 메서드에 전달합니다 (예: `Runner.run(..., **context=whatever**)`) -3. 모든 도구 호출, 라이프사이클 훅 등에는 래퍼 객체 `RunContextWrapper[T]` 가 전달되며, 여기서 `T` 는 컨텍스트 객체 타입을 나타내며 `wrapper.context` 로 접근할 수 있습니다 +1. 원하는 어떤 Python 객체든 생성합니다. 일반적으로 dataclass 또는 Pydantic 객체를 사용합니다 +2. 해당 객체를 다양한 run 메서드에 전달합니다(예: `Runner.run(..., **context=whatever**))`) +3. 모든 도구 호출, 라이프사이클 훅 등에는 래퍼 객체 `RunContextWrapper[T]`가 전달됩니다. 여기서 `T`는 컨텍스트 객체 타입을 나타내며 `wrapper.context`로 접근할 수 있습니다 -가장 중요한 점: 하나의 에이전트 실행에서 해당 에이전트의 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 _타입_ 의 컨텍스트를 사용해야 합니다. +가장 중요한 점: 특정 에이전트 실행에 대해 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 컨텍스트의 타입을 사용해야 합니다. 컨텍스트는 다음과 같은 용도로 사용할 수 있습니다: -- 실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 같은 것 또는 사용자에 대한 기타 정보) +- 실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 같은 값 또는 사용자에 대한 기타 정보) - 의존성(예: 로거 객체, 데이터 페처 등) - 헬퍼 함수 -!!! danger "Note" +!!! danger "주의" - 컨텍스트 객체는 LLM 에게 **전송되지 않습니다**. 완전히 로컬 객체이며, 읽고 쓰거나 메서드를 호출할 수 있습니다. + 컨텍스트 객체는 LLM에 **전송되지 않습니다**. 오로지 로컬 객체이며 읽고, 쓰고, 메서드를 호출할 수 있습니다. ```python import asyncio @@ -66,18 +66,18 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass 를 사용했지만, 어떤 타입이든 사용할 수 있습니다 -2. 이것은 도구입니다. `RunContextWrapper[UserInfo]` 를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다 -3. 타입체커가 오류를 잡을 수 있도록 에이전트에 제네릭 `UserInfo` 를 표시합니다(예: 다른 컨텍스트 타입을 받는 도구를 전달하려고 할 때) -4. 컨텍스트는 `run` 함수로 전달됩니다 -5. 에이전트는 도구를 올바르게 호출하고 age 를 가져옵니다 +1. 이것은 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만, 어떤 타입이든 사용할 수 있습니다 +2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현이 컨텍스트에서 값을 읽습니다 +3. 에이전트에 제네릭 `UserInfo`를 표시하여 타입 체커가 오류를 잡을 수 있게 합니다(예: 다른 컨텍스트 타입을 받는 도구를 전달하려고 할 때) +4. 컨텍스트가 `run` 함수로 전달됩니다 +5. 에이전트가 도구를 올바르게 호출하고 나이를 가져옵니다 --- ### 고급: `ToolContext` -어떤 경우에는 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원문 인자 문자열)에 접근하고 싶을 수 있습니다. -이를 위해 `RunContextWrapper` 를 확장한 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다. +일부 경우, 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원문 인자 문자열)에 접근하고 싶을 수 있습니다. +이를 위해 `RunContextWrapper`를 확장한 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다. ```python from typing import Annotated @@ -105,23 +105,23 @@ agent = Agent( ) ``` -`ToolContext` 는 `RunContextWrapper` 와 동일한 `.context` 속성을 제공하며, -현재 도구 호출에 특화된 추가 필드가 있습니다: +`ToolContext`는 `RunContextWrapper`와 동일한 `.context` 프로퍼티와 함께, +현재 도구 호출에 특화된 추가 필드를 제공합니다: -- `tool_name` – 호출 중인 도구의 이름 -- `tool_call_id` – 이 도구 호출의 고유 식별자 +- `tool_name` – 호출되는 도구의 이름 +- `tool_call_id` – 해당 도구 호출의 고유 식별자 - `tool_arguments` – 도구에 전달된 원문 인자 문자열 -실행 중 도구 수준의 메타데이터가 필요할 때 `ToolContext` 를 사용하세요. -에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper` 로 충분합니다. +실행 중 도구 수준 메타데이터가 필요할 때 `ToolContext`를 사용하세요. +에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper`만으로 충분합니다. --- ## 에이전트/LLM 컨텍스트 -LLM 이 호출될 때, LLM 이 볼 수 있는 **유일한** 데이터는 대화 이력입니다. 즉, LLM 에게 새로운 데이터를 제공하려면 그 이력에 포함되도록 해야 합니다. 방법은 몇 가지가 있습니다: +LLM이 호출될 때, 볼 수 있는 데이터는 대화 기록뿐입니다. 즉, LLM이 새로운 데이터를 사용할 수 있게 하려면 그 데이터가 해당 기록에 포함되도록 해야 합니다. 이를 위한 방법은 다음과 같습니다: -1. Agent 의 `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. retrieval 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져오거나(retrieval), 웹에서 가져올 수 있는(웹 검색) 특수한 도구입니다. 이는 응답을 관련 컨텍스트 데이터에 "그라운딩" 하는 데 유용합니다 \ No newline at end of file +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. 리트리벌(retrieval) 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스(리트리벌) 또는 웹(웹 검색)에서 관련 데이터를 가져올 수 있는 특수 도구입니다. 관련 컨텍스트 데이터에 응답을 근거하도록 하는 데 유용합니다 \ No newline at end of file diff --git a/docs/ko/examples.md b/docs/ko/examples.md index 66e9175d0..fd74bbd5b 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -4,55 +4,55 @@ search: --- # 코드 예제 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK 의 다양한 샘플 구현을 확인하세요. code examples 는 다양한 패턴과 기능을 보여 주는 여러 카테고리로 구성되어 있습니다. +[repo](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 는 다음과 같은 일반적인 에이전트 설계 패턴을 보여 줍니다 + 이 카테고리의 code examples 는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 - 결정적 워크플로 - 도구로서의 에이전트 - - 병렬 에이전트 실행 + - 에이전트 병렬 실행 - 조건부 도구 사용 - 입력/출력 가드레일 - - 판사로서의 LLM + - LLM as a judge - 라우팅 - 스트리밍 가드레일 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 이 code examples 는 SDK 의 기본 기능을 보여 줍니다 + 이 code examples 는 SDK 의 기초 기능을 보여줍니다 - - Hello world code examples (기본 모델, GPT-5, open-weight 모델) - - 에이전트 수명주기 관리 + - Hello world examples (Default model, GPT-5, open-weight model) + - 에이전트 라이프사이클 관리 - 동적 시스템 프롬프트 - 스트리밍 출력(텍스트, 아이템, 함수 호출 인자) - 프롬프트 템플릿 - - 파일 처리(로컬 및 원격, 이미지 및 PDF) + - 파일 처리(로컬/원격, 이미지/PDF) - 사용량 추적 - 비엄격 출력 타입 - 이전 응답 ID 사용 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 항공사용 고객 서비스 시스템 예제. + 항공사를 위한 고객 서비스 시스템 예시 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 금융 데이터 분석을 위한 에이전트와 도구로 구조화된 연구 워크플로를 시연하는 금융 리서치 에이전트. + 금융 데이터 분석을 위한 에이전트와 도구로 구조화된 연구 워크플로를 보여주는 금융 리서치 에이전트 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 메시지 필터링이 포함된 에이전트 핸드오프의 실용적인 code examples 를 확인하세요. + 메시지 필터링을 통한 에이전트 핸드오프의 실용적인 code examples - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 호스티드 MCP (Model Context Protocol) 커넥터와 승인 사용 방법을 보여 주는 code examples. + 호스티드 MCP (Model Context Protocol) 커넥터와 승인을 사용하는 방법을 보여주는 code examples - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model Context Protocol) 로 에이전트를 구축하는 방법을 배우세요. 포함 내용: + MCP (Model Context Protocol) 로 에이전트를 빌드하는 방법을 학습하세요. 다음을 포함합니다 - - 파일시스템 코드 예제 - - Git 코드 예제 - - MCP 프롬프트 서버 코드 예제 - - SSE (Server-Sent Events) 코드 예제 - - 스트리머블 HTTP 코드 예제 + - 파일시스템 code examples + - Git code examples + - MCP 프롬프트 서버 code examples + - SSE (Server-Sent Events) code examples + - 스트리밍 가능한 HTTP code examples - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** 에이전트를 위한 다양한 메모리 구현 code examples @@ -65,29 +65,29 @@ search: - OpenAI 세션 스토리지 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 사용자 정의 provider 와 LiteLLM 통합을 포함하여 OpenAI 이외 모델을 SDK 와 함께 사용하는 방법을 살펴보세요. + 커스텀 프로바이더와 LiteLLM 연동을 포함하여, OpenAI 가 아닌 모델을 SDK 와 함께 사용하는 방법을 살펴보세요 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK 를 사용해 실시간 경험을 구축하는 방법을 보여 주는 code examples + SDK 를 사용해 실시간 경험을 구축하는 방법을 보여주는 code examples - 웹 애플리케이션 - 커맨드라인 인터페이스 - - Twilio 통합 + - Twilio 연동 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 추론 콘텐츠와 structured outputs 를 다루는 방법을 보여 주는 code examples. + 추론 콘텐츠와 structured outputs 를 다루는 방법을 보여주는 code examples - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 복잡한 멀티 에이전트 리서치 워크플로를 시연하는 간단한 딥 리서치 클론. + 복잡한 멀티 에이전트 연구 워크플로를 시연하는 간단한 딥 리서치 클론 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 다음과 같은 OpenAI 호스트하는 도구를 구현하는 방법을 배우세요 + 다음과 같은 OpenAI 호스트하는 도구를 구현하는 방법을 학습하세요 - - 웹 검색 및 필터가 있는 웹 검색 + - 웹 검색 및 필터 포함 웹 검색 - 파일 검색 - Code interpreter - 컴퓨터 사용 - 이미지 생성 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - TTS 및 STT 모델을 사용하는 음성 에이전트 code examples 를 확인하세요. 스트리밍 음성 code examples 도 포함됩니다. \ No newline at end of file + TTS 및 STT 모델을 사용한 음성 에이전트 code examples 를 확인하세요. 스트리밍 음성 code examples 포함 \ No newline at end of file diff --git a/docs/ko/guardrails.md b/docs/ko/guardrails.md index 86251e0aa..b1c993482 100644 --- a/docs/ko/guardrails.md +++ b/docs/ko/guardrails.md @@ -4,9 +4,9 @@ search: --- # 가드레일 -가드레일은 사용자 입력과 에이전트 출력에 대한 검사와 유효성 검사를 수행할 수 있게 해줍니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고/비싼) 모델을 사용하는 에이전트가 있다고 가정해 보세요. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것은 원치 않을 것입니다. 이때 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜 비싼 모델 실행을 방지하여 시간과 비용을 절약할 수 있습니다(**블로킹 가드레일 사용 시. 병렬 가드레일의 경우, 가드레일이 완료되기 전에 비싼 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래의 "실행 모드"를 참조하세요**). +가드레일은 사용자 입력과 에이전트 출력에 대한 검사와 검증을 수행할 수 있도록 합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(그리고 느리고 비싼) 모델을 사용하는 에이전트를 상상해 보세요. 악의적인 사용자가 모델에게 수학 숙제를 도와달라고 요청하는 것은 원치 않을 것입니다. 이때 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜 비싼 모델이 실행되는 것을 방지하여 시간과 비용을 절약할 수 있습니다(**블로킹 가드레일을 사용할 때 해당하며, 병렬 가드레일의 경우 가드레일이 완료되기 전에 비싼 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래 "실행 모드"를 참조하세요**). -가드레일에는 두 종류가 있습니다: +가드레일에는 두 가지 종류가 있습니다: 1. 입력 가드레일은 초기 사용자 입력에서 실행됨 2. 출력 가드레일은 최종 에이전트 출력에서 실행됨 @@ -17,19 +17,19 @@ search: 1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑됩니다 -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하며, 이를 통해 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true인 경우, [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하여 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 첫 번째 에이전트일 때만 실행됩니다. 왜 `guardrails` 속성이 `Runner.run`에 전달되는 대신 에이전트에 있는지 궁금할 수 있습니다. 이는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하므로, 코드를 같은 곳에 두는 것이 가독성에 유리합니다. + 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. 왜 `guardrails` 속성이 `Runner.run`에 전달되지 않고 에이전트에 있는지 궁금할 수 있습니다. 가드레일은 실제 에이전트와 밀접하게 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행할 수 있으므로, 코드를 같은 위치에 두는 것이 가독성에 유리합니다. ### 실행 모드 입력 가드레일은 두 가지 실행 모드를 지원합니다: -- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트 실행과 동시에 실행됩니다. 둘 다 동시에 시작되므로 지연 시간이 가장 좋습니다. 그러나 가드레일이 실패할 경우, 에이전트는 취소되기 전에 이미 토큰을 소비하고 도구를 실행했을 수 있습니다. +- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트의 실행과 동시에 실행됩니다. 둘 다 동시에 시작되므로 지연 시간이 가장 좋습니다. 그러나 가드레일이 실패하는 경우, 에이전트는 취소되기 전에 이미 토큰을 소비하고 도구를 실행했을 수 있습니다. -- **블로킹 실행**(`run_in_parallel=False`): 가드레일이 에이전트가 시작되기 전에 실행을 완료합니다. 가드레일 트립와이어가 트리거되면, 에이전트는 전혀 실행되지 않아 토큰 소비와 도구 실행을 방지합니다. 비용 최적화와 도구 호출로 인한 잠재적 부작용을 피하고자 할 때 이상적입니다. +- **블로킹 실행**(`run_in_parallel=False`): 가드레일이 에이전트가 시작되기 *전에* 실행을 완료합니다. 가드레일 트립와이어가 트리거되면, 에이전트는 전혀 실행되지 않아 토큰 소비와 도구 실행이 방지됩니다. 비용 최적화와 도구 호출의 부작용을 피하고 싶을 때 이상적입니다. ## 출력 가드레일 @@ -37,21 +37,21 @@ search: 1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑됩니다 -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하며, 이를 통해 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true인 경우, [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하여 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 마지막 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 관련되는 경우가 많기 때문에 코드를 같은 곳에 두는 것이 가독성에 유리합니다. + 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 밀접하게 관련되므로 에이전트마다 다른 가드레일을 실행할 수 있습니다. 코드를 같은 위치에 두는 것이 가독성에 유리합니다. 출력 가드레일은 항상 에이전트가 완료된 후에 실행되므로, `run_in_parallel` 매개변수를 지원하지 않습니다. ## 트립와이어 -입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. +입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 감지하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. ## 가드레일 구현 -입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예제에서는 내부적으로 에이전트를 실행하여 이를 수행합니다. +입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예시에서는 내부적으로 에이전트를 실행하여 이를 수행합니다. ```python from pydantic import BaseModel @@ -104,10 +104,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. 가드레일 함수에서 이 에이전트를 사용합니다. -2. 이것이 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다. -3. 가드레일 결과에 추가 정보를 포함할 수 있습니다. -4. 이것이 워크플로를 정의하는 실제 에이전트입니다. +1. 이 에이전트를 가드레일 함수에서 사용합니다 +2. 이것은 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다 +3. 가드레일 결과에 추가 정보를 포함할 수 있습니다 +4. 이것이 워크플로를 정의하는 실제 에이전트입니다 출력 가드레일도 유사합니다. @@ -162,7 +162,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. 이것이 실제 에이전트의 출력 타입입니다. -2. 이것이 가드레일의 출력 타입입니다. -3. 이것이 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다. -4. 이것이 워크플로를 정의하는 실제 에이전트입니다. \ No newline at end of file +1. 이것이 실제 에이전트의 출력 타입입니다 +2. 이것이 가드레일의 출력 타입입니다 +3. 이것은 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다 +4. 이것이 워크플로를 정의하는 실제 에이전트입니다 \ No newline at end of file diff --git a/docs/ko/handoffs.md b/docs/ko/handoffs.md index aa72c446b..67b2bb134 100644 --- a/docs/ko/handoffs.md +++ b/docs/ko/handoffs.md @@ -4,17 +4,17 @@ search: --- # 핸드오프 -핸드오프는 한 에이전트가 다른 에이전트에게 작업을 위임할 수 있게 합니다. 이는 서로 다른 에이전트가 각기 다른 영역을 전문으로 하는 시나리오에서 특히 유용합니다. 예를 들어, 고객 지원 앱에서는 주문 상태, 환불, FAQ 등을 각각 전담하는 에이전트가 있을 수 있습니다. +핸드오프를 사용하면 에이전트가 작업을 다른 에이전트에 위임할 수 있습니다. 이는 서로 다른 에이전트가 각기 다른 영역에 특화되어 있는 시나리오에서 특히 유용합니다. 예를 들어, 고객 지원 앱에서는 주문 상태, 환불, FAQ 등과 같은 작업을 각각 처리하는 에이전트가 있을 수 있습니다. -핸드오프는 LLM 에게 도구로 표시됩니다. 예를 들어 `Refund Agent` 라는 에이전트로의 핸드오프가 있다면, 도구 이름은 `transfer_to_refund_agent` 가 됩니다. +핸드오프는 LLM 에게 도구로 표시됩니다. 예를 들어 `Refund Agent` 라는 에이전트로 핸드오프가 있다면, 도구 이름은 `transfer_to_refund_agent` 가 됩니다. ## 핸드오프 생성 -모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, `Agent` 를 직접 전달하거나 Handoff 를 커스터마이징하는 `Handoff` 객체를 전달할 수 있습니다. +모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, `Agent` 를 직접 전달하거나 핸드오프를 커스터마이즈하는 `Handoff` 객체를 전달할 수 있습니다. -Agents SDK 가 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용해 핸드오프를 생성할 수 있습니다. 이 함수는 핸드오프 대상 에이전트를 지정하고, 선택적 override 와 입력 필터를 함께 설정할 수 있게 해줍니다. +Agents SDK 에서 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용하여 핸드오프를 생성할 수 있습니다. 이 함수는 핸드오프 대상 에이전트와 함께 선택적 override 와 입력 필터를 지정할 수 있게 해줍니다. -### 기본 사용법 +### 기본 사용 간단한 핸드오프를 만드는 방법은 다음과 같습니다: @@ -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()` 함수로 핸드오프 사용자 지정 -[`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 @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## Handoff 입력 +## 핸드오프 입력 -특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하길 원할 수 있습니다. 예를 들어, "Escalation agent" 로의 핸드오프를 상상해 보세요. 로깅을 위해 사유가 제공되도록 하고 싶을 수 있습니다. +특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하기를 원할 수 있습니다. 예를 들어, "에스컬레이션 에이전트" 로의 핸드오프를 상상해보세요. 로그를 위해 사유를 제공받고 싶을 수 있습니다. ```python from pydantic import BaseModel @@ -84,11 +84,11 @@ 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` 를 반환해야 하는 함수입니다. -기본적으로 러너는 이제 이전 대화록을 하나의 assistant 요약 메시지로 압축합니다(참고: [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]). 요약은 동일한 실행 중에 여러 번의 핸드오프가 발생하면 새로운 턴을 계속 추가하는 `` 블록 내부에 표시됩니다. 전체 `input_filter` 를 작성하지 않고도 생성된 메시지를 교체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 를 통해 매핑 함수를 제공할 수 있습니다. 해당 기본 동작은 핸드오프와 실행 모두에서 명시적인 `input_filter` 를 제공하지 않는 경우에만 적용되므로, 이미 페이로드를 커스터마이징하는 기존 코드(이 저장소의 code examples 포함)는 변경 없이 현재 동작을 유지합니다. 단일 핸드오프에 대해 중첩 동작을 재정의하려면 [`handoff(...)`][agents.handoffs.handoff] 에 `nest_handoff_history=True` 또는 `False` 를 전달하세요. 이는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 를 설정합니다. 생성된 요약의 래퍼 텍스트만 변경하면 되는 경우, 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (및 선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]) 를 호출하세요. +기본적으로 런너는 이전 대화록을 하나의 assistant 요약 메시지로 접습니다([`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 참조). 요약은 동일한 실행 중에 여러 번의 핸드오프가 발생할 때 새 턴이 계속 추가되는 `` 블록 내부에 나타납니다. 전체 `input_filter` 를 작성하지 않고도 생성된 메시지를 교체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 를 통해 자체 매핑 함수를 제공할 수 있습니다. 해당 기본 동작은 핸드오프와 실행 중 어느 쪽에서도 명시적인 `input_filter` 를 제공하지 않는 경우에만 적용되므로, 이미 페이로드를 커스터마이즈하고 있는 기존 코드(이 저장소의 code examples 포함)는 변경 없이 현재 동작을 유지합니다. 개별 핸드오프에 대해 중첩 동작을 오버라이드하려면 [`handoff(...)`][agents.handoffs.handoff] 에 `nest_handoff_history=True` 또는 `False` 를 전달하여 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 를 설정하세요. 생성된 요약의 래퍼 텍스트만 변경하면 되는 경우, 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers])를 호출하세요. -몇 가지 일반적인 패턴(예: 기록에서 모든 도구 호출 제거)이 있으며, 이는 [`agents.extensions.handoff_filters`][] 에 구현되어 있습니다 +일반적인 패턴들(예: 기록에서 모든 도구 호출 제거)은 [`agents.extensions.handoff_filters`][] 에 구현되어 있습니다 ```python from agents import Agent, handoff @@ -102,11 +102,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/ko/index.md b/docs/ko/index.md index 30298a0c7..319b57790 100644 --- a/docs/ko/index.md +++ b/docs/ko/index.md @@ -4,39 +4,39 @@ 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는 매우 소수의 기본 구성 요소(basic components)만 제공합니다: +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)는 추상화가 매우 적은 경량 패키지로 에이전트형 AI 앱을 쉽게 구축할 수 있게 해줍니다. 이는 이전 에이전트 실험 프로젝트인 [Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션급 업그레이드입니다. Agents SDK에는 매우 작은 범위의 기본 구성 요소가 있습니다: -- **에이전트**: instructions와 tools를 갖춘 LLM -- **핸드오프**: 특정 작업을 다른 에이전트에 위임할 수 있도록 함 -- **가드레일**: 에이전트의 입력과 출력을 검증할 수 있도록 함 -- **세션**: 에이전트 실행 전반에 걸쳐 대화 이력을 자동으로 관리 +- **에이전트**: instructions와 tools를 갖춘 LLM +- **핸드오프**: 특정 작업에 대해 에이전트가 다른 에이전트에 위임할 수 있도록 함 +- **가드레일**: 에이전트 입력 및 출력의 유효성을 검사할 수 있도록 함 +- **세션**: 에이전트 실행 전반에 걸쳐 대화 기록을 자동으로 유지 관리함 -파이썬과 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 충분히 표현할 수 있고, 높은 학습 곡선 없이 실사용 애플리케이션을 만들 수 있습니다. 또한, SDK에는 에이전트 플로우를 시각화하고 디버깅할 수 있는 내장 **트레이싱**이 포함되어 있으며, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝하는 데에도 활용할 수 있습니다. +Python과 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 충분히 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버그할 수 있는 내장 **트레이싱**이 포함되어 있어 평가를 수행하고, 심지어 애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다. -## Why use the Agents SDK +## Agents SDK를 사용해야 하는 이유 -SDK는 다음의 두 가지 설계 원칙을 따릅니다: +SDK의 설계 원칙은 다음과 같습니다: 1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 학습할 수 있도록 기본 구성 요소는 최소화합니다 -2. 기본값만으로도 잘 동작하되, 실제로 어떤 일이 일어나는지 정확히 커스터마이즈할 수 있습니다 +2. 기본 설정만으로도 훌륭하게 작동하지만, 동작을 정확히 원하는 대로 커스터마이즈할 수 있습니다 SDK의 주요 기능은 다음과 같습니다: -- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지의 루프를 처리하는 내장 에이전트 루프 -- 파이썬 우선: 새로운 추상화를 학습할 필요 없이, 내장 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝 -- 핸드오프: 여러 에이전트 간을 조정하고 위임할 수 있는 강력한 기능 -- 가드레일: 에이전트와 병렬로 입력 검증과 체크를 실행하고, 실패 시 조기 중단 -- 세션: 에이전트 실행 전반의 대화 이력을 자동 관리하여 수동 상태 관리를 제거 -- 함수 도구: 어떤 Python 함수든 도구로 전환, 자동 스키마 생성과 Pydantic 기반 검증 지원 -- 트레이싱: 워크플로를 시각화, 디버그, 모니터링할 수 있는 내장 트레이싱과 OpenAI의 평가, 파인튜닝, 증류 도구 활용 +- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 처리하는 내장 에이전트 루프 +- 파이썬 우선: 새로운 추상화를 학습할 필요 없이, 언어의 기본 기능만으로 에이전트를 오케스트레이션하고 체이닝 +- 핸드오프: 여러 에이전트 간 조정과 위임을 가능하게 하는 강력한 기능 +- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 수행하고, 실패 시 조기에 중단 +- 세션: 에이전트 실행 전반에 걸쳐 대화 기록을 자동으로 관리하여 수동 상태 관리 제거 +- 함수 도구: 어떤 Python 함수든 자동 스키마 생성과 Pydantic 기반 검증으로 도구로 전환 +- 트레이싱: 워크플로우를 시각화, 디버그, 모니터링할 수 있는 내장 트레이싱과 함께 OpenAI의 평가, 파인튜닝, 증류 도구 활용 -## Installation +## 설치 ```bash pip install openai-agents ``` -## Hello world example +## Hello World 예제 ```python from agents import Agent, Runner @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_) +(_이를 실행하는 경우 `OPENAI_API_KEY` 환경 변수를 설정했는지 확인하세요_) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ko/mcp.md b/docs/ko/mcp.md index cdb1a49d8..c73a30846 100644 --- a/docs/ko/mcp.md +++ b/docs/ko/mcp.md @@ -4,36 +4,37 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP)은 애플리케이션이 도구와 컨텍스트를 언어 모델에 노출하는 방식을 표준화합니다. 공식 문서에서 인용합니다: +The [Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) standardises how applications expose tools and +context to language models. From the official documentation: > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI > applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP > provides a standardized way to connect AI models to different data sources and tools. -Agents Python SDK는 여러 MCP 전송 방식을 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 직접 구축하여 파일 시스템, HTTP, 또는 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. +Agents Python SDK 는 여러 MCP 전송 방식을 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나, 자체 서버를 구축해 파일시스템, HTTP, 혹은 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. -## MCP 통합 선택 +## Choosing an MCP integration -MCP 서버를 에이전트에 연결하기 전에 도구 호출이 어디에서 실행되어야 하는지, 그리고 어떤 전송 방식을 사용할 수 있는지 결정하세요. 아래 매트릭스는 Python SDK가 지원하는 옵션을 요약합니다. +에이전트에 MCP 서버를 연결하기 전에, 도구 호출을 어디에서 실행할지와 접근 가능한 전송 방식을 결정하세요. 아래 매트릭스는 Python SDK 가 지원하는 옵션을 요약합니다. -| 필요한 것 | 권장 옵션 | +| 필요한 것 | 권장 옵션 | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| OpenAI의 Responses API가 모델을 대신해 공개적으로 접근 가능한 MCP 서버를 호출하도록 함 | **호스티드 MCP 서버 도구** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | -| 로컬 또는 원격으로 실행하는 Streamable HTTP 서버에 연결 | **Streamable HTTP MCP 서버** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | -| Server-Sent Events를 사용하는 HTTP를 구현한 서버와 통신 | **HTTP with SSE MCP 서버** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | -| 로컬 프로세스를 실행하고 stdin/stdout으로 통신 | **stdio MCP 서버** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | +| 모델을 대신해 OpenAI 의 Responses API 가 공용 MCP 서버를 호출하도록 하기 | **호스티드 MCP 서버 도구** via [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| 로컬 또는 원격에서 실행하는 Streamable HTTP 서버에 연결 | **Streamable HTTP MCP 서버** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Server-Sent Events 를 사용하는 HTTP 구현 서버와 통신 | **HTTP with SSE MCP 서버** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| 로컬 프로세스를 실행하고 stdin/stdout 으로 통신 | **stdio MCP 서버** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -아래 섹션에서는 각 옵션을 설정하는 방법과 어떤 상황에서 어떤 전송 방식을 선호해야 하는지 설명합니다. +아래 섹션에서는 각 옵션에 대해 구성 방법과 언제 어떤 전송 방식을 선호해야 하는지를 설명합니다. ## 1. Hosted MCP server tools -호스티드 툴은 전체 도구 왕복 과정을 OpenAI 인프라로 이전합니다. 코드에서 도구를 나열하고 호출하는 대신, -[`HostedMCPTool`][agents.tool.HostedMCPTool]이 서버 레이블(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은 추가 콜백 없이 원격 서버의 도구를 나열하고 호출합니다. 호스티드 툴은 현재 Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 동작합니다. +호스티드 툴은 전체 도구 왕복 과정을 OpenAI 인프라에서 처리합니다. 코드에서 도구를 나열하고 호출하는 대신, +[`HostedMCPTool`][agents.tool.HostedMCPTool] 이 서버 레이블(및 선택적 커넥터 메타데이터)을 Responses API 로 전달합니다. 모델은 원격 서버의 도구를 나열하고 Python 프로세스에 추가 콜백 없이 이를 호출합니다. 호스티드 툴은 현재 Responses API 의 호스티드 MCP 통합을 지원하는 OpenAI 모델과 함께 동작합니다. -### 기본 호스티드 MCP 툴 +### Basic hosted MCP tool -에이전트의 `tools` 목록에 [`HostedMCPTool`][agents.tool.HostedMCPTool]을 추가하여 호스티드 툴을 만듭니다. `tool_config` -dict는 REST API에 보낼 JSON과 동일한 구조를 따릅니다: +에이전트의 `tools` 리스트에 [`HostedMCPTool`][agents.tool.HostedMCPTool] 을 추가하여 호스티드 툴을 생성합니다. `tool_config` +dict 는 REST API 에 전송할 JSON 과 동일한 구조를 따릅니다: ```python import asyncio @@ -61,11 +62,12 @@ async def main() -> None: asyncio.run(main()) ``` -호스티드 서버는 도구를 자동으로 노출하므로 `mcp_servers`에 추가할 필요가 없습니다. +호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers` 에 추가할 필요가 없습니다. -### 스트리밍 호스티드 MCP 결과 +### Streaming hosted MCP results -호스티드 툴은 함수 도구와 동일한 방식으로 스트리밍 결과를 지원합니다. 모델이 작업 중일 때 점진적인 MCP 출력을 소비하려면 `Runner.run_streamed`에 `stream=True`를 전달하세요: +호스티드 툴은 함수 도구와 정확히 같은 방식으로 스트리밍 결과를 지원합니다. `Runner.run_streamed` 에 `stream=True` 를 전달하여 +모델이 작업 중인 동안 증분 MCP 출력을 소비할 수 있습니다: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -75,9 +77,10 @@ async for event in result.stream_events(): print(result.final_output) ``` -### 선택적 승인 플로우 +### Optional approval flows -서버가 민감한 작업을 수행할 수 있는 경우 각 도구 실행 전에 사람 또는 프로그램의 승인을 요구할 수 있습니다. `tool_config`의 `require_approval`을 단일 정책(`"always"`, `"never"`) 또는 도구 이름과 정책의 dict 매핑으로 구성하세요. Python 내부에서 결정을 내리려면 `on_approval_request` 콜백을 제공하세요. +서버가 민감한 작업을 수행할 수 있는 경우 각 도구 실행 전에 사람 또는 프로그램적 승인을 요구할 수 있습니다. `tool_config` 의 +`require_approval` 을 단일 정책(`"always"`, `"never"`) 또는 도구 이름을 정책에 매핑한 dict 로 구성하세요. 의사결정을 Python 내부에서 수행하려면 `on_approval_request` 콜백을 제공하세요. ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -105,11 +108,12 @@ agent = Agent( ) ``` -콜백은 동기 또는 비동기로 작성할 수 있으며, 모델이 계속 실행하는 데 승인 데이터가 필요할 때마다 호출됩니다. +콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행되기 위해 승인 데이터가 필요할 때마다 호출됩니다. -### 커넥터 기반 호스티드 서버 +### Connector-backed hosted servers -호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다. +호스티드 MCP 는 OpenAI 커넥터도 지원합니다. `server_url` 을 지정하는 대신 `connector_id` 와 액세스 토큰을 제공하세요. +Responses API 가 인증을 처리하고, 호스티드 서버가 커넥터의 도구를 노출합니다. ```python import os @@ -126,12 +130,12 @@ HostedMCPTool( ``` 스트리밍, 승인, 커넥터를 포함한 완전한 호스티드 툴 샘플은 -[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)에 있습니다. +[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) 에 있습니다. -## 2. Streamable HTTP MCP 서버 +## 2. Streamable HTTP MCP servers 네트워크 연결을 직접 관리하려면 -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 사용하세요. 스트리밍 가능한 HTTP 서버는 전송을 제어하거나, 지연 시간을 낮게 유지하면서 자체 인프라 내에서 서버를 실행하려는 경우에 적합합니다. +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 를 사용하세요. Streamable HTTP 서버는 전송을 직접 제어하거나, 지연 시간을 낮게 유지하면서 자체 인프라 내에서 서버를 실행하고자 할 때 이상적입니다. ```python import asyncio @@ -166,17 +170,17 @@ async def main() -> None: 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) 참조) +- `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` 를 사용하면 노출할 도구의 서브셋만 선택할 수 있습니다(see [도구 필터링](#tool-filtering)) -## 3. HTTP with SSE MCP 서버 +## 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 @@ -203,9 +207,9 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP 서버 +## 4. stdio MCP servers -로컬 하위 프로세스로 실행되는 MCP 서버의 경우 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 사용하세요. SDK는 프로세스를 생성하고 파이프를 열어 유지하며, 컨텍스트 관리자가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른 프로토타입이나 서버가 명령줄 엔트리 포인트만 노출하는 경우에 유용합니다. +로컬 하위 프로세스로 실행되는 MCP 서버에는 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 를 사용하세요. SDK 가 프로세스를 시작하고 파이프를 열어두며 컨텍스트 매니저가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른 개념 증명이나 서버가 커맨드라인 엔트리 포인트만 노출하는 경우에 유용합니다. ```python from pathlib import Path @@ -231,13 +235,13 @@ async with MCPServerStdio( print(result.final_output) ``` -## 도구 필터링 +## 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,11 +259,11 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names`와 `blocked_tool_names`가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 뒤 남은 집합에서 차단된 도구를 제거합니다. +`allowed_tool_names` 와 `blocked_tool_names` 가 모두 제공되면 SDK 는 먼저 허용 리스트를 적용한 뒤, 남은 집합에서 차단된 도구를 제거합니다. -### 동적 도구 필터링 +### Dynamic tool filtering -더 정교한 로직이 필요하다면 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 callable을 전달하세요. 이 callable은 동기 또는 비동기로 작성할 수 있으며, 도구를 노출해야 할 때 `True`를 반환합니다. +더 정교한 로직을 위해 [`ToolFilterContext`][agents.mcp.ToolFilterContext] 를 받는 호출 가능 객체를 전달하세요. 이 호출체는 동기 또는 비동기일 수 있으며, 도구를 노출해야 할 때 `True` 를 반환합니다. ```python from pathlib import Path @@ -283,14 +287,15 @@ async with MCPServerStdio( ... ``` -필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, 그리고 `server_name`을 제공합니다. +필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, 그리고 `server_name` 을 제공합니다. -## 프롬프트 +## Prompts -MCP 서버는 에이전트 instructions를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 메서드를 노출합니다: +MCP 서버는 에이전트 instructions 를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 +메서드를 노출합니다: -- `list_prompts()`는 사용 가능한 프롬프트 템플릿을 나열합니다 -- `get_prompt(name, arguments)`는 선택적인 매개변수와 함께 구체적인 프롬프트를 가져옵니다 +- `list_prompts()` 는 사용 가능한 프롬프트 템플릿을 열거합니다 +- `get_prompt(name, arguments)` 는 필요하면 매개변수와 함께 구체적인 프롬프트를 가져옵니다 ```python from agents import Agent @@ -308,21 +313,22 @@ 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.md)은 MCP 활동을 자동으로 캡처합니다. 다음을 포함합니다: +[Tracing](./tracing.md) 은 다음을 포함해 MCP 활동을 자동으로 캡처합니다: -1. 도구 목록을 가져오기 위한 MCP 서버 호출 -2. 도구 호출과 관련된 MCP 정보 +1. MCP 서버에 도구 목록을 요청하는 호출 +2. 도구 호출의 MCP 관련 정보 ![MCP Tracing Screenshot](../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) – 승인과 커넥터를 포함한 완전한 호스티드 MCP 데모 \ No newline at end of file +- [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 index 6aec8da1c..67e9495bd 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,20 +4,20 @@ search: --- # 모델 -Agents SDK 는 OpenAI 모델을 다음 두 가지 방식으로 기본 지원합니다: +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] +- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses) 를 사용하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 를 사용하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] ## 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_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 추론 모델([`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 의 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")` 를 호출하세요. -지연 시간을 더 낮추거나 특정 요구 사항이 있는 경우 다른 모델과 설정을 선택할 수 있습니다. 기본 모델의 추론 강도를 조정하려면 사용자 정의 `ModelSettings` 를 전달하세요: +더 낮은 지연 시간이나 특정 요구 사항이 있다면, 다른 모델과 설정을 선택할 수 있습니다. 기본 모델의 reasoning effort 를 조정하려면, 사용자 지정 `ModelSettings` 를 전달하세요: ```python from openai.types.shared import Reasoning @@ -44,21 +44,21 @@ 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"` 추론 강도를 지원하지 않으므로, 본 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"` reasoning effort 를 지원하지 않으므로, 본 Agents SDK 의 기본값은 `"low"` 입니다. #### 비 GPT-5 모델 -사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하는 경우, SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌립니다. +사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하면, SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌립니다. ## 비 OpenAI 모델 -대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 litellm 의 종속성 그룹을 설치하세요: +대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md) 을 통해 사용할 수 있습니다. 먼저 litellm 의 추가 의존성을 설치하세요: ```bash pip install "openai-agents[litellm]" ``` -그런 다음 `litellm/` 접두사를 사용하여 [지원되는 모델](https://docs.litellm.ai/docs/providers) 중 아무 것이나 사용하세요: +그런 다음 `litellm/` 접두어와 함께 [지원 모델](https://docs.litellm.ai/docs/providers) 을 사용하세요: ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) @@ -67,29 +67,29 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 비 OpenAI 모델을 사용하는 다른 방법 -다른 LLM 제공자를 통합하는 방법은 추가로 3가지가 있습니다(예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다): +다른 LLM 공급자를 통합하는 3가지 방법이 더 있습니다(예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) 에서 확인): -1. [`set_default_openai_client`][agents.set_default_openai_client] 는 전역적으로 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 사용하려는 경우에 유용합니다. 이는 LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고, `base_url` 과 `api_key` 를 설정할 수 있는 경우입니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) 를 참고하세요. -2. [`ModelProvider`][agents.models.interface.ModelProvider] 는 `Runner.run` 레벨입니다. 이를 통해 "이 실행에서 모든 에이전트에 사용자 정의 모델 제공자를 사용"하도록 지정할 수 있습니다. 구성 가능한 예시는 [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] 는 전역적으로 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 사용하고자 할 때 유용합니다. 이는 LLM 공급자가 OpenAI 호환 API 엔드포인트를 제공하고, `base_url` 및 `api_key` 를 설정할 수 있는 경우에 해당합니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) 를 참조하세요. +2. [`ModelProvider`][agents.models.interface.ModelProvider] 는 `Runner.run` 레벨에서 사용됩니다. 이를 통해 “이 실행의 모든 에이전트에 대해 사용자 지정 모델 공급자를 사용”할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) 를 참조하세요. +3. [`Agent.model`][agents.agent.Agent.model] 은 특정 Agent 인스턴스에서 모델을 지정할 수 있게 합니다. 이를 통해 에이전트별로 서로 다른 공급자를 혼합해 사용할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) 를 참조하세요. 대부분의 사용 가능한 모델을 쉽게 사용하는 방법은 [LiteLLM 통합](./litellm.md) 을 사용하는 것입니다. -`platform.openai.com` 의 API 키가 없는 경우, `set_tracing_disabled()` 로 트레이싱을 비활성화하거나, [다른 트레이싱 프로세서](../tracing.md) 설정을 권장합니다. +`platform.openai.com` 의 API 키가 없는 경우, `set_tracing_disabled()` 로 트레이싱을 비활성화하거나, [다른 트레이싱 프로세서](../tracing.md) 를 설정하는 것을 권장합니다. !!! note - 이 예시들에서는 대부분의 LLM 제공자가 아직 Responses API 를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. LLM 제공자가 이를 지원한다면 Responses 사용을 권장합니다. + 이 예시들에서는 대부분의 LLM 공급자가 아직 Responses API 를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. 사용 중인 LLM 공급자가 이를 지원한다면 Responses 사용을 권장합니다. ## 모델 혼합 사용 -하나의 워크플로 내에서 에이전트마다 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어, 분류 작업에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때, 다음 중 하나의 방법으로 특정 모델을 선택할 수 있습니다: +하나의 워크플로 내에서 에이전트마다 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어, 분류(트리아지)에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 한 가지 방법으로 특정 모델을 선택할 수 있습니다: 1. 모델 이름을 전달 -2. 임의의 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달 -3. [`Model`][agents.models.interface.Model] 구현을 직접 제공 +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] 두 가지 모양을 모두 지원하지만, 각 워크플로마다 단일 모델 모양을 사용하는 것을 권장합니다. 두 모양은 지원하는 기능과 도구가 다르기 때문입니다. 워크플로에 서로 다른 모델 모양의 혼합이 필요하다면, 사용하는 모든 기능이 두 모양 모두에서 사용 가능한지 확인하세요. + SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 두 가지 모델 형태를 모두 지원하지만, 두 형태가 지원하는 기능과 도구가 다르므로 워크플로마다 하나의 모델 형태만 사용할 것을 권장합니다. 워크플로에서 모델 형태를 혼합해야 한다면, 사용하는 모든 기능이 두 형태 모두에서 사용 가능한지 확인하세요. ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -123,9 +123,9 @@ async def main(): ``` 1. OpenAI 모델의 이름을 직접 설정합니다 -2. [`Model`][agents.models.interface.Model] 구현을 제공합니다 +2. [`Model`][agents.models.interface.Model] 구현체를 제공합니다 -에이전트에 사용되는 모델을 더 세부적으로 구성하려면, temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings] 를 전달할 수 있습니다. +에이전트에 사용되는 모델을 더 세부적으로 구성하려면, temperature 와 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings] 를 전달할 수 있습니다. ```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 공급자 사용 시 흔한 문제 ### Tracing 클라이언트 오류 401 -트레이싱 관련 오류가 발생한다면, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 다음 중 하나입니다: +트레이싱 관련 오류가 발생하는 경우, 트레이스가 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) 참조 +2. 트레이싱을 위한 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며, 반드시 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다 +3. 비 OpenAI 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 를 참조하세요 ### Responses API 지원 -SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 그 결과 404 등 문제가 발생할 수 있습니다. 해결 방법은 다음 두 가지입니다: +SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 공급자는 아직 이를 지원하지 않습니다. 이로 인해 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/)에 있습니다 +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 지원 -일부 모델 제공자는 [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, 멀티모달 입력, 호스티드 파일 검색과 웹 검색을 지원하지만, 많은 다른 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요: +모델 공급자별 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어, OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 많은 다른 공급자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요: -- 지원하지 않는 `tools` 를 이해하지 못하는 제공자에 보내지 않기 +- 지원되지 않는 `tools` 를 이해하지 못하는 공급자에게 보내지 않기 - 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하기 -- structured JSON 출력을 지원하지 않는 제공자는 때때로 잘못된 JSON 을 생성할 수 있음을 인지하기 \ No newline at end of file +- structured JSON 출력을 지원하지 않는 공급자는 때때로 잘못된 JSON 을 생성할 수 있음을 유의하기 \ No newline at end of file diff --git a/docs/ko/models/litellm.md b/docs/ko/models/litellm.md index 7b26db3f2..93b3982b5 100644 --- a/docs/ko/models/litellm.md +++ b/docs/ko/models/litellm.md @@ -6,29 +6,29 @@ search: !!! note - LiteLLM 연동은 베타 단계입니다. 특히 소규모 모델 제공자에서 문제가 발생할 수 있습니다. [Github issues](https://github.com/openai/openai-agents-python/issues)로 문제를 보고해 주세요. 신속히 수정하겠습니다. + LiteLLM 통합은 베타입니다. 특히 소규모 모델 제공업체에서 문제가 발생할 수 있습니다. [GitHub 이슈](https://github.com/openai/openai-agents-python/issues)로 보고해 주시면 신속히 해결하겠습니다. -[LiteLLM](https://docs.litellm.ai/docs/)은 단일 인터페이스로 100개 이상의 모델을 사용할 수 있게 해주는 라이브러리입니다. Agents SDK 에 LiteLLM 연동을 추가하여, 어떤 AI 모델이든 사용할 수 있습니다. +[LiteLLM](https://docs.litellm.ai/docs/)은 단일 인터페이스로 100개 이상의 모델을 사용할 수 있게 해주는 라이브러리입니다. Agents SDK 에 LiteLLM 통합을 추가하여 어떤 AI 모델이든 사용할 수 있습니다. ## 설정 -`litellm` 이 사용 가능해야 합니다. 선택적 `litellm` 의존성 그룹을 설치해 준비할 수 있습니다: +`litellm` 이 사용 가능해야 합니다. 선택적 `litellm` 종속성 그룹을 설치하면 됩니다: ```bash pip install "openai-agents[litellm]" ``` -설치가 완료되면, 어떤 에이전트에서도 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 을 사용할 수 있습니다. +설치가 완료되면 어떤 에이전트에서도 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 을 사용할 수 있습니다. ## 예제 -다음은 완전히 동작하는 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 프롬프트가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: +다음은 완전한 동작 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 프롬프트가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: -- `openai/gpt-4.1` 를 모델로, OpenAI API 키 -- `anthropic/claude-3-5-sonnet-20240620` 를 모델로, Anthropic API 키 -- 등등 +- 모델에는 `openai/gpt-4.1`, API 키에는 OpenAI API 키 +- 모델에는 `anthropic/claude-3-5-sonnet-20240620`, API 키에는 Anthropic API 키 +- 등 -LiteLLM 에서 지원하는 전체 모델 목록은 [litellm 제공자 문서](https://docs.litellm.ai/docs/providers)를 참조하세요. +LiteLLM 에서 지원하는 전체 모델 목록은 [litellm providers docs](https://docs.litellm.ai/docs/providers)를 참조하세요. ```python from __future__ import annotations @@ -78,7 +78,7 @@ if __name__ == "__main__": ## 사용량 데이터 추적 -LiteLLM 응답이 Agents SDK 사용량 지표에 반영되도록 하려면, 에이전트를 만들 때 `ModelSettings(include_usage=True)` 를 전달하세요. +LiteLLM 응답으로 Agents SDK 사용량 지표를 채우려면 에이전트를 만들 때 `ModelSettings(include_usage=True)` 를 전달하세요. ```python from agents import Agent, ModelSettings @@ -91,4 +91,4 @@ agent = Agent( ) ``` -`include_usage=True` 인 경우, LiteLLM 요청은 기본 제공 OpenAI 모델과 마찬가지로 `result.context_wrapper.usage` 를 통해 토큰 및 요청 수를 보고합니다. \ No newline at end of file +`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 index b98a1e2c3..d030191e0 100644 --- a/docs/ko/multi_agent.md +++ b/docs/ko/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 멀티 에이전트 오케스트레이션 -오케스트레이션은 앱에서 에이전트가 흐르는 방식을 말합니다. 어떤 에이전트가 어떤 순서로 실행되며, 다음에 무엇을 할지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 방법은 두 가지가 있습니다: +오케스트레이션은 앱에서 에이전트가 흐르는 방식을 의미합니다. 어떤 에이전트가 어떤 순서로 실행되고, 다음에 무엇을 할지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 방법은 두 가지가 있습니다: -1. LLM이 결정하도록 하기: LLM의 지능을 사용해 계획하고 추론하여 다음에 취할 단계를 결정 -2. 코드로 오케스트레이션하기: 코드로 에이전트의 흐름을 결정 +1. LLM 에게 결정을 맡기기: LLM 의 지능을 활용해 계획하고 추론하며 그에 따라 수행할 단계를 결정합니다 +2. 코드로 오케스트레이션하기: 코드로 에이전트의 흐름을 결정합니다 -이 패턴들은 혼합하여 사용할 수 있습니다. 각 방식에는 아래에 설명된 트레이드오프가 있습니다. +이 두 패턴을 혼합하여 사용할 수 있습니다. 각각의 트레이드오프는 아래에 설명합니다. -## LLM 기반 오케스트레이션 +## LLM 을 통한 오케스트레이션 -에이전트는 지침, 도구, 핸드오프로 무장한 LLM입니다. 이는 개방형 작업이 주어졌을 때, LLM이 도구를 사용해 행동하고 데이터를 획득하며, 핸드오프를 사용해 하위 에이전트에 작업을 위임함으로써 작업을 수행할 방법을 자율적으로 계획할 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: +에이전트는 instructions, tools 및 핸드오프로 장착된 LLM 입니다. 이는 개방형 작업이 주어지면 LLM 이 도구를 사용해 행동하고 데이터를 수집하며, 핸드오프를 통해 하위 에이전트에 작업을 위임하면서 스스로 작업을 해결하는 계획을 세울 수 있음을 의미합니다. 예를 들어, 리서치 에이전트는 다음과 같은 도구를 갖출 수 있습니다: -- 웹 검색으로 온라인에서 정보 찾기 -- 파일 검색과 검색으로 독점 데이터와 연결에서 탐색 -- 컴퓨터 사용으로 컴퓨터에서 행동 수행 -- 코드 실행으로 데이터 분석 수행 -- 계획 수립, 보고서 작성 등에 능숙한 특화 에이전트로의 핸드오프 +- 온라인에서 정보를 찾기 위한 웹 검색 +- 독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색 +- 컴퓨터에서 작업을 수행하기 위한 컴퓨터 사용 +- 데이터 분석을 위한 코드 실행 +- 기획, 보고서 작성 등 특정 작업에 뛰어난 특화된 에이전트로의 핸드오프 -이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고 싶을 때 적합합니다. 여기서 가장 중요한 전술은 다음과 같습니다: +이 패턴은 작업이 개방형이고 LLM 의 지능에 의존하고자 할 때 유용합니다. 여기서 가장 중요한 전술은 다음과 같습니다: -1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용하는 방법, 그리고 준수해야 하는 매개변수를 명확히 하세요. -2. 앱을 모니터링하고 반복적으로 개선하세요. 문제가 발생하는 지점을 확인하고 프롬프트를 개선하세요. -3. 에이전트가 자기 성찰하고 개선하도록 하세요. 예를 들어 루프에서 실행하여 스스로 비판하게 하거나, 오류 메시지를 제공해 개선하도록 하세요. -4. 모든 것을 잘하는 범용 에이전트보다 하나의 작업에 뛰어난 특화 에이전트를 두세요. -5. [평가 (evals)](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 훈련해 지속적으로 개선하고 작업에 더 능숙해지게 할 수 있습니다. +1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 그리고 준수해야 할 매개변수를 명확히 하세요 +2. 앱을 모니터링하고 반복 개선하세요. 어디서 문제가 발생하는지 확인하고 프롬프트를 개선하세요 +3. 에이전트가 자기 성찰하고 개선하도록 하세요. 예를 들어 루프로 실행해 스스로 비판하게 하거나, 오류 메시지를 제공해 개선하게 하세요 +4. 모든 것을 잘하려는 범용 에이전트 대신 한 가지 작업에 특화된 에이전트를 두세요 +5. [평가(evals)](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 학습시켜 작업 성능을 향상시킬 수 있습니다 ## 코드 기반 오케스트레이션 -LLM 기반 오케스트레이션이 강력하긴 하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정적이고 예측 가능하게 만듭니다. 여기서 흔한 패턴은 다음과 같습니다: +LLM 기반 오케스트레이션이 강력하긴 하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 더 결정론적이고 예측 가능합니다. 일반적인 패턴은 다음과 같습니다: -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성. 예를 들어, 에이전트에게 작업을 몇 가지 카테고리로 분류하도록 요청한 다음, 카테고리에 따라 다음 에이전트를 선택할 수 있습니다. -- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝. 블로그 포스트 작성 같은 작업을 연구, 개요 작성, 본문 작성, 비판, 개선의 일련의 단계로 분해할 수 있습니다. -- 특정 기준을 통과한다고 평가자가 판단할 때까지, 작업을 수행하는 에이전트와 평가 및 피드백을 제공하는 에이전트를 `while` 루프로 실행 -- `asyncio.gather` 같은 Python 기본 구성 요소를 통해 여러 에이전트를 병렬 실행. 서로 의존하지 않는 여러 작업이 있을 때 속도에 유용합니다. +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성합니다. 예를 들어, 에이전트에게 작업을 몇 개의 카테고리로 분류하게 한 다음, 해당 카테고리에 따라 다음 에이전트를 선택할 수 있습니다 +- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환하여 여러 에이전트를 체이닝합니다. 블로그 글 작성 같은 작업을 리서치, 개요 작성, 본문 작성, 비판, 개선의 일련의 단계로 분해할 수 있습니다 +- 작업을 수행하는 에이전트와 평가 및 피드백을 제공하는 에이전트를 `while` 루프로 함께 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복합니다 +- `asyncio.gather` 같은 파이썬의 기본 컴포넌트를 통해 여러 에이전트를 병렬로 실행합니다. 서로 의존하지 않는 여러 작업이 있을 때 속도에 유리합니다 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에서 여러 예제를 제공하고 있습니다. \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 코드 예제가 있습니다. \ No newline at end of file diff --git a/docs/ko/quickstart.md b/docs/ko/quickstart.md index e3f0fe930..c55334cc3 100644 --- a/docs/ko/quickstart.md +++ b/docs/ko/quickstart.md @@ -4,7 +4,7 @@ search: --- # 빠른 시작 -## 프로젝트와 가상 환경 생성 +## 프로젝트 및 가상 환경 생성 한 번만 수행하면 됩니다. @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API 키 설정 -아직 없다면 OpenAI API 키를 생성하려면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따르세요. +아직 없다면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)을 따라 OpenAI API 키를 생성하세요. ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 첫 에이전트 생성 -에이전트는 instructions, 이름, 그리고 선택적 구성(`model_config` 등)으로 정의합니다 +에이전트는 instructions, 이름, 선택적 구성(예: `model_config`)으로 정의됩니다 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## 에이전트 추가 +## 에이전트 몇 개 더 추가 -추가 에이전트도 동일한 방식으로 정의할 수 있습니다. `handoff_descriptions` 는 핸드오프 라우팅을 결정하는 데 추가 컨텍스트를 제공합니다 +추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_descriptions`는 핸드오프 라우팅을 결정하는 데 추가 컨텍스트를 제공합니다 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## 핸드오프 정의 -각 에이전트에서, 작업을 진행하는 방법을 결정하기 위해 선택할 수 있는 아웃바운드 핸드오프 옵션의 인벤토리를 정의할 수 있습니다. +각 에이전트에서 작업을 진행하는 방법을 결정할 때 선택할 수 있는 아웃바운드 핸드오프 옵션 목록을 정의할 수 있습니다. ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## 에이전트 오케스트레이션 실행 -워크플로가 실행되고 트리아지 에이전트가 두 전문 에이전트 사이를 올바르게 라우팅하는지 확인해 봅시다. +워크플로가 실행되고 트리아지 에이전트가 두 전문 에이전트 간에 올바르게 라우팅하는지 확인해 봅시다. ```python from agents import Runner @@ -95,7 +95,7 @@ async def main(): ## 가드레일 추가 -입력 또는 출력에 실행할 사용자 지정 가드레일을 정의할 수 있습니다. +입력 또는 출력에 대해 실행할 사용자 지정 가드레일을 정의할 수 있습니다. ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 전체 통합 +## 통합 실행 -모든 것을 합쳐 핸드오프와 입력 가드레일을 사용해 전체 워크플로를 실행해 봅시다. +모든 것을 한데 모아 핸드오프와 입력 가드레일을 사용해 전체 워크플로를 실행해 봅시다. ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -192,12 +192,12 @@ if __name__ == "__main__": ## 트레이스 보기 -에이전트 실행 중에 발생한 내용을 검토하려면 [OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하여 에이전트 실행의 트레이스를 확인하세요. +에이전트 실행 중에 발생한 내용을 검토하려면 [OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하여 실행 트레이스를 확인하세요. ## 다음 단계 -더 복잡한 에이전트 플로를 구성하는 방법을 알아보세요: +더 복잡한 에이전틱 플로우를 구축하는 방법을 알아보세요: -- Learn about how to configure [에이전트](agents.md). -- Learn about [에이전트 실행](running_agents.md). -- Learn about [tools](tools.md), [가드레일](guardrails.md) and [모델](models/index.md). \ No newline at end of file +- [Agents](agents.md)를 구성하는 방법 알아보기. +- [에이전트 실행](running_agents.md)에 대해 알아보기. +- [tools](tools.md), [guardrails](guardrails.md), [models](models/index.md)에 대해 알아보기. \ No newline at end of file diff --git a/docs/ko/realtime/guide.md b/docs/ko/realtime/guide.md index da5e956ee..c5120f6e5 100644 --- a/docs/ko/realtime/guide.md +++ b/docs/ko/realtime/guide.md @@ -4,14 +4,14 @@ search: --- # 가이드 -이 가이드는 OpenAI Agents SDK의 실시간 기능을 사용하여 음성 지원 AI 에이전트를 구축하는 방법을 자세히 설명합니다. +이 가이드는 OpenAI Agents SDK의 실시간 기능을 사용해 음성 지원 AI 에이전트를 구축하는 방법을 자세히 설명합니다. -!!! warning "베타 기능" -실시간 에이전트는 베타 단계입니다. 구현을 개선하는 동안 호환성이 깨지는 변경이 발생할 수 있습니다. +!!! warning "Beta feature" +실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 호환성 깨짐이 발생할 수 있습니다. ## 개요 -실시간 에이전트는 실시간으로 오디오와 텍스트 입력을 처리하고 실시간 오디오로 응답하는 대화형 흐름을 제공합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 지연이 낮은 자연스러운 음성 대화를 가능하게 하고, 인터럽션(중단 처리)을 우아하게 처리합니다. +실시간 에이전트는 실시간으로 오디오와 텍스트 입력을 처리하고 실시간 오디오로 응답하는 대화형 흐름을 제공합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 낮은 지연으로 자연스러운 음성 대화를 가능하게 하고, **인터럽션(중단 처리)**에도 유연하게 대응합니다. ## 아키텍처 @@ -19,44 +19,44 @@ search: 실시간 시스템은 다음과 같은 주요 구성 요소로 이루어져 있습니다: -- **RealtimeAgent**: instructions, tools, handoffs 로 구성된 에이전트 -- **RealtimeRunner**: 구성을 관리합니다. `runner.run()`을 호출하여 세션을 가져올 수 있습니다. -- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 만들고, 대화가 끝날 때까지 유지합니다. +- **RealtimeAgent**: instructions, 도구, 핸드오프로 구성된 에이전트 +- **RealtimeRunner**: 구성 관리를 담당합니다. `runner.run()`을 호출해 세션을 가져올 수 있습니다 +- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 만들고 대화가 끝날 때까지 유지합니다 - **RealtimeModel**: 기본 모델 인터페이스(일반적으로 OpenAI의 WebSocket 구현) ### 세션 흐름 -일반적인 실시간 세션은 다음 흐름을 따릅니다: +일반적인 실시간 세션 흐름은 다음과 같습니다: -1. instructions, tools, handoffs 를 사용하여 **RealtimeAgent를 생성**합니다 -2. 에이전트와 구성 옵션으로 **RealtimeRunner를 설정**합니다 -3. `await runner.run()`을 사용해 **세션을 시작**합니다. RealtimeSession 을 반환합니다 -4. `send_audio()` 또는 `send_message()`를 사용해 세션에 **오디오 또는 텍스트 메시지 전송**합니다 -5. 세션을 반복(iterate)하여 **이벤트 수신**을 처리합니다 - 오디오 출력, 음성 인식 결과, 도구 호출, 핸드오프, 에러 등이 포함됩니다 -6. 사용자가 에이전트의 발화를 가로챌 때 **인터럽션(중단 처리)을 처리**합니다. 현재 오디오 생성이 자동으로 중지됩니다 +1. **RealtimeAgent 생성**: instructions, 도구, 핸드오프로 구성합니다 +2. **RealtimeRunner 설정**: 에이전트와 구성 옵션을 설정합니다 +3. **세션 시작**: `await runner.run()`을 사용해 RealtimeSession을 반환받습니다 +4. **오디오 또는 텍스트 전송**: `send_audio()` 또는 `send_message()`를 사용해 세션으로 전송합니다 +5. **이벤트 수신**: 세션을 이터레이션하여 이벤트를 청취합니다 — 이벤트에는 오디오 출력, 전사, 도구 호출, 핸드오프, 오류가 포함됩니다 +6. **인터럽션 처리**: 사용자가 에이전트 말 중에 말하면 현재 오디오 생성이 자동으로 중단됩니다 -세션은 대화 기록을 유지하고 실시간 모델과의 지속적인 연결을 관리합니다. +세션은 대화 기록을 유지하고 실시간 모델과의 지속 연결을 관리합니다. ## 에이전트 구성 -RealtimeAgent 는 일반 Agent 클래스와 유사하게 동작하나 몇 가지 차이가 있습니다. 전체 API 세부 정보는 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 레퍼런스를 참조하세요. +RealtimeAgent는 기본 Agent 클래스와 유사하게 작동하되 몇 가지 차이가 있습니다. 전체 API 세부 정보는 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 레퍼런스를 참조하세요. -일반 에이전트와의 주요 차이점: +기본 에이전트와의 주요 차이점: -- 모델 선택은 에이전트 레벨이 아니라 세션 레벨에서 구성됩니다 -- structured output 지원이 없습니다(`outputType`은 지원되지 않음) -- 음성은 에이전트별로 구성할 수 있으나, 최초 에이전트가 말한 후에는 변경할 수 없습니다 -- tools, handoffs, instructions 등 기타 기능은 동일하게 동작합니다 +- 모델 선택은 에이전트 레벨이 아니라 세션 레벨에서 구성합니다 +- structured outputs 지원 없음(`outputType` 미지원) +- 음성은 에이전트별로 구성할 수 있지만 첫 번째 에이전트가 말한 후에는 변경할 수 없음 +- 도구, 핸드오프, instructions 같은 다른 기능은 동일하게 동작 ## 세션 구성 ### 모델 설정 -세션 구성으로 기본 실시간 모델의 동작을 제어할 수 있습니다. 모델 이름(예: `gpt-realtime`), 음성 선택(alloy, echo, fable, onyx, nova, shimmer), 지원 모달리티(텍스트 및/또는 오디오)를 구성할 수 있습니다. 오디오 포맷은 입력과 출력 모두 설정할 수 있으며 기본값은 PCM16 입니다. +세션 구성으로 기본 실시간 모델 동작을 제어할 수 있습니다. 모델 이름(예: `gpt-realtime`), 음성 선택(alloy, echo, fable, onyx, nova, shimmer), 지원 모달리티(텍스트 및/또는 오디오)를 설정할 수 있습니다. 오디오 포맷은 입력과 출력 모두에 대해 설정할 수 있으며 기본값은 PCM16입니다. ### 오디오 구성 -오디오 설정은 세션이 음성 입력과 출력을 처리하는 방식을 제어합니다. Whisper 같은 모델을 사용한 입력 오디오 음성 인식, 언어 환경설정, 도메인 특화 용어의 정확도를 높이기 위한 인식 프롬프트를 구성할 수 있습니다. 턴 감지 설정은 에이전트가 언제 응답을 시작하고 중지할지 제어하며, 음성 활동 감지 임계값, 무음 지속 시간, 감지된 음성 주변 패딩 옵션을 제공합니다. +오디오 설정은 세션이 음성 입력과 출력을 처리하는 방식을 제어합니다. Whisper 같은 모델을 사용한 입력 오디오 전사, 선호 언어, 도메인 특화 용어의 정확도를 높이기 위한 전사 프롬프트를 구성할 수 있습니다. 턴 감지 설정을 통해 에이전트가 언제 응답을 시작하고 멈춰야 하는지 제어하며, 음성 활동 감지 임계값, 무음 지속 시간, 감지된 음성 주변 패딩 등의 옵션을 제공합니다. ## 도구와 함수 @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### 핸드오프 생성 -핸드오프를 통해 특화된 에이전트 간에 대화를 전환할 수 있습니다. +핸드오프는 특화된 에이전트 간에 대화를 전달할 수 있게 해줍니다. ```python from agents.realtime import realtime_handoff @@ -119,20 +119,20 @@ main_agent = RealtimeAgent( ## 이벤트 처리 -세션은 세션 객체를 반복(iterate)하여 수신할 수 있는 이벤트 스트림을 제공합니다. 이벤트에는 오디오 출력 청크, 음성 인식 결과, 도구 실행 시작/종료, 에이전트 핸드오프, 에러가 포함됩니다. 처리해야 할 주요 이벤트는 다음과 같습니다: +세션은 세션 객체를 이터레이션하여 청취할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작/종료, 에이전트 핸드오프, 오류가 포함됩니다. 처리해야 할 주요 이벤트는 다음과 같습니다: - **audio**: 에이전트 응답의 원시 오디오 데이터 -- **audio_end**: 에이전트 발화 종료 -- **audio_interrupted**: 사용자가 에이전트를 중단 +- **audio_end**: 에이전트가 말하기를 완료함 +- **audio_interrupted**: 사용자가 에이전트를 중단함 - **tool_start/tool_end**: 도구 실행 라이프사이클 - **handoff**: 에이전트 핸드오프 발생 - **error**: 처리 중 오류 발생 -전체 이벤트 세부 정보는 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]를 참조하세요. +전체 이벤트 상세는 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]를 참조하세요. ## 가드레일 -실시간 에이전트는 출력 가드레일만 지원합니다. 이러한 가드레일은 성능 문제를 피하기 위해 실시간 생성 중 매 단어마다가 아니라 디바운싱되어 주기적으로 실행됩니다. 기본 디바운스 길이는 100자이며, 구성 가능합니다. +실시간 에이전트는 출력 가드레일만 지원합니다. 이러한 가드레일은 성능 문제를 피하기 위해 매 단어마다가 아니라 주기적으로 디바운스되어 실행됩니다. 기본 디바운스 길이는 100자이며, 설정 가능합니다. 가드레일은 `RealtimeAgent`에 직접 연결하거나 세션의 `run_config`를 통해 제공할 수 있습니다. 두 소스의 가드레일은 함께 실행됩니다. @@ -152,19 +152,19 @@ agent = RealtimeAgent( ) ``` -가드레일이 트리거되면 `guardrail_tripped` 이벤트를 생성하고 에이전트의 현재 응답을 중단할 수 있습니다. 디바운스 동작은 안전성과 실시간 성능 요구 사이의 균형을 돕습니다. 텍스트 에이전트와 달리, 실시간 에이전트는 가드레일이 작동해도 Exception 을 발생시키지 않습니다. +가드레일이 트리거되면 `guardrail_tripped` 이벤트를 생성하고 에이전트의 현재 응답을 인터럽트할 수 있습니다. 디바운스 동작은 안전성과 실시간 성능 요구사항 간의 균형을 맞추는 데 도움이 됩니다. 텍스트 에이전트와 달리, 실시간 에이전트는 가드레일이 트리거되어도 Exception을 발생시키지 않습니다. ## 오디오 처리 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio]를 사용해 오디오를 세션으로 보내거나, [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용해 텍스트를 보낼 수 있습니다. +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio]를 사용해 세션으로 오디오를 보내거나, [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용해 텍스트를 보냅니다. -오디오 출력을 위해서는 `audio` 이벤트를 수신하고 선호하는 오디오 라이브러리로 오디오 데이터를 재생하세요. 사용자가 에이전트를 중단할 때 즉시 재생을 중지하고 대기열의 오디오를 모두 비우려면 `audio_interrupted` 이벤트를 반드시 수신하세요. +오디오 출력을 위해서는 `audio` 이벤트를 청취하고 선호하는 오디오 라이브러리를 통해 오디오 데이터를 재생하세요. 사용자가 에이전트를 중단할 때 즉시 재생을 중지하고 대기 중인 오디오를 모두 지우기 위해 `audio_interrupted` 이벤트를 반드시 청취하세요. ## SIP 통합 -[Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip)로 들어오는 전화에 실시간 에이전트를 연결할 수 있습니다. SDK는 SIP 상에서 미디어를 협상하면서 동일한 에이전트 흐름을 재사용하는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]을 제공합니다. +[Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip)로 수신되는 전화 통화에 실시간 에이전트를 연결할 수 있습니다. SDK는 SIP를 통해 미디어를 협상하면서 동일한 에이전트 흐름을 재사용하는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]을 제공합니다. -사용하려면, 모델 인스턴스를 러너에 전달하고 세션 시작 시 SIP `call_id`를 제공하세요. 호출 ID는 수신 전화를 알리는 웹훅으로 전달됩니다. +사용하려면 모델 인스턴스를 러너에 전달하고 세션을 시작할 때 SIP `call_id`를 제공하세요. 통화 ID는 수신 전화를 알리는 웹훅으로 전달됩니다. ```python from agents.realtime import RealtimeAgent, RealtimeRunner @@ -191,7 +191,7 @@ async with await runner.run( ## 모델 직접 액세스 -하위 수준 리스너를 추가하거나 고급 작업을 수행하기 위해 기본 모델에 액세스할 수 있습니다: +기본 모델에 접근하여 커스텀 리스너를 추가하거나 고급 작업을 수행할 수 있습니다: ```python # Add a custom listener to the model @@ -202,4 +202,4 @@ session.model.add_listener(my_custom_listener) ## 코드 예제 -완전한 동작 코드 예제는 [examples/realtime 디렉터리](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)를 확인하세요. UI 구성 요소가 있는 데모와 없는 데모가 포함되어 있습니다. \ No newline at end of file +완전한 동작 코드 예제는 [examples/realtime 디렉터리](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)를 참고하세요. UI 구성 요소가 있는 데모와 없는 데모가 모두 포함되어 있습니다. \ No newline at end of file diff --git a/docs/ko/realtime/quickstart.md b/docs/ko/realtime/quickstart.md index ff508505d..af6ef20d6 100644 --- a/docs/ko/realtime/quickstart.md +++ b/docs/ko/realtime/quickstart.md @@ -4,28 +4,28 @@ search: --- # 빠른 시작 -실시간 에이전트는 OpenAI의 Realtime API를 사용해 AI 에이전트와 음성 대화를 가능하게 합니다. 이 가이드는 첫 번째 실시간 음성 에이전트를 만드는 과정을 안내합니다. +실시간 에이전트는 OpenAI의 Realtime API 를 사용하여 AI 에이전트와 음성 대화를 가능하게 합니다. 이 가이드는 첫 실시간 음성 에이전트를 만드는 과정을 안내합니다. !!! warning "베타 기능" -실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 호환성 문제가 발생할 수 있습니다. +실시간 에이전트는 베타 단계입니다. 구현이 개선되는 동안 일부 호환성 문제가 발생할 수 있습니다. ## 사전 준비 - Python 3.9 이상 -- OpenAI API key -- OpenAI Agents SDK에 대한 기본적인 이해 +- OpenAI API 키 +- OpenAI Agents SDK 에 대한 기본 이해 ## 설치 -아직 설치하지 않았다면 OpenAI Agents SDK를 설치하세요: +아직 설치하지 않았다면 OpenAI Agents SDK 를 설치하세요: ```bash pip install openai-agents ``` -## 첫 번째 실시간 에이전트 만들기 +## 첫 실시간 에이전트 생성 -### 1. 필요한 구성 요소 가져오기 +### 1. 필요한 구성요소 임포트 ```python import asyncio @@ -111,7 +111,7 @@ def _truncate_str(s: str, max_length: int) -> str: ## 전체 예제 -다음은 완전한 작동 예제입니다: +다음은 완전하게 동작하는 예제입니다: ```python import asyncio @@ -194,13 +194,13 @@ if __name__ == "__main__": - `model_name`: 사용 가능한 실시간 모델에서 선택 (예: `gpt-realtime`) - `voice`: 음성 선택 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: 텍스트 또는 오디오 활성화 (`["text"]` 또는 `["audio"]`) +- `modalities`: 텍스트 또는 오디오 사용 (`["text"]` 또는 `["audio"]`) ### 오디오 설정 - `input_audio_format`: 입력 오디오 형식 (`pcm16`, `g711_ulaw`, `g711_alaw`) - `output_audio_format`: 출력 오디오 형식 -- `input_audio_transcription`: 전사 설정 +- `input_audio_transcription`: 전사 구성 ### 턴 감지 @@ -211,15 +211,15 @@ if __name__ == "__main__": ## 다음 단계 -- [실시간 에이전트에 대해 더 알아보기](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 폴더에서 작동하는 예제 코드를 확인하세요 +- [실시간 에이전트 더 알아보기](guide.md) +- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 폴더의 동작하는 code examples 확인 - 에이전트에 도구 추가 - 에이전트 간 핸드오프 구현 - 안전을 위한 가드레일 설정 ## 인증 -환경 변수에 OpenAI API key가 설정되어 있는지 확인하세요: +환경 변수에 OpenAI API 키가 설정되어 있는지 확인하세요: ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/ko/release.md b/docs/ko/release.md index 72130a96c..bf2ac5877 100644 --- a/docs/ko/release.md +++ b/docs/ko/release.md @@ -4,40 +4,40 @@ search: --- # 릴리스 프로세스/변경 로그 -이 프로젝트는 `0.Y.Z` 형식의 약간 수정된 시맨틱 버전 관리를 따릅니다. 선행 `0`은 SDK가 아직 빠르게 발전 중임을 의미합니다. 각 구성 요소는 다음과 같이 증가합니다: +이 프로젝트는 `0.Y.Z` 형식의 시맨틱 버저닝을 약간 수정해 따릅니다. 선행 `0`은 SDK 가 아직 빠르게 발전 중임을 나타냅니다. 각 구성 요소는 다음과 같이 증가합니다: -## 부( `Y` ) 버전 +## 부 버전(`Y`) -베타로 표시되지 않은 모든 퍼블릭 인터페이스에 **호환성 파괴 변경(breaking changes)** 이 있을 때 부 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 올라갈 때 호환성 파괴 변경이 포함될 수 있습니다. +베타로 표시되지 않은 모든 공개 인터페이스에 **호환성 파괴 변경**이 있을 때 부 버전 `Y`를 올립니다. 예를 들어, `0.0.x`에서 `0.1.x`로 올라갈 때 브레이킹 체인지가 포함될 수 있습니다. -호환성 파괴 변경을 원하지 않으면, 프로젝트에서 `0.0.x` 버전에 고정할 것을 권장합니다. +브레이킹 체인지를 원하지 않는 경우, 프로젝트에서 `0.0.x` 버전에 고정하는 것을 권장합니다. -## 패치( `Z` ) 버전 +## 패치(`Z`) 버전 -호환성을 깨지 않는 변경에는 `Z`를 증가시킵니다: +호환성에 영향을 주지 않는 변경에 대해 `Z`를 올립니다: - 버그 수정 -- 새로운 기능 -- 프라이빗 인터페이스 변경 +- 신규 기능 +- 비공개 인터페이스 변경 - 베타 기능 업데이트 ## 호환성 파괴 변경 로그 ### 0.6.0 -이 버전에서는 기본 핸드오프 기록이 사용자/assistant 턴의 원문을 노출하는 대신 하나의 assistant 메시지로 묶여, 다운스트림 에이전트에게 간결하고 예측 가능한 요약을 제공합니다 -- 기존의 단일 메시지 핸드오프 대화록은 이제 기본적으로 `` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하여, 다운스트림 에이전트가 명확하게 라벨링된 요약을 받도록 합니다 +이 버전에서는 기본 핸드오프 히스토리가 원문 사용자/assistant 턴을 노출하는 대신 단일 assistant 메시지에 패키징되어, 다운스트림 에이전트에 간결하고 예측 가능한 요약을 제공합니다 +- 기존의 단일 메시지 핸드오프 기록은 이제 기본적으로 `` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하여, 다운스트림 에이전트가 명확하게 라벨링된 요약을 받도록 합니다 ### 0.5.0 -이 버전은 눈에 보이는 호환성 파괴 변경을 도입하지 않지만, 새로운 기능과 내부적으로 몇 가지 중요한 업데이트를 포함합니다: +이 버전은 눈에 띄는 브레이킹 체인지는 도입하지 않지만, 신규 기능과 내부의 몇 가지 중요한 업데이트를 포함합니다: - `RealtimeRunner`가 [SIP protocol connections](https://platform.openai.com/docs/guides/realtime-sip)을 처리하도록 지원 추가 - Python 3.14 호환성을 위해 `Runner#run_sync`의 내부 로직을 대폭 수정 ### 0.4.0 -이 버전에서는 [openai](https://pypi.org/project/openai/) 패키지 v1.x 버전을 더 이상 지원하지 않습니다. 이 SDK와 함께 openai v2.x를 사용하세요. +이 버전부터 [openai](https://pypi.org/project/openai/) 패키지 v1.x 버전은 더 이상 지원되지 않습니다. 이 SDK 와 함께 openai v2.x 를 사용하세요. ### 0.3.0 @@ -45,8 +45,8 @@ search: ### 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` 두 개의 새로운 매개변수가 추가되었습니다. `MCPServer`를 상속하는 모든 클래스에 이 매개변수를 추가해야 합니다. \ No newline at end of file +이 버전에서 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 `run_context` 와 `agent` 두 매개변수가 추가되었습니다. `MCPServer` 를 상속하는 모든 클래스에 이 매개변수를 추가해야 합니다. \ No newline at end of file diff --git a/docs/ko/repl.md b/docs/ko/repl.md index ec8435971..b615bbbf8 100644 --- a/docs/ko/repl.md +++ b/docs/ko/repl.md @@ -4,8 +4,7 @@ search: --- # REPL 유틸리티 -SDK는 터미널에서 에이전트의 동작을 빠르고 인터랙티브하게 테스트할 수 있도록 `run_demo_loop`를 제공합니다. - +SDK는 터미널에서 에이전트의 동작을 빠르고 대화형으로 테스트할 수 있도록 `run_demo_loop`를 제공합니다. ```python import asyncio @@ -19,6 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop`는 루프에서 사용자 입력을 요청하며, 턴 사이의 대화 기록을 유지합니다. 기본적으로 생성되는 대로 모델 출력을 스트리밍합니다. 위의 예제를 실행하면, run_demo_loop가 인터랙티브 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 사이의 전체 대화 기록을 기억해 에이전트가 어떤 대화가 오갔는지 알 수 있게 하며, 생성되는 즉시 에이전트의 응답을 실시간으로 자동 스트리밍합니다. +`run_demo_loop`는 루프에서 사용자 입력을 요청하며, 턴 간 대화 기록을 유지합니다. 기본적으로 생성되는 대로 모델 출력을 스트리밍합니다. 위 예제를 실행하면 run_demo_loop가 대화형 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 간 전체 대화 기록을 기억하여(에이전트가 어떤 대화가 오갔는지 알 수 있도록) 생성되는 즉시 에이전트의 응답을 실시간으로 자동 스트리밍합니다. 이 채팅 세션을 종료하려면 `quit` 또는 `exit`를 입력하고 Enter 키를 누르거나 `Ctrl-D` 키보드 단축키를 사용하세요. \ No newline at end of file diff --git a/docs/ko/results.md b/docs/ko/results.md index 7bb5d3c91..cb800d472 100644 --- a/docs/ko/results.md +++ b/docs/ko/results.md @@ -6,10 +6,10 @@ search: `Runner.run` 메서드를 호출하면 다음 중 하나를 받습니다: -- [`RunResult`][agents.result.RunResult] 는 `run` 또는 `run_sync` 를 호출한 경우 -- [`RunResultStreaming`][agents.result.RunResultStreaming] 는 `run_streamed` 를 호출한 경우 +- [`RunResult`][agents.result.RunResult] 를 `run` 또는 `run_sync` 를 호출한 경우 +- [`RunResultStreaming`][agents.result.RunResultStreaming] 를 `run_streamed` 를 호출한 경우 -이 둘은 모두 [`RunResultBase`][agents.result.RunResultBase] 를 상속하며, 대부분의 유용한 정보가 여기에 있습니다. +이 둘은 모두 [`RunResultBase`][agents.result.RunResultBase] 를 상속하며, 대부분의 유용한 정보는 여기에 포함되어 있습니다. ## 최종 출력 @@ -20,19 +20,19 @@ search: !!! note - `final_output` 의 타입은 `Any` 입니다. 핸드오프 때문에 정적으로 타입을 지정할 수 없습니다. 핸드오프가 발생하면 어떤 에이전트든 마지막 에이전트가 될 수 있으므로, 가능한 출력 타입의 집합을 정적으로 알 수 없습니다. + `final_output` 의 타입은 `Any` 입니다. 핸드오프 때문에 이를 정적으로 타이핑할 수 없습니다. 핸드오프가 발생하면 어떤 에이전트든 마지막 에이전트가 될 수 있으므로, 가능한 출력 타입 집합을 정적으로 알 수 없습니다. -## 다음 턴을 위한 입력 +## 다음 턴 입력 -[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 를 사용하여 결과를 입력 리스트로 변환하고, 제공한 원본 입력과 에이전트 실행 중 생성된 항목을 이어 붙일 수 있습니다. 이를 통해 한 번의 에이전트 실행 결과를 다른 실행으로 전달하거나, 루프로 실행하면서 매번 새로운 사용자 입력을 추가하기가 편리합니다. +[`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 를 사용하여 결과를 입력 리스트로 변환할 수 있습니다. 이는 여러분이 제공한 원래 입력에 에이전트 실행 중 생성된 항목을 이어붙입니다. 이를 통해 한 번의 에이전트 실행 출력을 다른 실행에 전달하거나, 루프에서 실행하며 매번 새로운 사용자 입력을 추가하기가 편리합니다. ## 마지막 에이전트 -[`last_agent`][agents.result.RunResultBase.last_agent] 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음에 사용자가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 에이전트에 메시지를 보낼 때 재사용할 수 있습니다. +[`last_agent`][agents.result.RunResultBase.last_agent] 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라, 이는 다음번에 사용자 입력이 들어올 때 유용한 경우가 많습니다. 예를 들어, 1차 분류 에이전트가 언어별 에이전트로 핸드오프하는 구조라면, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다. ## 새 항목 -[`new_items`][agents.result.RunResultBase.new_items] 속성에는 실행 중에 생성된 새 항목이 포함됩니다. 항목은 [`RunItem`][agents.items.RunItem] 입니다. 실행 항목은 LLM 이 생성한 원문 항목을 래핑합니다. +[`new_items`][agents.result.RunResultBase.new_items] 속성에는 실행 중 생성된 새 항목이 들어 있습니다. 항목은 [`RunItem`][agents.items.RunItem] 들입니다. 실행 항목은 LLM 이 생성한 원문 항목을 래핑합니다. - [`MessageOutputItem`][agents.items.MessageOutputItem] 은 LLM 의 메시지를 나타냅니다. 원문 항목은 생성된 메시지입니다 - [`HandoffCallItem`][agents.items.HandoffCallItem] 은 LLM 이 핸드오프 도구를 호출했음을 나타냅니다. 원문 항목은 LLM 의 도구 호출 항목입니다 @@ -45,12 +45,12 @@ search: ### 가드레일 결과 -[`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_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/ko/running_agents.md b/docs/ko/running_agents.md index b2ffb4e57..f627715fc 100644 --- a/docs/ko/running_agents.md +++ b/docs/ko/running_agents.md @@ -4,11 +4,11 @@ search: --- # 에이전트 실행 -[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 선택지는 3가지입니다: +[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 방법은 3가지입니다: -1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult] 를 반환합니다 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드로, 내부적으로 `.run()` 을 실행합니다 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환합니다. LLM 을 스트리밍 모드로 호출하고, 수신되는 대로 이벤트를 스트리밍합니다 +1. 비동기로 실행하고 [`RunResult`][agents.result.RunResult] 를 반환하는 [`Runner.run()`][agents.run.Runner.run] +2. 동기 메서드로, 내부적으로 `.run()` 을 실행하는 [`Runner.run_sync()`][agents.run.Runner.run_sync] +3. 비동기로 실행하고 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환하는 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]. LLM 을 스트리밍 모드로 호출하며, 수신되는 대로 이벤트를 스트리밍합니다 ```python from agents import Agent, Runner @@ -27,11 +27,11 @@ async def main(): ## 에이전트 루프 -`Runner` 의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API 의 입력 아이템 목록이 될 수 있습니다. +`Runner` 의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주됨) 또는 OpenAI Responses API 의 항목 리스트(입력 아이템 리스트)일 수 있습니다. -러너는 다음과 같은 루프를 실행합니다: +런너는 다음 루프를 실행합니다: -1. 현재 입력과 함께 현재 에이전트에 대해 LLM 을 호출합니다 +1. 현재 입력으로 현재 에이전트에 대해 LLM 을 호출합니다 2. LLM 이 출력을 생성합니다 1. LLM 이 `final_output` 을 반환하면 루프가 종료되고 결과를 반환합니다 2. LLM 이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 다시 실행합니다 @@ -40,42 +40,42 @@ async def main(): !!! 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] 문서를 참조하세요 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: `True`(기본값) 인 경우, 러너는 다음 에이전트를 호출하기 전에 이전 대화를 하나의 assistant 메시지로 접습니다. 도우미는 콘텐츠를 `` 블록 안에 배치하고 이후 핸드오프가 발생할 때마다 새 턴을 계속 추가합니다. 원문(transcript)을 그대로 전달하려면 이를 `False` 로 설정하거나 원하는 대로 대화를 전달하는 사용자 지정 handoff 필터를 제공하세요. 모든 [`Runner` 메서드](agents.run.Runner)는 `RunConfig` 를 전달하지 않으면 자동으로 생성하므로, 빠른 시작과 code examples 는 이 기본값을 자동으로 사용하며 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백이 있으면 계속해서 이를 우선합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 를 통해 이 설정을 재정의할 수 있습니다 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` 가 `True` 일 때 정규화된 대본(히스토리 + 핸드오프 아이템)을 수신하는 선택적 호출 가능 객체. 다음 에이전트로 전달할 입력 아이템의 정확한 리스트를 반환해야 하며, 전체 handoff 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다 -- [`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] 문서를 참조 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: `True`(기본값)인 경우, 다음 에이전트를 호출하기 전에 이전 대화록을 단일 assistant 메시지로 접어 넣음. 헬퍼는 콘텐츠를 `` 블록 내부에 배치하며, 이후 핸드오프가 발생할 때마다 새 턴을 계속 추가함. 이전 동작으로 돌아가려면 `False` 로 설정하거나, 원문 대화록을 그대로 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`) 를 제공. [`Runner` 메서드](agents.run.Runner)는 `RunConfig` 를 전달하지 않으면 자동으로 생성하므로, 퀵스타트 및 code examples 는 이 기본값을 자동으로 사용하며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속해서 이를 재정의함. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 를 통해 이 설정을 재정의할 수 있음 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` 가 `True` 일 때 정규화된 대화록(히스토리 + 핸드오프 아이템)을 전달받는 선택적 호출 가능 객체. 다음 에이전트에 전달할 입력 아이템의 정확한 리스트를 반환해야 하며, 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 교체할 수 있음 +- [`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]: 모든 트레이스에 포함할 메타데이터 -기본적으로 SDK 는 이제 한 에이전트가 다른 에이전트로 핸드오프할 때 이전 턴을 단일 assistant 요약 메시지 안에 중첩합니다. 이는 반복되는 assistant 메시지를 줄이고 전체 대화를 새 에이전트가 빠르게 스캔할 수 있는 단일 블록 안에 유지합니다. 레거시 동작으로 돌아가려면 `RunConfig(nest_handoff_history=False)` 를 전달하거나, 대화를 필요한 그대로 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`) 를 제공하세요. 특정 핸드오프에 대해 옵트아웃(또는 옵트인)하려면 `handoff(..., nest_handoff_history=False)` 또는 `True` 로 설정하세요. 사용자 지정 매퍼를 작성하지 않고 생성된 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] 를 호출하세요(기본값으로 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]). +기본적으로, SDK 는 한 에이전트가 다른 에이전트로 핸드오프할 때 이전 턴을 단일 assistant 요약 메시지 내부로 중첩합니다. 이는 반복되는 assistant 메시지를 줄이고, 전체 대화록을 새 에이전트가 빠르게 스캔할 수 있는 단일 블록에 유지합니다. 레거시 동작으로 돌아가려면 `RunConfig(nest_handoff_history=False)` 를 전달하거나, 대화를 필요한 형태로 그대로 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`) 를 제공하세요. 또한 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=False)` 또는 `True` 로 선택적으로 옵트아웃(또는 옵트인)할 수 있습니다. 사용자 정의 매퍼를 작성하지 않고 생성된 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] 를 호출하세요(기본값으로 되돌리려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]). ## 대화/채팅 스레드 -어떤 run 메서드를 호출하더라도 하나 이상의 에이전트가 실행될 수 있으며(따라서 하나 이상의 LLM 호출), 채팅 대화의 단일 논리적 턴을 나타냅니다. 예: +어떤 run 메서드를 호출하더라도 하나 이상의 에이전트가 실행될 수 있으며(따라서 하나 이상의 LLM 호출이 발생), 이는 채팅 대화의 단일 논리적 턴을 나타냅니다. 예: 1. 사용자 턴: 사용자가 텍스트 입력 -2. Runner 실행: 첫 번째 에이전트가 LLM 을 호출하고 도구를 실행하고 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성 +2. 런너 실행: 첫 번째 에이전트가 LLM 을 호출하고 도구를 실행하며 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성 -에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 아이템을 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든, 사용자가 후속 질문을 할 수 있으며, 그 경우 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(): @@ -95,9 +95,9 @@ async def main(): # California ``` -### Sessions 를 통한 자동 대화 관리 +### 세션을 사용한 자동 대화 관리 -더 간단한 접근을 원한다면 [Sessions](sessions/index.md) 를 사용하여 `.to_input_list()` 를 수동 호출하지 않고 대화 기록을 자동으로 관리할 수 있습니다: +더 간단한 접근을 위해, [세션](sessions/index.md) 을 사용하면 `.to_input_list()` 를 수동으로 호출하지 않고도 대화 이력을 자동으로 처리할 수 있습니다: ```python from agents import Agent, Runner, SQLiteSession @@ -121,23 +121,24 @@ async def main(): # California ``` -Sessions 는 다음을 자동으로 수행합니다: +세션은 자동으로 다음을 수행합니다: -- 각 실행 전 대화 기록을 가져옴 -- 각 실행 후 새로운 메시지를 저장 -- 서로 다른 세션 ID 에 대해 별도의 대화를 유지 +- 각 실행 전에 대화 이력 조회 +- 각 실행 후 새 메시지 저장 +- 서로 다른 세션 ID 에 대해 별도의 대화 유지 -자세한 내용은 [Sessions 문서](sessions/index.md)에서 확인하세요. +자세한 내용은 [세션 문서](sessions/index.md) 를 참조하세요. -### 서버 관리 대화 -OpenAI 대화 상태 기능을 사용하여 `to_input_list()` 또는 `Sessions` 로 로컬에서 처리하는 대신 서버 측에서 대화 상태를 관리할 수도 있습니다. 이를 통해 과거 모든 메시지를 수동으로 다시 보내지 않고도 대화 기록을 유지할 수 있습니다. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. +### 서버 관리형 대화 + +로컬에서 `to_input_list()` 또는 `세션` 으로 처리하는 대신, OpenAI 대화 상태 기능에 대화 상태 관리를 서버 측에서 맡길 수도 있습니다. 이는 모든 과거 메시지를 수동으로 다시 보내지 않고도 대화 이력을 보존할 수 있게 해줍니다. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) 를 참조하세요. OpenAI 는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다: #### 1. `conversation_id` 사용 -먼저 OpenAI Conversations API 를 사용해 대화를 생성하고, 이후의 모든 호출에서 해당 ID 를 재사용합니다: +먼저 OpenAI Conversations API 를 사용하여 대화를 생성한 후, 이후 호출마다 해당 ID 를 재사용합니다: ```python from agents import Agent, Runner @@ -192,18 +193,19 @@ async def main(): # California ``` + ## 장기 실행 에이전트 및 휴먼인더루프 (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)에서 확인하세요. +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]: 에이전트 실행이 `max_turns` 한도를 초과하여 `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` 메서드에서 발생하는 예외입니다. 이는 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기본 모델(LLM) 이 예상치 못한 또는 유효하지 않은 출력을 생성할 때 발생합니다. 다음을 포함할 수 있습니다: - - 잘못된 JSON: 모델이 도구 호출 또는 직접 출력에 대해 잘못된 JSON 구조를 제공하는 경우, 특히 특정 `output_type` 이 정의된 경우 - - 예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못한 경우 -- [`UserError`][agents.exceptions.UserError]: SDK 를 사용하는 코드 작성자(당신)가 SDK 사용 중 오류를 범했을 때 발생합니다. 일반적으로 잘못된 코드 구현, 잘못된 구성, SDK API 오사용에서 비롯됩니다 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 각각 입력 가드레일 또는 출력 가드레일의 조건이 충족될 때 발생합니다. 입력 가드레일은 처리 전에 들어오는 메시지를 검사하고, 출력 가드레일은 전달 전에 에이전트의 최종 응답을 검사합니다 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 내에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 구체적 예외가 파생되는 일반적인 타입으로 사용됩니다 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 에이전트 실행이 `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 이는 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기반 모델(LLM) 이 예기치 않거나 잘못된 출력을 생성할 때 발생합니다. 다음을 포함할 수 있습니다: + - 잘못된 JSON: 특히 특정 `output_type` 이 정의된 경우, 모델이 도구 호출 또는 직접 출력에서 잘못된 JSON 구조를 제공하는 경우 + - 예기치 않은 도구 관련 실패: 모델이 예상 방식으로 도구를 사용하지 못하는 경우 +- [`UserError`][agents.exceptions.UserError]: SDK 를 사용하는(코드를 작성하는) 사용자가 SDK 사용 중 실수를 했을 때 발생합니다. 이는 잘못된 코드 구현, 잘못된 구성, SDK API 오용에서 비롯되는 경우가 일반적입니다 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 각각 입력 가드레일 또는 출력 가드레일 조건이 충족될 때 발생합니다. 입력 가드레일은 처리 전에 수신 메시지를 검사하고, 출력 가드레일은 에이전트의 최종 응답을 전달하기 전에 검사합니다 \ No newline at end of file diff --git a/docs/ko/sessions/advanced_sqlite_session.md b/docs/ko/sessions/advanced_sqlite_session.md index 7a0d770cc..32d55096d 100644 --- a/docs/ko/sessions/advanced_sqlite_session.md +++ b/docs/ko/sessions/advanced_sqlite_session.md @@ -4,15 +4,15 @@ search: --- # 고급 SQLite 세션 -`AdvancedSQLiteSession` 은 기본 `SQLiteSession` 을 확장한 버전으로, 대화 분기, 상세 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다. +`AdvancedSQLiteSession`은 기본 `SQLiteSession`을 확장한 버전으로, 대화 분기, 상세 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다. ## 기능 - **대화 분기**: 임의의 사용자 메시지에서 대체 대화 경로 생성 -- **사용량 추적**: 각 턴별 토큰 사용량을 JSON 전체 분해와 함께 상세 분석 -- **구조화된 쿼리**: 턴 기준 대화 조회, 도구 사용 통계 등 +- **사용량 추적**: 각 턴별 토큰 사용량에 대한 상세 분석과 전체 JSON 분해 제공 +- **구조화된 쿼리**: 턴별 대화 조회, 도구 사용 통계 등 제공 - **분기 관리**: 독립적인 분기 전환 및 관리 -- **메시지 구조 메타데이터**: 메시지 유형, 도구 사용, 대화 흐름 추적 +- **메시지 구조 메타데이터**: 메시지 타입, 도구 사용, 대화 흐름 추적 ## 빠른 시작 @@ -87,13 +87,13 @@ session = AdvancedSQLiteSession( - `session_id` (str): 대화 세션의 고유 식별자 - `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 인메모리 저장을 위해 기본값은 `:memory:` - `create_tables` (bool): 고급 테이블을 자동으로 생성할지 여부. 기본값은 `False` -- `logger` (logging.Logger | None): 세션에서 사용할 커스텀 로거. 기본값은 모듈 로거 +- `logger` (logging.Logger | None): 세션에 사용할 커스텀 로거. 기본값은 모듈 로거 ## 사용량 추적 -AdvancedSQLiteSession 은 대화의 각 턴별 토큰 사용 데이터를 저장하여 상세한 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드를 호출하는 것에 전적으로 의존합니다.** +AdvancedSQLiteSession은 대화의 각 턴별로 토큰 사용 데이터를 저장하여 상세 사용량 분석을 제공합니다. **이는 매 에이전트 실행 후 `store_run_usage` 메서드를 호출하는 것에 전적으로 의존합니다.** -### 사용량 데이터 저장 +### 사용 데이터 저장 ```python # After each agent run, store the usage data @@ -107,7 +107,7 @@ await session.store_run_usage(result) # - Detailed JSON token information (if available) ``` -### 사용량 통계 조회 +### 사용 통계 조회 ```python # Get session-level usage (all branches) @@ -137,7 +137,7 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2) ## 대화 분기 -AdvancedSQLiteSession 의 핵심 기능 중 하나는 임의의 사용자 메시지에서 대화 분기를 생성하여 대체 대화 경로를 탐색할 수 있는 능력입니다. +AdvancedSQLiteSession의 핵심 기능 중 하나는 임의의 사용자 메시지에서 대화 분기를 생성하여 대체 대화 경로를 탐색할 수 있는 능력입니다. ### 분기 생성 @@ -217,7 +217,7 @@ await session.store_run_usage(result) ## 구조화된 쿼리 -AdvancedSQLiteSession 은 대화 구조와 내용을 분석하기 위한 여러 메서드를 제공합니다. +AdvancedSQLiteSession은 대화 구조와 내용을 분석하기 위한 여러 메서드를 제공합니다. ### 대화 분석 @@ -245,17 +245,17 @@ for turn in matching_turns: ### 메시지 구조 -세션은 다음을 포함해 메시지 구조를 자동으로 추적합니다: +세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다: -- 메시지 유형(사용자, 어시스턴트, tool_call 등) -- 도구 호출의 도구 이름 +- 메시지 타입(user, assistant, tool_call 등) +- 도구 호출 시 도구 이름 - 턴 번호와 시퀀스 번호 -- 분기 연관성 +- 분기 연관 - 타임스탬프 ## 데이터베이스 스키마 -AdvancedSQLiteSession 은 기본 SQLite 스키마를 두 개의 추가 테이블로 확장합니다. +AdvancedSQLiteSession은 기본 SQLite 스키마를 확장하여 두 개의 추가 테이블을 제공합니다: ### message_structure 테이블 @@ -298,7 +298,7 @@ CREATE TABLE turn_usage ( ## 전체 예제 -모든 기능을 포괄적으로 시연하는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요. +모든 기능에 대한 종합적인 데모는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요. ## API 레퍼런스 diff --git a/docs/ko/sessions/encrypted_session.md b/docs/ko/sessions/encrypted_session.md index 69b777d5a..8d3951558 100644 --- a/docs/ko/sessions/encrypted_session.md +++ b/docs/ko/sessions/encrypted_session.md @@ -4,18 +4,18 @@ search: --- # 암호화된 세션 -`EncryptedSession`은 모든 세션 구현에 투명한 암호화를 제공하여, 자동 만료를 통해 오래된 항목을 안전하게 처리합니다. +`EncryptedSession`은 어떤 세션 구현에도 투명한 암호화를 제공하여, 자동 만료와 함께 대화 데이터를 안전하게 보호합니다. ## 기능 -- **투명한 암호화**: 어떤 세션이든 Fernet 암호화로 감쌈 -- **세션별 키**: 세션마다 고유한 암호화를 위해 HKDF 키 유도 사용 -- **자동 만료**: TTL 만료 시 오래된 항목을 조용히 건너뜀 -- **대체 가능**: 기존의 어떤 세션 구현과도 동작 +- **투명한 암호화**: 모든 세션을 Fernet 암호화로 감쌉니다 +- **세션별 키**: 각 세션마다 고유한 암호화를 위해 HKDF 키 파생을 사용합니다 +- **자동 만료**: TTL이 만료되면 오래된 항목은 조용히 건너뜁니다 +- **바로 교체 가능**: 기존 세션 구현과 함께 작동합니다 ## 설치 -암호화된 세션을 사용하려면 `encrypt` extra가 필요합니다: +암호화된 세션에는 `encrypt` extra가 필요합니다: ```bash pip install openai-agents[encrypt] @@ -81,7 +81,7 @@ session = EncryptedSession( ### TTL (Time To Live) -암호화된 항목이 유효하게 유지되는 기간을 설정합니다: +암호화된 항목이 얼마나 오래 유효한지 설정합니다: ```python # Items expire after 1 hour @@ -101,7 +101,7 @@ session = EncryptedSession( ) ``` -## 다양한 세션 유형과 함께 사용 +## 여러 세션 유형과의 사용 ### SQLite 세션 사용 @@ -140,16 +140,16 @@ session = EncryptedSession( !!! warning "고급 세션 기능" - `EncryptedSession`을 `AdvancedSQLiteSession` 같은 고급 세션 구현과 함께 사용할 때는 다음을 유의하세요: + `AdvancedSQLiteSession` 같은 고급 세션 구현과 함께 `EncryptedSession`을 사용할 때는 다음을 유의하세요: - - 메시지 내용이 암호화되므로 `find_turns_by_content()` 같은 메서드는 효과적으로 동작하지 않습니다 - - 내용 기반 검색은 암호화된 데이터에 대해 수행되어 효율이 제한됩니다 + - 메시지 콘텐츠가 암호화되므로 `find_turns_by_content()` 같은 메서드는 효과적으로 동작하지 않습니다 + - 콘텐츠 기반 검색은 암호화된 데이터에서 수행되어 효율이 제한됩니다 -## 키 유도 +## 키 파생 -EncryptedSession은 HKDF(HMAC 기반 키 유도 함수)를 사용하여 세션마다 고유한 암호화 키를 유도합니다: +EncryptedSession은 HKDF(HMAC 기반 키 파생 함수)를 사용해 세션마다 고유한 암호화 키를 파생합니다: - **마스터 키**: 사용자가 제공한 암호화 키 - **세션 솔트**: 세션 ID @@ -158,12 +158,12 @@ EncryptedSession은 HKDF(HMAC 기반 키 유도 함수)를 사용하여 세션 이는 다음을 보장합니다: - 각 세션은 고유한 암호화 키를 가짐 -- 마스터 키 없이는 키를 유도할 수 없음 +- 마스터 키 없이는 키를 파생할 수 없음 - 서로 다른 세션 간에는 세션 데이터를 복호화할 수 없음 ## 자동 만료 -항목이 TTL을 초과하면, 조회 중 자동으로 건너뜁니다: +항목이 TTL을 초과하면 조회 시 자동으로 건너뜁니다: ```python # Items older than TTL are silently ignored @@ -175,5 +175,5 @@ result = await Runner.run(agent, "Continue conversation", session=session) ## API 레퍼런스 -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 기본 클래스 +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 메인 클래스 - [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜 \ No newline at end of file diff --git a/docs/ko/sessions/index.md b/docs/ko/sessions/index.md index d8c4071c0..f0489eef9 100644 --- a/docs/ko/sessions/index.md +++ b/docs/ko/sessions/index.md @@ -4,9 +4,9 @@ search: --- # 세션 -Agents SDK 는 여러 에이전트 실행(run) 간 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공합니다. 이를 통해 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요가 없습니다. +Agents SDK 는 여러 에이전트 실행(run)에 걸쳐 대화 기록을 자동으로 유지하는 기본 세션 메모리를 제공합니다. 이를 통해 턴 사이에 수동으로 `.to_input_list()` 를 처리할 필요가 없습니다. -세션은 특정 세션의 대화 기록을 저장하여, 에이전트가 명시적인 수동 메모리 관리 없이도 컨텍스트를 유지할 수 있도록 합니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티 턴 대화를 구축할 때 특히 유용합니다. +Sessions 는 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리를 하지 않아도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화에 특히 유용합니다. ## 빠른 시작 @@ -47,21 +47,21 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 작동 방식 +## 동작 원리 세션 메모리가 활성화되면: -1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 아이템 앞에 붙입니다 -2. **각 실행 후**: 실행 중 생성된 모든 새 아이템(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 자동으로 세션에 저장됩니다 -3. **컨텍스트 유지**: 동일한 세션으로 후속 실행을 수행할 때 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다 +1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 아이템 앞에 추가합니다 +2. **각 실행 후**: 실행 중에 생성된 모든 새 아이템(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 자동으로 세션에 저장됩니다 +3. **컨텍스트 유지**: 동일한 세션으로 수행되는 이후 실행에는 전체 대화 기록이 포함되어, 에이전트가 컨텍스트를 유지할 수 있습니다 -이를 통해 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없습니다. +이로써 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없습니다. ## 메모리 작업 ### 기본 작업 -세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다: +Sessions 는 대화 기록을 관리하기 위한 여러 작업을 지원합니다: ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 수정 시 pop_item 사용 +### 수정용 pop_item 사용 -`pop_item` 메서드는 대화에서 마지막 아이템을 되돌리거나 수정하려는 경우 특히 유용합니다: +대화에서 마지막 아이템을 되돌리거나 수정하려는 경우 `pop_item` 메서드가 특히 유용합니다: ```python from agents import Agent, Runner, SQLiteSession @@ -159,7 +159,7 @@ print(result.final_output) # "California" ### SQLite 세션 -기본 제공되는 경량 SQLite 기반 세션 구현: +SQLite 를 사용하는 기본 경량 세션 구현: ```python from agents import SQLiteSession @@ -180,7 +180,7 @@ result = await Runner.run( ### SQLAlchemy 세션 -SQLAlchemy 가 지원하는 모든 데이터베이스를 사용하는 프로덕션급 세션: +SQLAlchemy 가 지원하는 모든 데이터베이스를 사용하는 프로덕션 준비 세션: ```python from agents.extensions.memory import SQLAlchemySession @@ -204,7 +204,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ### 고급 SQLite 세션 -대화 브랜칭, 사용량 분석, 구조화된 쿼리를 지원하는 강화된 SQLite 세션: +대화 분기, 사용량 분석, 구조화된 쿼리를 제공하는 향상된 SQLite 세션: ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -228,7 +228,7 @@ await session.create_branch_from_turn(2) # Branch from turn 2 ### 암호화된 세션 -모든 세션 구현에 대한 투명한 암호화 래퍼: +모든 세션 구현을 위한 투명한 암호화 래퍼: ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -255,13 +255,13 @@ result = await Runner.run(agent, "Hello", session=session) ### 기타 세션 유형 -몇 가지 추가 내장 옵션이 있습니다. `examples/memory/` 와 `extensions/memory/` 아래의 소스 코드를 참고하세요. +기본 제공 옵션이 더 있습니다. `examples/memory/` 와 `extensions/memory/` 하위의 소스 코드를 참고하세요. ## 세션 관리 ### 세션 ID 네이밍 -대화를 체계적으로 구성할 수 있도록 의미 있는 세션 ID 를 사용하세요: +대화를 정리하는 데 도움이 되는 의미 있는 세션 ID 를 사용하세요: - User 기반: `"user_12345"` - 스레드 기반: `"thread_abc123"` @@ -269,13 +269,14 @@ result = await Runner.run(agent, "Hello", session=session) ### 메모리 지속성 -- 임시 대화에는 메모리 내 SQLite (`SQLiteSession("session_id")`) 사용 -- 지속형 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 -- SQLAlchemy 가 지원하는 기존 데이터베이스를 사용하는 프로덕션 시스템에는 SQLAlchemy 기반 세션 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 -- 클라우드 네이티브 프로덕션 배포에는 Dapr 상태 저장소 세션 (`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용. 내장 텔레메트리, 트레이싱, 데이터 분리를 갖춘 30+ 데이터베이스 백엔드 지원 -- 기록을 OpenAI Conversations API 에 저장하기를 선호하는 경우 OpenAI 호스트하는 저장소 (`OpenAIConversationsSession()`) 사용 -- 모든 세션을 투명한 암호화와 TTL 기반 만료로 래핑하려면 암호화된 세션 (`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 -- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Redis, Django 등)에 맞춘 사용자 정의 세션 백엔드를 구현하는 것을 고려 +- 임시 대화에는 인메모리 SQLite (`SQLiteSession("session_id")`) 사용 +- 지속적 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- SQLAlchemy 가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 +- 클라우드 네이티브 프로덕션 배포에는 Dapr 상태 저장소 세션 (`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용. 다음을 지원 +30+ database backends with built-in telemetry, tracing, and data isolation +- 기록을 OpenAI Conversations API 에 저장하려면 OpenAI 호스트하는 스토리지 (`OpenAIConversationsSession()`) 사용 +- 투명한 암호화와 TTL 기반 만료를 위해 암호화된 세션 (`EncryptedSession(session_id, underlying_session, encryption_key)`) 으로 어떤 세션이든 래핑 +- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 맞는 커스텀 세션 백엔드 구현 고려 ### 다중 세션 @@ -321,9 +322,9 @@ result2 = await Runner.run( ) ``` -## 전체 예제 +## 전체 예시 -세션 메모리가 실제로 동작하는 전체 예제입니다: +다음은 세션 메모리가 실제로 동작하는 완전한 예시입니다: ```python import asyncio @@ -385,9 +386,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 사용자 정의 세션 구현 +## 커스텀 세션 구현 -[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 생성하여 사용자 정의 세션 메모리를 구현할 수 있습니다: +[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 생성하여 자체 세션 메모리를 구현할 수 있습니다: ```python from agents.memory.session import SessionABC @@ -430,6 +431,16 @@ result = await Runner.run( ) ``` +## 커뮤니티 세션 구현 + +커뮤니티에서 추가 세션 구현을 개발했습니다: + +| 패키지 | 설명 | +|---------|-------------| +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django 가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 위한 Django ORM 기반 세션 | + +세션 구현을 구축하셨다면, 여기 추가할 수 있도록 문서 PR 을 자유롭게 제출해 주세요! + ## API 레퍼런스 자세한 API 문서는 다음을 참조하세요: @@ -439,5 +450,5 @@ result = await Runner.run( - [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 기본 SQLite 구현 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭과 분석을 지원하는 강화된 SQLite +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기 및 분석이 포함된 향상된 SQLite - [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼 \ No newline at end of file diff --git a/docs/ko/sessions/sqlalchemy_session.md b/docs/ko/sessions/sqlalchemy_session.md index 1eaa7179c..a30288d86 100644 --- a/docs/ko/sessions/sqlalchemy_session.md +++ b/docs/ko/sessions/sqlalchemy_session.md @@ -8,7 +8,7 @@ search: ## 설치 -SQLAlchemy 세션에는 `sqlalchemy` extra가 필요합니다: +SQLAlchemy 세션에는 `sqlalchemy` 익스트라가 필요합니다: ```bash pip install openai-agents[sqlalchemy] @@ -18,7 +18,7 @@ pip install openai-agents[sqlalchemy] ### 데이터베이스 URL 사용 -가장 간단한 시작 방법: +시작하는 가장 간단한 방법: ```python import asyncio @@ -44,7 +44,7 @@ if __name__ == "__main__": ### 기존 엔진 사용 -기존 SQLAlchemy 엔진이 있는 애플리케이션의 경우: +기존 SQLAlchemy 엔진을 사용하는 애플리케이션의 경우: ```python import asyncio diff --git a/docs/ko/streaming.md b/docs/ko/streaming.md index 6101c89e8..e35cce8f5 100644 --- a/docs/ko/streaming.md +++ b/docs/ko/streaming.md @@ -4,13 +4,13 @@ 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] 객체의 비동기 스트림을 받을 수 있습니다. ## 원문 응답 이벤트 -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원문 이벤트입니다. OpenAI Responses API 형식을 사용하므로 각 이벤트에는 유형(예: `response.created`, `response.output_text.delta` 등)과 데이터가 있습니다. 이러한 이벤트는 생성되는 즉시 사용자에게 응답 메시지를 스트리밍하려는 경우에 유용합니다. +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원문 이벤트입니다. 이들은 OpenAI Responses API 형식이며, 각 이벤트는 유형(예: `response.created`, `response.output_text.delta` 등)과 데이터를 가집니다. 이러한 이벤트는 생성 즉시 응답 메시지를 사용자에게 스트리밍하려는 경우에 유용합니다. 예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다. @@ -35,9 +35,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 실행 항목 이벤트 및 에이전트 이벤트 +## 실행 항목 이벤트와 에이전트 이벤트 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 상위 수준의 이벤트입니다. 항목이 완전히 생성되었을 때를 알려줍니다. 이를 통해 각 토큰이 아니라 "메시지 생성됨", "도구 실행됨" 수준에서 진행 상황을 전달할 수 있습니다. 유사하게, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프 결과로) 업데이트를 제공합니다. +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 상위 수준의 이벤트입니다. 항목이 완전히 생성되었을 때를 알려줍니다. 이를 통해 각 토큰이 아닌 "메시지 생성 완료", "도구가 실행됨" 등의 수준에서 진행 상황을 전달할 수 있습니다. 또한 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때 업데이트를 제공합니다(예: 핸드오프의 결과로). 예를 들어, 다음은 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. diff --git a/docs/ko/tools.md b/docs/ko/tools.md index 1ca04f77f..584159ca2 100644 --- a/docs/ko/tools.md +++ b/docs/ko/tools.md @@ -4,23 +4,23 @@ search: --- # 도구 -도구는 에이전트가 동작을 수행하도록 합니다. 예: 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지. Agents SDK 에는 세 가지 종류의 도구가 있습니다: +도구는 에이전트가 동작을 수행하도록 합니다. 예를 들어 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지 가능합니다. Agents SDK 에는 세 가지 종류의 도구가 있습니다: -- 호스티드 툴: AI 모델과 함께 LLM 서버에서 실행됩니다. OpenAI 는 retrieval, 웹 검색, 컴퓨터 사용을 호스티드 툴로 제공합니다 -- 함수 호출: 임의의 Python 함수를 도구로 사용할 수 있습니다 -- 도구로서의 에이전트: 에이전트를 도구로 사용하여, 핸드오프 없이 에이전트가 다른 에이전트를 호출할 수 있습니다 +- 호스티드 툴: 이들은 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] 은 로컬 머신에서 셸 명령을 실행합니다 +- [`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 @@ -43,14 +43,14 @@ async def main(): ## 함수 도구 -임의의 Python 함수를 도구로 사용할 수 있습니다. Agents SDK 가 도구 설정을 자동으로 처리합니다: +어떤 Python 함수든 도구로 사용할 수 있습니다. Agents SDK 가 도구 설정을 자동으로 처리합니다: -- 도구 이름은 Python 함수 이름이 됩니다(또는 이름을 직접 지정할 수 있음) -- 도구 설명은 함수의 docstring 에서 가져옵니다(또는 설명을 직접 지정할 수 있음) -- 함수 입력에 대한 스키마는 함수의 인자에서 자동으로 생성됩니다 -- 각 입력의 설명은 비활성화하지 않는 한 함수의 docstring 에서 가져옵니다 +- 도구 이름은 Python 함수 이름이 됩니다(또는 직접 이름을 지정할 수 있음) +- 도구 설명은 함수의 docstring 에서 가져옵니다(또는 직접 설명을 지정할 수 있음) +- 함수 입력을 위한 스키마는 함수의 인자에서 자동으로 생성됩니다 +- 각 입력의 설명은 비활성화하지 않는 한 함수의 docstring 에서 가져옵니다 -Python 의 `inspect` 모듈을 사용해 함수 시그니처를 추출하고, [`griffe`](https://mkdocstrings.github.io/griffe/) 로 docstring 을 파싱하며, 스키마 생성에는 `pydantic` 을 사용합니다. +Python 의 `inspect` 모듈로 함수 시그니처를 추출하고, docstring 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/) 를, 스키마 생성에는 `pydantic` 을 사용합니다. ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 함수의 인자로 임의의 Python 타입을 사용할 수 있으며, 함수는 sync 또는 async 일 수 있습니다 -2. docstring 이 있으면 설명과 인자 설명을 캡처하는 데 사용됩니다 -3. 선택적으로 `context` 를 받을 수 있습니다(첫 번째 인자여야 함). 또한 도구 이름, 설명, 사용할 docstring 스타일 등 오버라이드를 설정할 수 있습니다 -4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다 +1. 함수의 인자로 임의의 Python 타입을 사용할 수 있으며, 함수는 sync 또는 async 일 수 있습니다 +2. docstring 이 있으면 설명과 인자 설명을 캡처하는 데 사용됩니다 +3. 함수는 선택적으로 `context` 를 받을 수 있습니다(첫 번째 인자여야 함). 또한 도구 이름, 설명, 사용할 docstring 스타일 등 오버라이드를 설정할 수 있습니다 +4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다 -??? note "결과 보기" +??? note "출력을 보려면 펼치기" ``` fetch_weather @@ -179,20 +179,20 @@ for tool in agent.tools: ### 함수 도구에서 이미지나 파일 반환 -텍스트 출력 외에도, 함수 도구의 출력으로 하나 또는 여러 개의 이미지나 파일을 반환할 수 있습니다. 이를 위해 다음 중 아무 것이나 반환할 수 있습니다: +텍스트 출력 외에도, 함수 도구의 출력으로 하나 이상의 이미지나 파일을 반환할 수 있습니다. 이를 위해 다음 중 하나를 반환할 수 있습니다: -- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전, [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) -- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전, [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) -- 텍스트: 문자열 또는 문자열로 변환 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText] (또는 TypedDict 버전, [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) +- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전, [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) +- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전, [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) +- 텍스트: 문자열 또는 문자열화 가능한 객체, 혹은 [`ToolOutputText`][agents.tool.ToolOutputText] (또는 TypedDict 버전, [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) ### 커스텀 함수 도구 -때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 직접 [`FunctionTool`][agents.tool.FunctionTool] 을 생성할 수 있습니다. 다음을 제공해야 합니다: +가끔은 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 이 경우 직접 [`FunctionTool`][agents.tool.FunctionTool] 을 생성할 수 있습니다. 다음을 제공해야 합니다: -- `name` -- `description` -- `params_json_schema` — 인자에 대한 JSON 스키마 -- `on_invoke_tool` — [`ToolContext`][agents.tool_context.ToolContext] 와 JSON 문자열로 된 인자를 받아, 도구 출력을 문자열로 반환해야 하는 async 함수 +- `name` +- `description` +- `params_json_schema` (인자의 JSON 스키마) +- `on_invoke_tool` (async 함수로, [`ToolContext`][agents.tool_context.ToolContext] 와 JSON 문자열 형태의 인자를 받고, 도구 출력을 문자열로 반환해야 함) ```python from typing import Any @@ -227,16 +227,16 @@ tool = FunctionTool( ### 인자 및 docstring 자동 파싱 -앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자에 대한 설명을 추출하기 위해 docstring 을 파싱합니다. 참고 사항: +앞서 언급했듯이, 도구를 위한 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자의 설명을 추출하기 위해 docstring 을 파싱합니다. 참고 사항: -1. 시그니처 파싱은 `inspect` 모듈로 수행합니다. 타입 어노테이션을 사용해 인자 타입을 파악하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 구성합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다 -2. docstring 파싱에는 `griffe` 를 사용합니다. 지원하는 docstring 형식은 `google`, `sphinx`, `numpy` 입니다. docstring 형식은 자동 감지를 시도하지만 최선의 노력일 뿐이므로, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. 또한 `use_docstring_info` 를 `False` 로 설정하여 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`][] 에 있습니다. +스키마 추출을 위한 코드는 [`agents.function_schema`][] 에 있습니다. -## 도구로서의 에이전트 +## 에이전트를 도구로 사용 -일부 워크플로에서는 제어를 넘기지 않고, 중앙 에이전트가 특화된 에이전트들의 네트워크를 오케스트레이션하기를 원할 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다. +일부 워크플로에서는 제어권을 넘기는 대신, 중앙 에이전트가 특화된 에이전트 네트워크를 오케스트레이션하기를 원할 수 있습니다. 에이전트를 도구로 모델링하면 이를 구현할 수 있습니다. ```python from agents import Agent, Runner @@ -275,9 +275,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 @@ -298,13 +298,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: @@ -323,9 +323,9 @@ json_tool = data_agent.as_tool( ) ``` -### 도구 조건부 활성화 +### 조건부 도구 활성화 -실행 시점에 `is_enabled` 매개변수를 사용해 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호, 실행 시점 조건에 따라 LLM 에 제공할 도구를 동적으로 필터링할 수 있습니다. +런타임에 `is_enabled` 매개변수 를 사용해 에이전트 도구를 조건부로 활성화 또는 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도, 런타임 조건에 따라 LLM 에 제공되는 도구를 동적으로 필터링할 수 있습니다. ```python import asyncio @@ -380,26 +380,26 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` 매개변수는 다음을 허용합니다: +`is_enabled` 매개변수 는 다음을 허용합니다: -- **불리언 값**: `True`(항상 활성) 또는 `False`(항상 비활성) -- **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 -- **Async 함수**: 복잡한 조건부 로직을 위한 async 함수 +- **불리언 값**: `True`(항상 활성) 또는 `False`(항상 비활성) +- **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 +- **Async 함수**: 더 복잡한 조건부 로직을 위한 async 함수 -비활성화된 도구는 실행 시점에 LLM 에 완전히 숨겨지므로 다음에 유용합니다: +비활성화된 도구는 런타임에 LLM 에게 완전히 숨겨지므로 다음에 유용합니다: -- 사용자 권한에 따른 기능 게이팅 -- 환경별 도구 제공(dev vs prod) -- 서로 다른 도구 구성을 A/B 테스트 -- 실행 시점 상태에 따른 동적 도구 필터링 +- 사용자 권한에 따른 기능 제어 +- 환경별 도구 가용성 제어(개발 환경 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 @@ -422,4 +422,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/ko/tracing.md b/docs/ko/tracing.md index 56978f3bd..51bc9b3fe 100644 --- a/docs/ko/tracing.md +++ b/docs/ko/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 트레이싱은 기본적으로 활성화되어 있습니다. 트레이싱을 비활성화하는 방법은 두 가지입니다: - 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 를 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다 - 2. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][] 를 `True` 로 설정하여 트레이싱을 비활성화할 수 있습니다 + 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 을 설정해 전역으로 트레이싱을 비활성화할 수 있습니다 + 2. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][] 를 `True` 로 설정해 트레이싱을 비활성화할 수 있습니다 -***OpenAI의 API를 사용하는 Zero Data Retention (ZDR) 정책 하에서 운영되는 조직의 경우, 트레이싱을 사용할 수 없습니다.*** +***OpenAI 의 API 를 사용하는 Zero Data Retention (ZDR) 정책하의 조직에서는 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 -- **트레이스**는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: +- **트레이스(Traces)** 는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "Code generation" 또는 "Customer service" - - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>` 이어야 합니다 - - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 - - `disabled`: True이면 트레이스가 기록되지 않습니다 + - `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 생성에 대한 정보를 포함합니다 + - `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()` 호출이 하나의 트레이스에 속하길 원할 수 있습니다. 이 경우 전체 코드를 `trace()` 로 래핑하면 됩니다. +때로는 `run()` 에 대한 여러 호출이 단일 트레이스의 일부가 되도록 하고 싶을 수 있습니다. 전체 코드를 `trace()` 로 래핑하면 됩니다. ```python from agents import Agent, Runner, trace @@ -64,47 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `with trace()` 로 `Runner.run` 에 대한 두 번의 호출을 감싸면, 개별 실행이 두 개의 트레이스를 만들지 않고 전체 트레이스의 일부가 됩니다. +1. `Runner.run` 에 대한 두 번의 호출이 `with trace()` 로 래핑되어 있으므로, 개별 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다. ## 트레이스 생성 -[`trace()`][agents.tracing.trace] 함수를 사용하여 트레이스를 생성할 수 있습니다. 트레이스는 시작되고 종료되어야 합니다. 이를 수행하는 방법은 두 가지입니다: +[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작되고 종료되어야 합니다. 방법은 두 가지입니다: -1. 권장: 컨텍스트 매니저로 트레이스를 사용합니다. 예: `with trace(...) as my_trace`. 적절한 시점에 자동으로 트레이스를 시작하고 종료합니다 -2. [`trace.start()`][agents.tracing.Trace.start] 와 [`trace.finish()`][agents.tracing.Trace.finish] 를 수동으로 호출할 수도 있습니다 +1. 권장: 컨텍스트 매니저로 트레이스를 사용합니다. 예: `with trace(...) as my_trace`. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작되고 종료됩니다 +2. 수동으로 [`trace.start()`][agents.tracing.Trace.start] 및 [`trace.finish()`][agents.tracing.Trace.finish] 를 호출할 수도 있습니다 -현재 트레이스는 Python의 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 를 통해 추적됩니다. 이는 자동으로 동시성에 대응함을 의미합니다. 트레이스를 수동으로 시작/종료하는 경우, 현재 트레이스를 업데이트하기 위해 `start()`/`finish()` 에 `mark_as_current` 및 `reset_current` 를 전달해야 합니다. +현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 즉, 자동으로 동시성에서 동작합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 업데이트하기 위해 `start()`/`finish()` 에 `mark_as_current` 및 `reset_current` 를 전달해야 합니다. ## 스팬 생성 -여러 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 지정 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수가 제공됩니다. +여러 [`*_span()`][agents.tracing.create] 메서드를 사용하여 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 정의 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수가 제공됩니다. -스팬은 자동으로 현재 트레이스의 일부가 되며, Python의 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. +스팬은 자동으로 현재 트레이스의 일부가 되며, Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. ## 민감한 데이터 일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. -`generation_span()` 은 LLM 생성의 입력/출력을 저장하고, `function_span()` 은 함수 호출의 입력/출력을 저장합니다. 민감한 데이터를 포함할 수 있으므로 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. +`generation_span()` 은 LLM 생성의 입력/출력을 저장하고, `function_span()` 은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로, [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. -마찬가지로, 오디오 스팬에는 기본적으로 입력 및 출력 오디오에 대한 base64 인코딩된 PCM 데이터가 포함됩니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 를 구성하여 이 오디오 데이터의 캡처를 비활성화할 수 있습니다. +마찬가지로, 오디오 스팬은 기본적으로 입력 및 출력 오디오에 대해 base64 로 인코딩된 PCM 데이터를 포함합니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 를 구성하여 이 오디오 데이터 캡처를 비활성화할 수 있습니다. ## 사용자 지정 트레이싱 프로세서 트레이싱의 상위 수준 아키텍처는 다음과 같습니다: -- 초기화 시, 트레이스를 생성하는 역할을 하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider] 를 생성합니다 -- `TraceProvider` 를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 로 구성하여, 스팬과 트레이스를 OpenAI 백엔드로 배치 전송하는 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] 에 배치로 전달합니다 +- 초기화 시 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider] 를 생성하며, 이는 트레이스를 생성하는 역할을 담당합니다 +- `TraceProvider` 를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 로 구성하여, 스팬과 트레이스를 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] 에 전달하고, Exporter 가 OpenAI 백엔드로 배치 전송합니다 -기본 설정을 사용자 지정하여 다른 백엔드로 전송하거나 추가 백엔드로 전송하거나 내보내기 동작을 수정하려면 두 가지 옵션이 있습니다: +기본 설정을 사용자 지정하여 다른 백엔드로 트레이스를 전송하거나 추가 목적지로 전송하거나 Exporter 동작을 수정하려면 두 가지 옵션이 있습니다: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 는 트레이스와 스팬이 준비되는 즉시 수신하는 **추가** 트레이스 프로세서를 추가할 수 있게 합니다. 이를 통해 OpenAI 백엔드로의 전송 외에 자체 처리를 수행할 수 있습니다 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 는 기본 프로세서를 사용자 지정 트레이스 프로세서로 **교체** 할 수 있게 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 그렇게 하는 `TracingProcessor` 를 포함해야 합니다 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 를 사용하면 트레이스와 스팬이 준비되는 대로 수신하는 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 트레이스를 전송하는 것 외에도 자체 처리를 수행할 수 있습니다 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 를 사용하면 기본 프로세서를 사용자 지정 트레이스 프로세서로 **교체**할 수 있습니다. 이 경우 OpenAI 백엔드로 전송하는 `TracingProcessor` 를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다 +## 비 OpenAI 모델에서의 트레이싱 -## 비 OpenAI 모델과의 트레이싱 - -OpenAI의 API 키를 비 OpenAI 모델과 함께 사용하여 트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. +트레이싱을 비활성화할 필요 없이 OpenAI 가 아닌 모델에서도 OpenAI API 키를 사용해 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. ```python import os @@ -126,7 +125,7 @@ agent = Agent( ``` ## 참고 -- OpenAI Traces 대시보드에서 무료 트레이스를 확인하세요 +- Openai Traces 대시보드에서 무료 트레이스를 확인하세요 ## 외부 트레이싱 프로세서 목록 diff --git a/docs/ko/usage.md b/docs/ko/usage.md index b153ce468..592d6c9c2 100644 --- a/docs/ko/usage.md +++ b/docs/ko/usage.md @@ -4,7 +4,7 @@ search: --- # 사용량 -Agents SDK는 각 실행에 대한 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 접근하여 비용 모니터링, 제한 적용, 분석 기록에 사용할 수 있습니다. +Agents SDK 는 각 실행마다 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 접근하여 비용 모니터링, 한도 적용, 분석 기록에 활용할 수 있습니다. ## 추적 항목 @@ -12,14 +12,14 @@ Agents SDK는 각 실행에 대한 토큰 사용량을 자동으로 추적합니 - **input_tokens**: 전송된 입력 토큰 총합 - **output_tokens**: 수신된 출력 토큰 총합 - **total_tokens**: 입력 + 출력 -- **request_usage_entries**: 요청별 사용량 분해 목록 +- **request_usage_entries**: 요청별 사용량 세부 목록 - **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?") @@ -31,11 +31,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -사용량은 실행 중의 모든 모델 호출(도구 호출 및 handoffs 포함)에 걸쳐 집계됩니다. +사용량은 실행 중 발생한 모든 모델 호출에 대해 집계됩니다(도구 호출과 핸드오프 포함). ### 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 @@ -53,7 +53,7 @@ print(result.context_wrapper.usage.total_tokens) ## 요청별 사용량 추적 -SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하므로, 상세한 비용 계산 및 컨텍스트 윈도우 소모 모니터링에 유용합니다. +SDK 는 각 API 요청에 대한 사용량을 `request_usage_entries` 로 자동 추적합니다. 이는 상세 비용 계산과 컨텍스트 윈도우 소모 모니터링에 유용합니다. ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -64,7 +64,7 @@ for request in enumerate(result.context_wrapper.usage.request_usage_entries): ## 세션에서 사용량 접근 -`Session`(예: `SQLiteSession`)을 사용할 때, `Runner.run(...)`의 각 호출은 해당 실행에 대한 사용량을 반환합니다. 세션은 컨텍스트를 위한 대화 기록을 유지하지만 각 실행의 사용량은 독립적입니다. +`Session`(예: `SQLiteSession`) 을 사용할 때, `Runner.run(...)` 호출마다 해당 실행의 사용량이 반환됩니다. 세션은 컨텍스트 유지를 위해 대화 기록을 보관하지만, 실행별 사용량은 서로 독립적입니다. ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,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): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API 레퍼런스 -자세한 API 문서는 다음을 참조하세요: +자세한 API 문서는 다음을 참조하세요. - [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 - [`RequestUsage`][agents.usage.RequestUsage] - 요청별 사용량 세부 정보 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근 -- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 수명 주기에 훅 연결 \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 생명주기에 훅 연결하기 \ No newline at end of file diff --git a/docs/ko/visualization.md b/docs/ko/visualization.md index 65bb0618d..2d7e06550 100644 --- a/docs/ko/visualization.md +++ b/docs/ko/visualization.md @@ -4,7 +4,7 @@ search: --- # 에이전트 시각화 -에이전트 시각화는 **Graphviz**를 사용해 에이전트와 그 관계를 구조화된 그래픽으로 생성합니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다. +에이전트 시각화는 **Graphviz**를 사용하여 에이전트와 그 관계를 구조화된 그래픽 형태로 생성할 수 있게 해줍니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다. ## 설치 @@ -16,14 +16,14 @@ pip install "openai-agents[viz]" ## 그래프 생성 -`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 유향 그래프를 생성합니다: +`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 구성의 방향 그래프를 생성합니다: -- **에이전트**는 노란색 박스로 표현 -- **MCP 서버**는 회색 박스로 표현 -- **도구**는 초록색 타원으로 표현 -- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 유향 간선 +- **에이전트**는 노란색 상자로 표시됨 +- **MCP 서버**는 회색 상자로 표시됨 +- **도구**는 초록색 타원으로 표시됨 +- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향 간선으로 표시됨 -### 사용 예 +### 사용 예시 ```python import os @@ -69,30 +69,29 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -이는 **트리아지 에이전트**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프를 생성합니다 - +이는 **triage agent**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프를 생성합니다. ## 시각화 이해 생성된 그래프에는 다음이 포함됩니다: -- 진입점을 나타내는 **시작 노드** (`__start__`) -- 노란색 채움의 **사각형**으로 표현된 에이전트 -- 초록색 채움의 **타원**으로 표현된 도구 -- 회색 채움의 **사각형**으로 표현된 MCP 서버 -- 상호작용을 나타내는 유향 간선: +- 진입점을 나타내는 **start 노드** (`__start__`) +- 노란색 채우기의 **사각형**으로 표시된 에이전트 +- 초록색 채우기의 **타원**으로 표시된 도구 +- 회색 채우기의 **사각형**으로 표시된 MCP 서버 +- 상호작용을 나타내는 방향 간선: - 에이전트 간 핸드오프는 **실선 화살표** - 도구 호출은 **점선 화살표** - MCP 서버 호출은 **파선 화살표** -- 실행 종료 지점을 나타내는 **끝 노드** (`__end__`) +- 실행 종료 지점을 나타내는 **end 노드** (`__end__`) **참고:** MCP 서버는 최신 버전의 -`agents` 패키지에서 렌더링됩니다 (**v0.2.8**에서 확인됨). 시각화에서 MCP 박스가 보이지 않는 경우 최신 릴리스로 업그레이드하세요. +`agents` 패키지에서 렌더링됩니다 ( **v0.2.8**에서 확인됨). 시각화에 MCP 상자가 보이지 않는다면 최신 릴리스로 업그레이드하세요. -## 그래프 사용자 정의 +## 그래프 커스터마이징 ### 그래프 표시 -기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창으로 표시하려면 다음을 작성하세요: +기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에 표시하려면 다음을 작성하세요: ```python draw_graph(triage_agent).view() @@ -105,4 +104,4 @@ draw_graph(triage_agent).view() draw_graph(triage_agent, filename="agent_graph") ``` -그러면 작업 디렉터리에 `agent_graph.png`가 생성됩니다. \ No newline at end of file +작업 디렉터리에 `agent_graph.png`가 생성됩니다. \ No newline at end of file diff --git a/docs/ko/voice/pipeline.md b/docs/ko/voice/pipeline.md index a58c8179d..394ab94bf 100644 --- a/docs/ko/voice/pipeline.md +++ b/docs/ko/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # 파이프라인과 워크플로 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 워크플로를 손쉽게 음성 앱으로 바꿀 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오의 음성 인식, 오디오 종료 감지, 올바른 타이밍에 워크플로 호출, 워크플로 출력을 다시 오디오로 변환하는 작업을 처리합니다. +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 워크플로를 음성 앱으로 손쉽게 전환할 수 있게 해 주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오를 음성 인식하고, 오디오 종료를 감지하며, 적절한 시점에 워크플로를 호출하고, 워크플로 출력을 다시 오디오로 변환하는 일을 담당합니다. ```mermaid graph LR @@ -34,28 +34,28 @@ graph LR ## 파이프라인 구성 -파이프라인을 생성할 때 다음 항목들을 설정할 수 있습니다: +파이프라인을 생성할 때 다음을 설정할 수 있습니다: -1. 매번 새로운 오디오가 전사될 때 실행되는 코드인 [`workflow`][agents.voice.workflow.VoiceWorkflowBase] -2. 사용될 [`speech-to-text`][agents.voice.model.STTModel] 및 [`text-to-speech`][agents.voice.model.TTSModel] 모델 +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 모델의 설정: 프롬프트, 언어, 사용되는 데이터 타입 등 + - 프롬프트, 언어, 사용하는 데이터 타입 등 TTS 및 STT 모델 설정 ## 파이프라인 실행 -파이프라인은 [`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드로 실행하며, 오디오 입력을 두 가지 형태로 전달할 수 있습니다: +파이프라인은 [`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드로 실행할 수 있으며, 두 가지 형태의 오디오 입력을 전달할 수 있습니다: -1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사가 있고 해당 전사에 대한 결과만 생성하면 될 때 사용합니다. 이는 화자가 발화를 마쳤는지 감지할 필요가 없는 경우, 예를 들어 사전 녹음된 오디오나 사용자가 발화를 마치는 시점이 명확한 push-to-talk 앱에서 유용합니다. -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 발화를 마쳤는지를 감지해야 할 수 있는 경우에 사용합니다. 감지되는 대로 오디오 청크를 푸시할 수 있으며, 음성 파이프라인은 "activity detection(활동 감지)"이라 불리는 프로세스를 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다. +1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 기록이 있고 그에 대한 결과만 생성하면 될 때 사용합니다. 이는 화자가 발화를 마치는 시점을 감지할 필요가 없는 경우, 예를 들어 사전 녹음된 오디오나 사용자가 말하기를 마치는 시점이 명확한 푸시-투-토크 앱에서 유용합니다 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 발화를 마치는 시점을 감지해야 할 수 있는 경우에 사용합니다. 이 경우 탐지되는 대로 오디오 청크를 푸시할 수 있으며, 음성 파이프라인이 "활동 감지"라는 프로세스를 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다 ## 결과 -음성 파이프라인 실행 결과는 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]입니다. 이는 발생하는 이벤트를 스트리밍할 수 있는 객체입니다. 다음과 같은 여러 종류의 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent]가 있습니다: +음성 파이프라인 실행의 결과는 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]입니다. 이는 이벤트가 발생하는 대로 스트리밍할 수 있게 해 주는 객체입니다. 다음과 같은 여러 종류의 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent]가 있습니다: 1. 오디오 청크를 포함하는 [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] -2. 턴 시작/종료와 같은 라이프사이클 이벤트를 알려주는 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] +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]에 대한 내장 인터럽션(중단 처리) 기능을 지원하지 않습니다. 대신 감지된 각 턴마다 워크플로의 별도 실행(run)을 트리거합니다. 애플리케이션 내부에서 인터럽션을 처리하려면 [`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 index a7cf238f0..c461b98b3 100644 --- a/docs/ko/voice/quickstart.md +++ b/docs/ko/voice/quickstart.md @@ -4,9 +4,9 @@ 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. 음성을 텍스트로 변환하기 위해 음성 인식(speech-to-text) 모델을 실행 +2. 보통 에이전트 워크플로인 코드를 실행하여 결과 생성 +3. 결과 텍스트를 다시 오디오로 변환하기 위해 음성 합성(text-to-speech) 모델을 실행 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## 에이전트 -먼저 에이전트를 설정해 봅시다. 이 SDK로 에이전트를 만든 경험이 있다면 익숙하게 느껴질 것입니다. 에이전트 몇 개와 핸드오프, 그리고 도구 하나를 사용합니다. +먼저 몇 개의 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙할 것입니다. 몇 개의 에이전트, 하나의 핸드오프, 그리고 하나의 도구를 사용합니다. ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 음성 파이프라인 -워크플로우로 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 사용하여 간단한 음성 파이프라인을 설정하겠습니다. +[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 워크플로로 사용해 간단한 음성 파이프라인을 설정합니다. ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -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/ko/voice/tracing.md b/docs/ko/voice/tracing.md index 02b70e27f..38705907c 100644 --- a/docs/ko/voice/tracing.md +++ b/docs/ko/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # 트레이싱 -[에이전트 트레이싱](../tracing.md)과 마찬가지로 음성 파이프라인도 자동으로 트레이싱됩니다. +[에이전트 트레이싱](../tracing.md)과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다. -기본적인 트레이싱 정보는 위 문서를 참고하시고, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 설정할 수 있습니다. +기본 트레이싱 정보는 위 문서를 참고하시고, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인 트레이싱을 구성할 수 있습니다. -트레이싱 관련 주요 필드는 다음과 같습니다: +주요 트레이싱 관련 필드는 다음과 같습니다: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱 비활성화 여부를 제어합니다. 기본적으로 트레이싱은 활성화되어 있습니다. -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사본과 같은 민감할 수 있는 데이터를 트레이스에 포함할지 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며, Workflow 내부에서 발생하는 작업에는 적용되지 않습니다. -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 트레이스에 오디오 데이터를 포함할지 여부를 제어합니다. -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로 이름 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있게 해주는 트레이스의 `group_id` -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이스에 포함할 추가 메타데이터 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱 비활성화 여부를 제어합니다. 기본값은 트레이싱 활성화입니다. +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사본처럼 민감할 수 있는 데이터 포함 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며 워크플로 내부에서 발생하는 내용에는 적용되지 않습니다. +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 오디오 데이터 포함 여부를 제어합니다. +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로의 이름입니다. +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있게 하는 트레이스의 `group_id`입니다. +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이스에 포함할 추가 메타데이터입니다. \ No newline at end of file diff --git a/docs/zh/agents.md b/docs/zh/agents.md index d18fdd7c8..c3ff070ca 100644 --- a/docs/zh/agents.md +++ b/docs/zh/agents.md @@ -4,16 +4,16 @@ search: --- # 智能体 -智能体是应用中的核心构建块。一个智能体是配置了 instructions 和工具的大型语言模型（LLM）。 +智能体是你应用中的核心构建模块。一个智能体是经过配置了 instructions 和工具的大型语言模型（LLM）。 ## 基本配置 -你最常为智能体配置的属性包括： +你通常会为智能体配置以下常见属性： -- `name`: 一个必填字符串，用于标识你的智能体。 -- `instructions`: 也称为开发者消息或系统提示词（system prompt）。 -- `model`: 使用哪个 LLM，以及可选的 `model_settings` 来配置如 temperature、top_p 等模型调优参数。 -- `tools`: 智能体为完成任务可使用的工具。 +- `name`: 用于标识智能体的必填字符串。 +- `instructions`: 也称为开发者消息或 system prompt。 +- `model`: 指定要使用的 LLM，并可选提供 `model_settings` 来配置如 temperature、top_p 等模型调优参数。 +- `tools`: 智能体可用于完成任务的工具。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## 上下文 -智能体在其 `context` 类型上是泛型的。Context 是一种依赖注入工具：这是你创建并传递给 `Runner.run()` 的对象，它会传给每个智能体、工具、任务转移等，并作为本次运行的依赖与状态集合。你可以提供任何 Python 对象作为上下文。 +智能体对其 `context` 类型是泛型的。Context 是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会传递给每个智能体、工具、任务转移等，并作为此次智能体运行的依赖与状态集合。你可以提供任何 Python 对象作为 context。 ```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、list、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) 而不是常规纯文本响应。 ## 多智能体系统设计模式 -设计多智能体系统的方式很多，但我们常见到两种广泛适用的模式： +设计多智能体系统的方法有很多，但我们通常看到两种普适模式： -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](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](handoffs.md) 文档。 +任务转移是智能体可委派的子智能体。当发生任务转移时，被委派的智能体会接收对话历史并接管对话。该模式支持模块化、专精于单一任务的智能体。更多内容见[任务转移](handoffs.md)文档。 ```python from agents import Agent @@ -134,9 +134,9 @@ triage_agent = Agent( ) ``` -## 动态 instructions +## 动态指令 -在大多数情况下，你可以在创建智能体时提供 instructions。你也可以通过函数提供动态 instructions。该函数将接收智能体和上下文，并必须返回提示词。支持常规和 `async` 函数。 +在大多数情况下，你可以在创建智能体时提供指令。不过，你也可以通过函数提供动态指令。该函数将接收智能体和 context，并且必须返回提示词。支持普通函数和 `async` 函数。 ```python def dynamic_instructions( @@ -153,15 +153,15 @@ agent = Agent[UserContext]( ## 生命周期事件（hooks） -有时你希望观察智能体的生命周期。例如，你可能想记录事件，或在特定事件发生时预取数据。你可以通过 `hooks` 属性挂接到智能体生命周期。子类化 [`AgentHooks`][agents.lifecycle.AgentHooks] 类，并重写你感兴趣的方法。 +有时你可能希望观察智能体的生命周期。例如，你可能希望记录事件，或在某些事件发生时预取数据。你可以通过 `hooks` 属性接入智能体生命周期。继承 [`AgentHooks`][agents.lifecycle.AgentHooks] 类，并重写你感兴趣的方法。 ## 安全防护措施 -安全防护措施允许你在智能体运行的同时对用户输入进行检查/验证，并在智能体产出结果后对其输出进行检查。例如，你可以对用户输入和智能体输出进行相关性筛查。更多内容参见 [guardrails](guardrails.md) 文档。 +安全防护措施允许你在智能体运行的同时并行地对用户输入进行检查/校验，并在智能体产出输出后对其进行检查。例如，你可以筛查用户输入和智能体输出的相关性。更多内容见[安全防护措施](guardrails.md)文档。 ## 克隆/复制智能体 -通过在智能体上使用 `clone()` 方法，你可以复制一个智能体，并可选地更改任意属性。 +通过在智能体上使用 `clone()` 方法，你可以复制一个智能体，并可选地修改任意你想更改的属性。 ```python pirate_agent = Agent( @@ -176,13 +176,13 @@ 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 _不_ 使用工具。 +1. `auto`：允许 LLM 自行决定是否使用工具。 +2. `required`：要求 LLM 使用某个工具（但可智能选择使用哪个工具）。 +3. `none`：要求 LLM 不使用工具。 4. 设置特定字符串，例如 `my_tool`，要求 LLM 使用该特定工具。 ```python @@ -203,10 +203,10 @@ agent = Agent( ## 工具使用行为 -`Agent` 配置中的 `tool_use_behavior` 参数控制工具输出的处理方式： +在 `Agent` 配置中的 `tool_use_behavior` 参数控制如何处理工具输出： -- `"run_llm_again"`：默认值。运行工具后，LLM 处理结果以生成最终响应。 -- `"stop_on_first_tool"`：第一次工具调用的输出将作为最终响应，不再进行额外的 LLM 处理。 +- `"run_llm_again"`：默认值。运行工具后，由 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` 设置，LLM 会再次生成工具调用，如此往复。 \ No newline at end of file diff --git a/docs/zh/config.md b/docs/zh/config.md index 68d60bc0c..305dafba0 100644 --- a/docs/zh/config.md +++ b/docs/zh/config.md @@ -2,11 +2,11 @@ search: exclude: true --- -# SDK 配置 +# 配置 SDK ## API 密钥与客户端 -默认情况下，SDK 在导入后会立即从环境变量 `OPENAI_API_KEY` 中读取用于 LLM 请求和追踪的密钥。如果你无法在应用启动前设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数来设置密钥。 +默认情况下，SDK 在被导入后会立即从环境变量 `OPENAI_API_KEY` 中读取 LLM 请求与追踪所需的密钥。若无法在应用启动前设置该环境变量，可使用 [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` 实例，使用来自环境变量或上述默认设置的 API 密钥。你可以通过 [set_default_openai_client()][agents.set_default_openai_client] 函数进行更改。 +或者，你也可以配置要使用的 OpenAI 客户端。默认情况下，SDK 会使用环境变量中的密钥或上述设置的默认密钥创建一个 `AsyncOpenAI` 实例。你可以通过 [set_default_openai_client()][agents.set_default_openai_client] 函数进行更改。 ```python from openai import AsyncOpenAI @@ -24,7 +24,7 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -最后，你也可以自定义所使用的 OpenAI API。默认使用 OpenAI Responses API。你可以通过 [set_default_openai_api()][agents.set_default_openai_api] 函数覆盖为使用 Chat Completions API。 +最后，你还可以自定义所使用的 OpenAI API。默认情况下，我们使用 OpenAI Responses API。你可以通过 [set_default_openai_api()][agents.set_default_openai_api] 函数覆盖为使用 Chat Completions API。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## 追踪 -追踪默认启用。默认情况下，它使用上文的 OpenAI API 密钥（即环境变量或你设置的默认密钥）。你可以通过 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数专门设置用于追踪的 API 密钥。 +追踪默认启用。它默认使用上文中的 OpenAI API 密钥（即环境变量或你设置的默认密钥）。你可以使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数专门设置用于追踪的 API 密钥。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -你也可以通过 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数完全禁用追踪。 +你也可以使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数完全禁用追踪。 ```python from agents import set_tracing_disabled @@ -52,9 +52,9 @@ set_tracing_disabled(True) ## 调试日志 -SDK 提供了两个未设置任何处理器的 Python 日志记录器。默认情况下，这意味着警告与错误会输出到 `stdout`，但其他日志会被抑制。 +该 SDK 提供两个未设置任何处理器的 Python 日志记录器。默认情况下，这意味着警告和错误会输出到 `stdout`，而其他日志会被抑制。 -若要启用详细日志，使用 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 函数。 +若需启用详细日志，请使用 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 函数。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -或者，你可以通过添加处理器（handlers）、过滤器（filters）、格式化器（formatters）等自定义日志。更多内容参见 [Python logging 指南](https://docs.python.org/3/howto/logging.html)。 +或者，你可以通过添加处理器、过滤器、格式化器等自定义日志。可阅读 [Python logging 指南](https://docs.python.org/3/howto/logging.html)了解更多。 ```python import logging @@ -85,13 +85,13 @@ logger.addHandler(logging.StreamHandler()) 某些日志可能包含敏感数据（例如，用户数据）。如果你希望禁用这些数据的记录，请设置以下环境变量。 -禁用记录 LLM 的输入与输出： +禁用记录 LLM 输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -禁用记录工具的输入与输出： +禁用记录工具输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/zh/context.md b/docs/zh/context.md index cb244093a..36c5c5a92 100644 --- a/docs/zh/context.md +++ b/docs/zh/context.md @@ -4,30 +4,30 @@ search: --- # 上下文管理 -“上下文”是一个易混淆的术语。通常你会关心两类主要的上下文： +“上下文”一词含义较多。你可能关心的上下文主要分为两类： -1. 代码本地可用的上下文：指工具函数运行时、如 `on_handoff` 回调、生命周期钩子等需要的数据与依赖。 -2. LLM 可用的上下文：指 LLM 在生成响应时所能看到的数据。 +1. 代码本地可用的上下文：即工具函数运行时、`on_handoff` 等回调、生命周期钩子中可能需要的数据与依赖。 +2. 对 LLM 可见的上下文：即 LLM 在生成响应时所能看到的数据。 ## 本地上下文 -这由 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 类及其内部的 [`context`][agents.run_context.RunContextWrapper.context] 属性表示。其工作方式是： +这通过 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 类以及其内部的 [`context`][agents.run_context.RunContextWrapper.context] 属性来表示。其工作方式如下： -1. 你创建任意 Python 对象。常见做法是使用 dataclass 或 Pydantic 对象。 -2. 将该对象传给各种运行方法（例如 `Runner.run(..., **context=whatever**)`）。 -3. 所有工具调用、生命周期钩子等都会接收一个包装对象 `RunContextWrapper[T]`，其中 `T` 表示你的上下文对象类型，你可以通过 `wrapper.context` 访问。 +1. 你可以创建任意 Python 对象。常见做法是使用 dataclass 或 Pydantic 对象。 +2. 将该对象传入各类运行方法（例如 `Runner.run(..., **context=whatever**)`）。 +3. 你所有的工具调用、生命周期钩子等都会收到一个包装对象 `RunContextWrapper[T]`，其中 `T` 代表你的上下文对象类型，你可以通过 `wrapper.context` 访问它。 -需要重点注意的是：对于同一次智能体运行，所有智能体、工具函数、生命周期等必须使用相同的上下文_类型_。 +需要特别注意的最重要一点：给定一次智能体运行，所有智能体、工具函数、生命周期等必须使用相同的上下文类型。 你可以将上下文用于以下场景： -- 运行的上下文数据（例如用户名/uid 或关于用户的其他信息） -- 依赖（例如日志记录对象、数据获取器等） -- 辅助函数 +- 运行所需的上下文数据（例如用户名/uid 或其他关于用户的信息） +- 依赖项（例如 logger 对象、数据获取器等） +- 帮助函数 !!! danger "注意" - 上下文对象**不**会发送给 LLM。它只是一个纯本地对象，你可以读取、写入并在其上调用方法。 + 上下文对象**不会**发送给 LLM。它纯粹是一个本地对象，你可以读取、写入并在其上调用方法。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 这是上下文对象。此处使用了 dataclass，但你可以使用任何类型。 -2. 这是一个工具。你可以看到它接收一个 `RunContextWrapper[UserInfo]`。该工具的实现会从上下文中读取。 -3. 我们在智能体上标注泛型 `UserInfo`，以便类型检查器捕获错误（例如，如果我们试图传入一个使用不同上下文类型的工具）。 -4. 通过 `run` 函数传入上下文。 -5. 智能体正确调用该工具并获取年龄。 +1. 这是上下文对象。此处我们使用了 dataclass，但你可以使用任何类型。 +2. 这是一个工具。你可以看到它接收 `RunContextWrapper[UserInfo]`。该工具的实现会从上下文中读取数据。 +3. 我们用泛型 `UserInfo` 标注智能体，这样类型检查器就能捕获错误（例如，如果我们尝试传入一个使用不同上下文类型的工具）。 +4. 将上下文传给 `run` 函数。 +5. 智能体正确调用工具并获得年龄。 --- -### 高级：`ToolContext` +### 高级用法：`ToolContext` -在某些情况下，你可能希望访问正在执行的工具的额外元数据——例如其名称、调用 ID，或原始参数字符串。 +在某些情况下，你可能需要访问正在执行的工具的额外元数据——例如其名称、调用 ID 或原始参数字符串。 为此，你可以使用扩展自 `RunContextWrapper` 的 [`ToolContext`][agents.tool_context.ToolContext] 类。 ```python @@ -105,23 +105,23 @@ agent = Agent( ) ``` -`ToolContext` 提供与 `RunContextWrapper` 相同的 `.context` 属性， -并额外包含当前工具调用的特定字段： +`ToolContext` 与 `RunContextWrapper` 一样提供 `.context` 属性， +并额外包含当前工具调用特有的字段： - `tool_name` – 被调用工具的名称 -- `tool_call_id` – 该次工具调用的唯一标识符 -- `tool_arguments` – 传给工具的原始参数字符串 +- `tool_call_id` – 此次工具调用的唯一标识符 +- `tool_arguments` – 传递给工具的原始参数字符串 -当你在执行期间需要工具级元数据时，请使用 `ToolContext`。 +当你在执行期间需要工具级元数据时，使用 `ToolContext`。 对于智能体与工具之间的一般上下文共享，`RunContextWrapper` 已经足够。 --- ## 智能体/LLM 上下文 -当调用 LLM 时，它能看到的**唯一**数据来自对话历史。这意味着如果你想让一些新数据对 LLM 可见，必须以能将其纳入历史的方式进行提供。常见方法包括： +当调用 LLM 时，它能看到的**唯一**数据来自对话历史。这意味着如果你希望让 LLM 获取新的数据，必须以能将其加入该历史的方式提供。有几种方法可以实现： -1. 将其添加到智能体的 `instructions`。这也被称为“system prompt”或“developer message”。System prompts 可以是静态字符串，或接收上下文并输出字符串的动态函数。这常用于总是有用的信息（例如用户名或当前日期）。 -2. 在调用 `Runner.run` 函数时将其添加到 `input`。这与 `instructions` 的做法类似，但允许你使用在[指令链](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)中层级更低的消息。 -3. 通过 工具调用 暴露。适用于_按需_上下文——LLM 决定何时需要某些数据，并可调用工具来获取该数据。 -4. 使用检索或 网络检索。它们是特殊的工具，能够从文件或数据库（文件检索），或从网页（网络检索）获取相关数据。这有助于将回答基于相关的上下文数据进行支撑（grounding）。 \ No newline at end of file +1. 将其添加到智能体的 `instructions`。这也被称为“系统提示词”或“开发者消息”。系统提示词可以是静态字符串，也可以是接收上下文并输出字符串的动态函数。这常用于始终有用的信息（例如用户名或当前日期）。 +2. 在调用 `Runner.run` 函数时将其添加到 `input`。这与 `instructions` 策略类似，但允许你将消息放在[指挥链](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)的更低位置。 +3. 通过 工具调用 暴露。适用于_按需_上下文——由 LLM 决定何时需要某些数据，并可调用工具获取该数据。 +4. 使用检索或 网络检索。这些是能够从文件或数据库（检索）或从网络（网络检索）获取相关数据的特殊工具。它有助于用相关上下文数据为响应“奠基”。 \ No newline at end of file diff --git a/docs/zh/examples.md b/docs/zh/examples.md index 11efb18f4..3f8076bc2 100644 --- a/docs/zh/examples.md +++ b/docs/zh/examples.md @@ -4,58 +4,58 @@ search: --- # 代码示例 -在[repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的代码示例部分查看多种 SDK 的示例实现。这些代码示例按多个目录组织，展示不同的模式与能力。 +在[仓库](https://github.com/openai/openai-agents-python/tree/main/examples)的 examples 部分可以查看各种 SDK 的示例实现。这些代码示例按多个目录组织，以演示不同的模式与能力。 ## 目录 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 本目录中的示例展示常见的智能体设计模式，例如： + 本目录中的代码示例展示常见的智能体设计模式，例如： - 确定性工作流 - 作为工具的智能体 - 并行智能体执行 - 条件性工具使用 - 输入/输出安全防护措施 - - 作为裁判的 LLM + - LLM 充当裁判 - 路由 - 流式传输安全防护措施 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 这些示例展示 SDK 的基础能力，例如： + 这些代码示例展示 SDK 的基础能力，例如： - - Hello World 代码示例（默认模型、GPT-5、open-weight 模型） + - Hello World 代码示例（默认模型、GPT-5、开源权重模型） - 智能体生命周期管理 - - 动态系统提示词 - - 流式传输输出（文本、条目、函数调用参数） + - 动态 system prompt + - 流式传输输出（文本、items、函数调用参数） - 提示词模板 - - 文件处理（本地与远程，图像与 PDF） + - 文件处理（本地与远程、图像与 PDF） - 使用情况追踪 - 非严格输出类型 - - 先前响应 ID 的使用 + - 先前响应 ID 的用法 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 航空公司客服系统示例。 + 航空公司的客户服务系统示例。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融研究智能体，展示用于金融数据分析的结构化研究工作流与工具。 + 一个金融研究智能体，展示使用智能体与工具的结构化研究工作流，用于金融数据分析。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 查看带消息过滤的智能体任务转移的实用示例。 + 查看带消息过滤的智能体任务转移的实用代码示例。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 展示如何使用托管的 MCP (Model Context Protocol) 连接器与审批。 + 演示如何使用托管的 MCP (Model Context Protocol) 连接器与审批。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 了解如何使用 MCP (Model Context Protocol) 构建智能体，包括： + 学习如何使用 MCP (Model Context Protocol) 构建智能体，包括： - 文件系统代码示例 - Git 代码示例 - - MCP 提示词服务代码示例 - - SSE（Server-Sent Events）代码示例 + - MCP prompt 服务 代码示例 + - SSE (Server-Sent Events) 代码示例 - 可流式传输的 HTTP 代码示例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 针对智能体的不同内存实现示例，包括： + 展示智能体的不同内存实现，包括： - SQLite 会话存储 - 高级 SQLite 会话存储 @@ -65,7 +65,7 @@ search: - OpenAI 会话存储 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 了解如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方与 LiteLLM 集成。 + 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方与 LiteLLM 集成。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** 展示如何使用 SDK 构建实时体验，包括： @@ -75,19 +75,19 @@ search: - 与 Twilio 的集成 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 展示如何处理推理内容与 structured outputs 的代码示例。 + 演示如何处理推理内容与格式良好的数据。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 简单的深度研究克隆，展示复杂的多智能体研究工作流。 + 简易的深度研究克隆，演示复杂的多智能体研究工作流。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 了解如何实现由OpenAI托管的工具，例如： + 学习如何实现由OpenAI托管的工具，例如： - - 网络检索与带筛选条件的网络检索 + - 网络检索与带筛选的网络检索 - 文件检索 - - Code interpreter + - Code Interpreter - 计算机操作 - 图像生成 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 查看语音智能体代码示例，使用我们的 TTS 与 STT 模型，包括流式语音代码示例。 \ No newline at end of file + 查看语音智能体代码示例，使用我们的 TTS 和 STT 模型，包括流式传输语音代码示例。 \ No newline at end of file diff --git a/docs/zh/guardrails.md b/docs/zh/guardrails.md index 8344d7aa3..c837933cf 100644 --- a/docs/zh/guardrails.md +++ b/docs/zh/guardrails.md @@ -4,9 +4,9 @@ search: --- # 安全防护措施 -安全防护措施使你能够对用户输入和智能体输出进行检查和验证。比如，假设你有一个使用非常智能（因此也较慢/昂贵）模型来处理客户请求的智能体。你不希望恶意用户让模型帮助他们完成数学作业。因此，你可以使用快速/便宜的模型运行一条安全防护措施。如果该安全防护措施检测到恶意使用，它可以立即抛出错误并阻止昂贵模型运行，从而节省时间和金钱（**在使用阻塞式安全防护措施时；对于并行安全防护措施，昂贵模型可能会在安全防护措施完成前就已开始运行。详见下方“执行模式”。**）。 +安全防护措施可用于对用户输入和智能体输出进行检查与验证。举例来说，假设你有一个使用非常智能（因此较慢/昂贵）模型来处理客户请求的智能体。你不希望恶意用户让模型帮他们做数学作业。因此，你可以使用一个快速/廉价的模型先运行安全防护措施。如果安全防护措施检测到恶意使用，它可以立即抛出错误并阻止昂贵模型运行，从而节省时间和成本（当使用阻塞式安全防护措施时；对于并行安全防护措施，在其完成前昂贵模型可能已开始运行。详见下文“执行模式”）。 -安全防护措施有两种类型： +安全防护措施分为两类： 1. 输入安全防护措施运行在初始用户输入上 2. 输出安全防护措施运行在最终智能体输出上 @@ -16,42 +16,42 @@ search: 输入安全防护措施分三步运行： 1. 首先，安全防护措施接收与智能体相同的输入。 -2. 接着，运行安全防护措施函数以生成一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后将其包装为一个[`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] -3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，则会抛出一个[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]异常，你可以据此适当回应用户或处理该异常。 +2. 接着，运行安全防护函数以产生一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后被包装为一个[`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] +3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，则抛出[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]异常，你可以据此适当回复用户或处理该异常。 !!! Note - 输入安全防护措施旨在运行于用户输入上，因此只有当该智能体是“第一个”智能体时，其安全防护措施才会运行。你或许会问，为什么 `guardrails` 属性在智能体上，而不是传给 `Runner.run`？这是因为安全防护措施通常与具体的智能体相关——你会为不同的智能体运行不同的安全防护措施，因此将代码放在一起有助于可读性。 + 输入安全防护措施旨在运行于用户输入上，因此仅当该智能体是“第一个”智能体时才会运行该智能体的安全防护措施。你可能会疑惑，为什么 `guardrails` 属性在智能体上，而不是作为参数传给 `Runner.run`？这是因为安全防护措施往往与具体的智能体相关——不同智能体会运行不同的安全防护措施，将代码放在一起有助于可读性。 ### 执行模式 输入安全防护措施支持两种执行模式： -- **并行执行**（默认，`run_in_parallel=True`）：安全防护措施与智能体执行并发运行。由于二者同时开始，这能提供最佳时延。然而，如果安全防护措施失败，智能体可能已经消耗了 token 并在被取消前执行了工具调用。 +- **并行执行**（默认，`run_in_parallel=True`）：安全防护措施与智能体执行并发运行。由于二者同时启动，这提供了最佳延迟。然而，如果安全防护措施判定失败，智能体可能在被取消前已消耗了部分 token 并执行了工具。 -- **阻塞执行**（`run_in_parallel=False`）：安全防护措施在智能体启动之前运行并完成。如果触发了触发线（tripwire），智能体将不会执行，避免 token 消耗和工具调用。这对于成本优化以及当你希望避免工具调用可能带来的副作用时非常理想。 +- **阻塞执行**（`run_in_parallel=False`）：安全防护措施在智能体启动之前运行并完成。如果触发了安全防护触发器，则智能体不会执行，从而避免 token 消耗与工具执行。这对于成本优化以及避免工具调用可能带来的副作用非常理想。 ## 输出安全防护措施 输出安全防护措施分三步运行： 1. 首先，安全防护措施接收智能体生成的输出。 -2. 接着，运行安全防护措施函数以生成一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后将其包装为一个[`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] -3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，则会抛出一个[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]异常，你可以据此适当回应用户或处理该异常。 +2. 接着，运行安全防护函数以产生一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后被包装为一个[`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] +3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，则抛出[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]异常，你可以据此适当回复用户或处理该异常。 !!! Note - 输出安全防护措施旨在运行于最终的智能体输出上，因此只有当该智能体是“最后一个”智能体时，其安全防护措施才会运行。与输入安全防护措施类似，我们这样做是因为安全防护措施通常与具体的智能体相关——你会为不同的智能体运行不同的安全防护措施，因此将代码放在一起有助于可读性。 + 输出安全防护措施旨在运行于最终的智能体输出上，因此仅当该智能体是“最后一个”智能体时才会运行该智能体的安全防护措施。与输入安全防护措施类似，我们这样设计是因为安全防护措施往往与具体的智能体相关——不同智能体会运行不同的安全防护措施，将代码放在一起有助于可读性。 输出安全防护措施总是在智能体完成后运行，因此不支持 `run_in_parallel` 参数。 -## 触发线（tripwires） +## 触发器 -如果输入或输出未通过安全防护措施，安全防护措施可以通过触发线（tripwire）发出信号。一旦我们发现某条安全防护措施触发了触发线，就会立即抛出`{Input,Output}GuardrailTripwireTriggered`异常并停止智能体执行。 +如果输入或输出未通过安全防护措施，安全防护措施可以通过触发器进行标示。一旦检测到某个安全防护措施触发了触发器，我们会立即抛出 `{Input,Output}GuardrailTripwireTriggered` 异常并停止智能体执行。 ## 实现安全防护措施 -你需要提供一个接收输入并返回[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]的函数。在这个示例中，我们将通过在底层运行一个智能体来实现。 +你需要提供一个接收输入并返回[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]的函数。在以下示例中，我们将通过在底层运行一个智能体来实现。 ```python from pydantic import BaseModel @@ -104,12 +104,12 @@ async def main(): print("Math homework guardrail tripped") ``` -1. 我们将在安全防护措施函数中使用这个智能体。 -2. 这是接收智能体输入/上下文并返回结果的安全防护措施函数。 -3. 我们可以在安全防护措施结果中包含额外信息。 +1. 我们将在安全防护函数中使用该智能体。 +2. 这是接收智能体输入/上下文并返回结果的安全防护函数。 +3. 我们可以在安全防护结果中包含额外信息。 4. 这是定义工作流的实际智能体。 -输出安全防护措施与之相似。 +输出安全防护措施与之类似。 ```python from pydantic import BaseModel @@ -164,5 +164,5 @@ async def main(): 1. 这是实际智能体的输出类型。 2. 这是安全防护措施的输出类型。 -3. 这是接收智能体输出并返回结果的安全防护措施函数。 +3. 这是接收智能体输出并返回结果的安全防护函数。 4. 这是定义工作流的实际智能体。 \ No newline at end of file diff --git a/docs/zh/handoffs.md b/docs/zh/handoffs.md index e81d788c7..0d7d3ca4d 100644 --- a/docs/zh/handoffs.md +++ b/docs/zh/handoffs.md @@ -4,19 +4,19 @@ search: --- # 任务转移 -任务转移允许一个智能体将任务委托给另一个智能体。在不同智能体各自专长不同领域的场景中，这尤其有用。例如，一个客服应用可能有分别处理订单状态、退款、常见问题等任务的智能体。 +任务转移允许一个智能体将任务委派给另一个智能体。这在不同智能体各自专精不同领域的场景中特别有用。例如，一个客服应用可能有分别处理订单状态、退款、常见问题等任务的智能体。 -对 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 @@ -32,15 +32,15 @@ triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refun ### 通过 `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 在调用任务转移时提供一些数据。例如，想象一个转移到“升级处理智能体（Escalation agent）”的场景。你可能希望提供一个原因，以便记录。 +在某些情况下，你希望 LLM 在调用任务转移时提供一些数据。例如，设想移交给“升级处理（Escalation）智能体”。你可能希望提供一个原因，以便记录日志。 ```python from pydantic import BaseModel @@ -84,11 +84,11 @@ 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`。 -默认情况下，runner 现在会将之前的记录折叠为一条助理摘要消息（见 [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]）。该摘要位于一个 `` 块内，当同一次运行期间发生多次任务转移时，该块会持续追加新的轮次。你可以通过 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 提供你自己的映射函数，以替换生成的消息，而无需编写完整的 `input_filter`。该默认行为仅在任务转移和运行均未提供显式的 `input_filter` 时适用，因此已自定义负载的现有代码（包括本仓库中的 code examples）将保持当前行为且无需更改。你可以在单次任务转移上通过向 [`handoff(...)`][agents.handoffs.handoff] 传递 `nest_handoff_history=True` 或 `False` 来覆盖嵌套行为，这会设置 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]。如果你只需要更改生成摘要的包装文本，请在运行智能体之前调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及可选的 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 +默认情况下，runner 现在会将先前的对话记录折叠为一个单一的 assistant 总结消息（参见 [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]）。该总结出现在一个 `` 块中，当同一轮运行期间发生多次任务转移时，会持续附加新的轮次。你可以通过 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 提供你自己的映射函数来替换生成的消息，而无需编写完整的 `input_filter`。该默认行为仅在任务转移和运行都未提供显式的 `input_filter` 时生效，因此已自定义载荷的现有代码（包括本仓库中的 code examples）将保持当前行为不变。你可以通过向 [`handoff(...)`][agents.handoffs.handoff] 传入 `nest_handoff_history=True` 或 `False` 来覆盖单次任务转移的嵌套行为，这会设置 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]。如果你只需要更改生成总结的包装文本，请在运行智能体之前调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及可选的 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 -有一些常见模式（例如从历史中移除所有工具调用），已经在 [`agents.extensions.handoff_filters`][] 中为你实现。 +有一些常见模式（例如从历史中移除所有工具调用），已在 [`agents.extensions.handoff_filters`][] 中为你实现。 ```python from agents import Agent, handoff @@ -102,11 +102,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/zh/index.md b/docs/zh/index.md index 4902947b5..013a9c7f5 100644 --- a/docs/zh/index.md +++ b/docs/zh/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 和工具的 LLM -- **任务转移**：允许智能体将特定任务委派给其他智能体 -- **安全防护措施**：支持对智能体输入与输出进行校验 -- **会话**：在多次智能体运行间自动维护对话历史 +- **智能体（Agents）**：配备了 instructions 和 tools 的 LLM +- **任务转移（Handoffs）**：允许智能体将特定任务委派给其他智能体 +- **安全防护措施（Guardrails）**：支持对智能体的输入与输出进行校验 +- **会话（Sessions）**：在智能体多次运行间自动维护对话历史 -配合 Python，这些基本组件足以表达工具与智能体之间的复杂关系，让你在没有陡峭学习曲线的情况下构建真实世界应用。此外，SDK 内置 **追踪**，可用于可视化与调试你的智能体流程，并进一步对其进行评估，甚至为你的应用微调模型。 +结合 Python，这些基本组件足以表达工具与智能体之间的复杂关系，使你无需陡峭的学习曲线即可构建真实世界的应用。此外，SDK 内置了 **追踪（tracing）**，可帮助你可视化和调试智能体流程，并支持评估、甚至为你的应用微调模型。 ## 为什么使用 Agents SDK -该 SDK 的两项核心设计原则： +该 SDK 的两条核心设计原则： -1. 功能足够多，值得使用；抽象足够少，易于上手。 -2. 开箱即用效果出色，同时你可以精确自定义其行为。 +1. 功能足够丰富值得使用，同时基本组件足够少，便于快速上手。 +2. 开箱即用体验优秀，同时你可以精确自定义行为。 -以下是 SDK 的主要特性： +SDK 的主要特性包括： -- 智能体循环：内置循环，负责调用工具、将结果返回给 LLM，并循环直至 LLM 完成。 -- Python 优先：使用语言内置特性编排并串联智能体，而无需学习新的抽象。 -- 任务转移：在多个智能体之间进行协调与委派的强大功能。 -- 安全防护措施：与智能体并行运行输入校验与检查，若检查失败则尽早中断。 -- 会话：跨多次智能体运行自动管理对话历史，免去手动状态管理。 -- 工具调用：将任意 Python 函数变成工具，自动生成模式并提供基于 Pydantic 的校验。 -- 追踪：内置追踪，用于可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具套件。 +- 智能体循环：内置循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。 +- Python 优先：使用内置语言特性编排与串联智能体，而无需学习新的抽象。 +- 任务转移：强大的能力，用于在多个智能体间协调与委派。 +- 安全防护措施：与智能体并行执行输入校验与检查，若检查失败可提前中断。 +- 会话：跨智能体运行自动管理对话历史，免去手动管理状态。 +- 工具调用（Function tools）：将任意 Python 函数转换为工具，自动生成模式并通过 Pydantic 提供校验。 +- 追踪：内置追踪，便于可视化、调试与监控工作流，并可使用 OpenAI 的评估、微调与蒸馏工具套件。 ## 安装 @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_如果运行此示例，请确保已设置 `OPENAI_API_KEY` 环境变量_) +_（如果运行此示例，请确保设置 `OPENAI_API_KEY` 环境变量）_ ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md index 65a10c22e..1807793e6 100644 --- a/docs/zh/mcp.md +++ b/docs/zh/mcp.md @@ -4,34 +4,34 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) 标准化了应用如何向语言模型暴露工具和上下文。摘自官方文档： +[Model context protocol](https://modelcontextprotocol.io/introduction)（MCP）标准化了应用如何向语言模型暴露工具与上下文。来自官方文档： > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI > applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP > provides a standardized way to connect AI models to different data sources and tools. -Agents Python SDK 支持多种 MCP 传输方式。你可以复用现有的 MCP 服务或自行构建，以向智能体暴露文件系统、HTTP 或基于 connector 的工具。 +Agents Python SDK 支持多种 MCP 传输方式。这使你可以复用现有 MCP 服务端，或自行构建以向智能体暴露文件系统、HTTP 或连接器支持的工具。 -## Choosing an MCP integration +## 选择 MCP 集成 -在将 MCP 服务接入智能体前，先确定工具调用应在何处执行，以及可以使用哪些传输方式。下表总结了 Python SDK 支持的选项。 +在将 MCP 服务端接入智能体之前，请先决定工具调用应在何处执行，以及你能访问哪些传输方式。下表总结了 Python SDK 支持的选项。 -| 你的需求 | 推荐选项 | +| 你的需求 | 推荐选项 | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| 让 OpenAI 的 Responses API 代表模型调用可公网访问的 MCP 服务 | **Hosted MCP server tools**，通过 [`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] | +| 让 OpenAI 的 Responses API 代表模型调用可公网访问的 MCP 服务端 | **托管 MCP 服务端工具**，通过 [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| 连接你在本地或远程运行的可流式传输的 HTTP 服务端 | **可流式 HTTP MCP 服务端**，通过 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| 与实现了基于 Server-Sent Events 的 HTTP 的服务端通信 | **HTTP with SSE MCP 服务端**，通过 [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| 启动本地进程并通过 stdin/stdout 通信 | **stdio MCP 服务端**，通过 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -以下各节将逐一介绍每种选项的配置方法，以及何时优先选择特定传输方式。 +下方各节将逐一介绍每个选项的配置方式，以及何时优先选择不同的传输方式。 -## 1. Hosted MCP server tools +## 1. 托管 MCP 服务端工具 -托管工具将整个工具往返流程放入 OpenAI 的基础设施中。你的代码不再负责列举和调用工具，[`HostedMCPTool`][agents.tool.HostedMCPTool] 会将服务器标签（以及可选的 connector 元数据）转发给 Responses API。模型会列举远程服务的工具并直接调用，无需额外回调至你的 Python 进程。托管工具目前适用于支持 Responses API 托管 MCP 集成的 OpenAI 模型。 +托管工具将整个工具往返过程置于 OpenAI 的基础设施中。你的代码无需列举和调用工具，[`HostedMCPTool`][agents.tool.HostedMCPTool] 会将服务端标签（及可选的连接器元数据）转发给 Responses API。模型会列举远程服务端的工具并调用它们，无需对你的 Python 进程进行额外回调。托管工具目前适用于支持 Responses API 托管 MCP 集成的 OpenAI 模型。 -### Basic hosted MCP tool +### 基础托管 MCP 工具 -通过在智能体的 `tools` 列表中添加 [`HostedMCPTool`][agents.tool.HostedMCPTool] 来创建托管工具。`tool_config` 字典与发送至 REST API 的 JSON 相同： +通过在智能体的 `tools` 列表中添加 [`HostedMCPTool`][agents.tool.HostedMCPTool] 创建托管工具。`tool_config` 字典与发送到 REST API 的 JSON 一致： ```python import asyncio @@ -59,11 +59,11 @@ async def main() -> None: asyncio.run(main()) ``` -托管服务会自动暴露其工具；你不需要将其添加到 `mcp_servers`。 +托管服务端会自动暴露其工具；你无需将其添加到 `mcp_servers`。 -### Streaming hosted MCP results +### 托管 MCP 结果的流式传输 -托管工具支持与工具调用相同方式的流式传输。向 `Runner.run_streamed` 传入 `stream=True`，即可在模型仍在运行时消费增量 MCP 输出： +托管工具与工具调用一样支持流式传输。将 `stream=True` 传给 `Runner.run_streamed`，即可在模型仍在思考时消费增量的 MCP 输出： ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -73,9 +73,9 @@ async for event in result.stream_events(): print(result.final_output) ``` -### Optional approval flows +### 可选的审批流程 -如果某个服务可以执行敏感操作，你可以在每次工具执行前要求人工或程序化审批。在 `tool_config` 中配置 `require_approval`，可使用单一策略（`"always"`、`"never"`）或将工具名映射到策略的字典。若要在 Python 中做出决策，提供 `on_approval_request` 回调。 +如果服务端可以执行敏感操作，你可以在每次工具执行前要求人工或程序化审批。在 `tool_config` 中配置 `require_approval`，可设置单一策略（`"always"`、`"never"`）或将工具名称映射到策略的字典。若要在 Python 内做出决策，请提供 `on_approval_request` 回调。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -103,11 +103,11 @@ agent = Agent( ) ``` -回调可以是同步或异步的，并会在模型需要审批数据以继续运行时调用。 +该回调可以是同步或异步的，并会在模型需要审批数据以继续运行时被调用。 -### Connector-backed hosted servers +### 基于连接器的托管服务端 -托管 MCP 也支持 OpenAI connectors。无需提供 `server_url`，改为提供 `connector_id` 和访问令牌。Responses API 负责身份验证，托管服务会暴露该 connector 的工具。 +托管 MCP 也支持 OpenAI 连接器。你可以不提供 `server_url`，而是提供 `connector_id` 和访问令牌。Responses API 负责认证，托管服务端会暴露该连接器的工具。 ```python import os @@ -123,12 +123,12 @@ HostedMCPTool( ) ``` -完整可运行的托管工具示例——包括流式传输、审批和 connectors——见 +完整可运行的托管工具示例（包含流式传输、审批与连接器）见 [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)。 -## 2. Streamable HTTP MCP servers +## 2. 可流式 HTTP MCP 服务端 -当你希望自行管理网络连接时，使用 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你掌控传输或希望在自有基础设施中运行服务并保持低延迟时，Streamable HTTP 服务非常适合。 +当你希望自行管理网络连接时，使用 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你可控传输层，或希望在你的自有基础设施中运行服务端并保持低延迟时，可流式 HTTP 服务端是理想选择。 ```python import asyncio @@ -163,16 +163,16 @@ async def main() -> None: 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)）。 +- `tool_filter` 允许仅暴露工具的子集（参见[工具过滤](#tool-filtering)）。 -## 3. HTTP with SSE MCP servers +## 3. HTTP with SSE MCP 服务端 -如果 MCP 服务实现了带 SSE 的 HTTP 传输，请实例化 [`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，其 API 与 Streamable HTTP 服务相同。 +如果 MCP 服务端实现了基于 SSE 的 HTTP 传输，实例化 [`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，其 API 与可流式 HTTP 服务端相同。 ```python @@ -199,9 +199,9 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP servers +## 4. stdio MCP 服务端 -对于作为本地子进程运行的 MCP 服务，使用 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK 会启动进程、保持管道打开，并在上下文管理器退出时自动关闭。此选项适合快速原型验证，或当服务仅提供命令行入口时使用。 +对于作为本地子进程运行的 MCP 服务端，使用 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK 会启动进程、保持管道打开，并在上下文管理器退出时自动关闭。该选项适用于快速原型验证，或当服务端仅提供命令行入口时。 ```python from pathlib import Path @@ -227,11 +227,11 @@ async with MCPServerStdio( print(result.final_output) ``` -## Tool filtering +## 工具过滤 -每个 MCP 服务都支持工具过滤，以便你仅暴露智能体所需的功能。过滤可以在构造时完成，或在每次运行时动态设置。 +每个 MCP 服务端均支持工具过滤，使你只能暴露智能体所需的函数。过滤可以在构建时或按运行动态进行。 -### Static tool filtering +### 静态工具过滤 使用 [`create_static_tool_filter`][agents.mcp.create_static_tool_filter] 配置简单的允许/阻止列表： @@ -251,11 +251,11 @@ filesystem_server = MCPServerStdio( ) ``` -当同时提供 `allowed_tool_names` 和 `blocked_tool_names` 时，SDK 会先应用允许列表，然后从剩余集合中移除任何被阻止的工具。 +当同时提供 `allowed_tool_names` 与 `blocked_tool_names` 时，SDK 会先应用允许列表，然后从剩余集合中移除被阻止的工具。 -### Dynamic tool filtering +### 动态工具过滤 -对于更复杂的逻辑，传入一个可调用对象，它接收 [`ToolFilterContext`][agents.mcp.ToolFilterContext]。该可调用对象可为同步或异步，当应暴露该工具时返回 `True`。 +对于更复杂的逻辑，传入一个可调用对象，该对象接收 [`ToolFilterContext`][agents.mcp.ToolFilterContext]。该可调用对象可为同步或异步，返回 `True` 表示应暴露该工具。 ```python from pathlib import Path @@ -281,12 +281,12 @@ async with MCPServerStdio( 过滤上下文会暴露当前的 `run_context`、请求工具的 `agent`，以及 `server_name`。 -## Prompts +## 提示词 -MCP 服务还可以提供用于动态生成智能体 instructions 的提示。支持提示的服务会暴露两个方法： +MCP 服务端还可以提供可动态生成智能体指令的提示词。支持提示词的服务端会暴露两个方法： - `list_prompts()` 枚举可用的提示模板。 -- `get_prompt(name, arguments)` 获取具体提示，可选传入参数。 +- `get_prompt(name, arguments)` 获取具体提示词，可选带参数。 ```python from agents import Agent @@ -304,15 +304,15 @@ 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.md) 会自动捕获 MCP 活动，包括： +[追踪](./tracing.md)会自动捕获 MCP 活动，包括： -1. 调用 MCP 服务以列举工具。 +1. 列出工具时对 MCP 服务端的调用。 2. 工具调用中的 MCP 相关信息。 ![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) @@ -320,5 +320,5 @@ agent = Agent( ## 延伸阅读 - [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 演示，包括审批与 connectors。 \ No newline at end of file +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的 stdio、SSE 和可流式 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/zh/models/index.md b/docs/zh/models/index.md index 144582866..e77999416 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,20 +4,20 @@ search: --- # 模型 -Agents SDK 开箱即用地支持两种 OpenAI 模型调用方式： +Agents SDK 开箱即用地支持两种 OpenAI 模型： -- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用全新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 +- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，通过新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，通过 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 ## OpenAI 模型 -当你在初始化 `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_DEFAULT_MODEL` 环境变量。 +如果你希望在所有未设置自定义模型的智能体中始终使用某个特定模型，请在运行智能体之前设置 `OPENAI_DEFAULT_MODEL` 环境变量。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -28,7 +28,7 @@ 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)）时，SDK 会默认应用合理的 `ModelSettings`。具体来说，它会将 `reasoning.effort` 和 `verbosity` 都设置为 `"low"`。如果你想自行构建这些设置，请调用 `agents.models.get_default_model_settings("gpt-5")`。 -针对更低延迟或特定需求，你可以选择不同的模型和设置。要为默认模型调整推理力度，请传入你自己的 `ModelSettings`： +出于更低延迟或特定需求的考虑，你可以选择不同的模型和设置。要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： ```python from openai.types.shared import Reasoning @@ -44,11 +44,11 @@ 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"` 的推理力度，因此本 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 模型 -如果你传入的是非 GPT-5 的模型名且没有自定义 `model_settings`，SDK 会回退到适用于任意模型的通用 `ModelSettings`。 +如果你传入一个非 GPT-5 的模型名且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。 ## 非 OpenAI 模型 @@ -67,29 +67,29 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 使用非 OpenAI 模型的其他方式 -你还可以通过另外 3 种方式集成其他 LLM 提供商（code examples 在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： +你还可以通过另外 3 种方式集成其他 LLM 提供商（code examples [在此](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： -1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望在全局使用一个 `AsyncOpenAI` 实例作为 LLM 客户端的场景。适用于 LLM 提供商具有 OpenAI 兼容 API 端点、且你可以设置 `base_url` 和 `api_key` 的情况。参见可配置示例：[examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] 用在 `Runner.run` 层级。它允许你为“本次运行中的所有智能体使用自定义模型提供商”。参见可配置示例：[examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。 -3. [`Agent.model`][agents.agent.Agent.model] 允许你在某个特定的 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] 适用于你希望在全局使用一个 `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 key，我们建议通过 `set_tracing_disabled()` 禁用 追踪，或设置一个[不同的追踪 进程](../tracing.md)。 +如果你没有来自 `platform.openai.com` 的 API key，建议通过 `set_tracing_disabled()` 禁用追踪，或设置一个[不同的追踪进程](../tracing.md)。 !!! note - 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供商尚未支持 Responses API。如果你的 LLM 提供商支持它，我们建议使用 Responses。 + 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供商尚不支持 Responses API。如果你的 LLM 提供商支持，建议使用 Responses。 -## 模型的混合与搭配 +## 混合与搭配模型 -在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以在分诊时使用更小、更快的模型，而在复杂任务中使用更大、更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式选择特定模型： +在单个工作流中，你可能希望为每个智能体使用不同的模型。例如，可以为分诊使用更小更快的模型，而为复杂任务使用更大更强的模型。在配置 [`Agent`][agents.Agent] 时，你可以通过以下方式之一选择特定模型： 1. 传入模型名称。 -2. 传入任意模型名称 + 一个可以将该名称映射到 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 +2. 传入任意模型名称 + 一个可将该名称映射到 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 3. 直接提供一个 [`Model`][agents.models.interface.Model] 实现。 !!!note - 虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议在每个工作流中使用单一模型形态，因为两种形态所支持的特性和工具不同。如果你的工作流需要混合使用不同的模型形态，请确保你所用的所有特性在两种形态上都可用。 + 虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议在每个工作流中使用单一模型形态，因为这两种形态支持的功能和工具集不同。如果你的工作流需要混用不同模型形态，请确保你所使用的所有功能在两种形态上都可用。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -125,7 +125,7 @@ async def main(): 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 @@ -158,22 +158,22 @@ english_agent = Agent( ### 追踪客户端错误 401 -如果你遇到与 追踪 相关的错误，这是因为追踪数据会上传到 OpenAI 服务，而你没有 OpenAI API key。你可以通过以下三种方式解决： +如果你遇到与追踪相关的错误，这是因为追踪会上传到 OpenAI 服务，而你没有 OpenAI API key。你有三种解决方案： 1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. 为追踪设置一个 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传追踪数据，且必须来自 [platform.openai.com](https://platform.openai.com/)。 -3. 使用非 OpenAI 的追踪 进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。 +2. 为追踪设置一个 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。 +3. 使用非 OpenAI 的追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。 ### Responses API 支持 -SDK 默认使用 Responses API，但大多数其他 LLM 提供商尚未支持它。因此你可能会看到 404 或类似问题。要解决，你有两种选择： +SDK 默认使用 Responses API，但大多数其他 LLM 提供商尚不支持它。因此你可能会看到 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]。相关 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 支持 -有些模型提供商不支持 [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、多模态输入、以及托管的 文件检索 和 网络检索，但许多其他提供商并不支持这些特性。请注意以下限制： +你需要了解不同模型提供商之间的功能差异，否则可能会遇到错误。比如，OpenAI 支持 structured outputs、多模态输入，以及托管的 文件检索 和 网络检索，但许多其他提供商并不支持这些功能。请注意以下限制： - 不要向不支持的提供商发送其无法理解的 `tools` - 在调用仅支持文本的模型之前，过滤掉多模态输入 -- 注意不支持结构化 JSON 输出的提供商偶尔会产生无效的 JSON。 \ No newline at end of file +- 注意不支持结构化 JSON 输出的提供商偶尔会生成无效的 JSON。 \ No newline at end of file diff --git a/docs/zh/models/litellm.md b/docs/zh/models/litellm.md index 34dc18a08..7b328d662 100644 --- a/docs/zh/models/litellm.md +++ b/docs/zh/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 集成处于 beta 阶段。你可能会在某些模型提供商（尤其是较小的）上遇到问题。请通过 [Github issues](https://github.com/openai/openai-agents-python/issues) 提交问题，我们会尽快修复。 -[LiteLLM](https://docs.litellm.ai/docs/) 是一个库，允许你通过统一接口使用 100+ 模型。我们在 Agents SDK 中加入了 LiteLLM 集成，让你可以使用任意 AI 模型。 +[LiteLLM](https://docs.litellm.ai/docs/) 是一个库，可通过统一接口使用 100+ 模型。我们已添加 LiteLLM 集成，使你可以在 Agents SDK 中使用任意 AI 模型。 ## 设置 -你需要确保可用 `litellm`。可以通过安装可选的 `litellm` 依赖组来完成： +你需要确保可用的 `litellm`。可通过安装可选的 `litellm` 依赖组完成： ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 示例 -这是一个可直接运行的示例。运行后会提示输入模型名称和 API 密钥。例如，你可以输入： +这是一个可直接运行的示例。运行时会提示你输入模型名称和 API key。例如，你可以输入： -- `openai/gpt-4.1` 作为模型，以及你的 OpenAI API 密钥 -- `anthropic/claude-3-5-sonnet-20240620` 作为模型，以及你的 Anthropic API 密钥 -- 等等 +- `openai/gpt-4.1` 作为模型，并提供你的 OpenAI API key +- `anthropic/claude-3-5-sonnet-20240620` 作为模型，并提供你的 Anthropic API key +- 等等 -有关 LiteLLM 支持的完整模型列表，请参见 [litellm providers 文档](https://docs.litellm.ai/docs/providers)。 +有关 LiteLLM 支持的完整模型列表，请参见 [litellm providers docs](https://docs.litellm.ai/docs/providers)。 ```python from __future__ import annotations @@ -78,7 +78,7 @@ if __name__ == "__main__": ## 使用数据追踪 -如果你希望 LiteLLM 的响应填充到 Agents SDK 的使用指标中，在创建智能体时传入 `ModelSettings(include_usage=True)`。 +如果你希望将 LiteLLM 的响应计入 Agents SDK 的使用指标，请在创建智能体时传入 `ModelSettings(include_usage=True)`。 ```python from agents import Agent, ModelSettings @@ -91,4 +91,4 @@ agent = Agent( ) ``` -设置 `include_usage=True` 后，LiteLLM 请求会像内置的 OpenAI 模型一样，通过 `result.context_wrapper.usage` 报告 token 与请求计数。 \ No newline at end of file +使用 `include_usage=True` 后，LiteLLM 请求会像内置的 OpenAI 模型一样，通过 `result.context_wrapper.usage` 报告 token 和请求计数。 \ No newline at end of file diff --git a/docs/zh/multi_agent.md b/docs/zh/multi_agent.md index 86ee1ab6f..8bea0e2bf 100644 --- a/docs/zh/multi_agent.md +++ b/docs/zh/multi_agent.md @@ -2,40 +2,40 @@ search: exclude: true --- -# 编排多个智能体 +# 多智能体编排 -编排指的是应用中智能体的流转：哪些智能体运行、以什么顺序运行、以及它们如何决定下一步做什么。编排智能体主要有两种方式： +编排指的是你在应用中对智能体的流程控制：哪些智能体运行、按什么顺序运行、以及它们如何决定下一步。编排智能体主要有两种方式： -1. 让 LLM 做出决策：利用 LLM 的智能进行规划、推理，并据此决定要采取的步骤。 -2. 通过代码进行编排：用代码来确定智能体的流程。 +1. 让 LLM 做决策：利用 LLM 的智能来规划、推理，并据此决定采取哪些步骤。 +2. 通过代码进行编排：用你的代码来确定智能体的执行流程。 -你可以混合使用这些模式。每种方式都有取舍，下文将进行说明。 +你可以混合使用这些模式。它们各有取舍，详见下文。 ## 通过 LLM 编排 -智能体是配备了指令（instructions）、工具（tools）和任务转移（handoffs）的 LLM。这意味着面对一个开放式任务时，LLM 可以自主规划如何处理该任务，使用工具采取行动和获取数据，并通过任务转移将任务委派给子智能体。比如，一个研究型智能体可以配备以下工具： +一个智能体是配备了 instructions、工具和 任务转移 的 LLM。这意味着面对一个开放式任务时，LLM 可以自主规划其完成方式，使用工具来执行操作和获取数据，并通过 任务转移 将任务委派给子智能体。比如，一个研究智能体可以配备以下工具： - 网络检索，用于在网上查找信息 -- 文件检索与读取，用于搜索专有数据与连接 -- 计算机操作，以在计算机上执行动作 +- 文件检索与获取，用于在专有数据与连接中搜索 +- 计算机操作，用于在计算机上执行操作 - 代码执行，用于进行数据分析 -- 任务转移到擅长规划、撰写报告等的专业智能体 +- 任务转移，到擅长规划、写作报告等的专业智能体 -当任务是开放式且你希望依赖 LLM 的智能时，这种模式非常适合。这里最重要的做法包括： +当任务是开放式且你希望依赖 LLM 的智能时，这种模式非常适合。关键做法包括： -1. 投入精力打造优质提示词。明确可用的工具、如何使用它们，以及必须遵循的参数与边界。 -2. 监控你的应用并持续迭代。观察问题出现在哪里，并迭代优化提示词。 -3. 允许智能体自我反思与改进。例如，将其置于循环中，让它自我批评；或者提供错误信息，让其改进。 -4. 使用在单一任务上表现卓越的专用智能体，而不是期望一个通用智能体能面面俱到。 -5. 投入到[评测](https://platform.openai.com/docs/guides/evals)。这能帮助你训练智能体提升能力，更好地完成任务。 +1. 打磨高质量提示词。明确可用工具、使用方式，以及必须遵循的参数与边界。 +2. 监控你的应用并迭代优化。观察问题出现的位置，并迭代你的提示词。 +3. 允许智能体自省与改进。例如在循环中运行并让其自我评议；或提供错误信息并让其改进。 +4. 让专业智能体各司其职，而不是指望一个通用智能体样样精通。 +5. 投入于[评测](https://platform.openai.com/docs/guides/evals)。这可帮助你训练智能体改进并提升任务表现。 ## 通过代码编排 -虽然通过 LLM 编排很强大，但通过代码编排在速度、成本和性能方面更具确定性和可预测性。常见模式包括： +尽管通过 LLM 编排很强大，但通过代码编排在速度、成本和性能方面更具确定性和可预测性。常见模式包括： -- 使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)生成你可以用代码检查的格式良好的数据。例如，你可以让智能体将任务分类为几个目录，然后基于该目录选择下一个智能体。 -- 将多个智能体串联起来，把一个智能体的输出转换为下一个的输入。你可以把写博客这样的任务分解为一系列步骤——先做研究、写提纲、写正文、批评与改进。 -- 用一个执行任务的智能体与一个负责评估和反馈的智能体在 `while` 循环中运行，直到评估者认为输出满足特定标准为止。 -- 并行运行多个智能体，例如通过 Python 基本组件如 `asyncio.gather`。当有多个彼此不依赖的任务时，这对提升速度很有用。 +- 使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)生成可由你的代码检查的 格式良好的数据。比如，你可以让智能体将任务分类到几个目录中，然后基于该目录选择下一个智能体。 +- 将多个智能体串联，把一个的输出转成下一个的输入。你可以将撰写博客这样的任务分解为一系列步骤——做研究、写大纲、写正文、评议并改进。 +- 将执行任务的智能体与进行评估并提供反馈的智能体一起在 `while` 循环中运行，直到评估者确认输出通过某些标准。 +- 并行运行多个智能体，例如通过 Python 基本组件如 `asyncio.gather`。当你有多个彼此独立的任务时，这有助于提速。 -我们在[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)中提供了许多示例。 \ No newline at end of file +我们在[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)中提供了许多代码示例。 \ No newline at end of file diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index 5d4570827..9b3e12965 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -2,9 +2,9 @@ search: exclude: true --- -# 快速入门 +# 快速开始 -## 项目与虚拟环境创建 +## 创建项目和虚拟环境 你只需执行一次。 @@ -14,7 +14,7 @@ cd my_project python -m venv .venv ``` -### 虚拟环境激活 +### 激活虚拟环境 每次开启新的终端会话时都需要执行。 @@ -36,7 +36,7 @@ pip install openai-agents # or `uv add openai-agents`, etc export OPENAI_API_KEY=sk-... ``` -## 第一个智能体创建 +## 创建你的第一个智能体 智能体由 instructions、名称和可选配置（例如 `model_config`）定义。 @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## 更多智能体添加 +## 添加更多智能体 -可以用相同方式定义其他智能体。`handoff_descriptions` 提供用于确定任务转移路由的额外上下文。 +可以用相同方式定义其他智能体。`handoff_descriptions` 为确定任务转移路由提供额外上下文。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## 任务转移定义 +## 定义你的任务转移 -在每个智能体上，你可以定义一份可选的外向任务转移清单，智能体可从中选择以决定如何推进其任务。 +在每个智能体上，你可以定义一个可用的外发任务转移选项清单，供智能体选择以决定如何推进其任务。 ```python triage_agent = Agent( @@ -81,9 +81,9 @@ triage_agent = Agent( ) ``` -## 智能体编排运行 +## 运行智能体编排 -让我们检查工作流是否运行，以及分诊智能体是否在两个专家智能体之间正确路由。 +让我们检查工作流是否运行，并且分诊智能体是否在两个专家型智能体之间正确路由。 ```python from agents import Runner @@ -93,9 +93,9 @@ async def main(): print(result.final_output) ``` -## 安全防护措施添加 +## 添加安全防护措施 -你可以定义自定义的安全防护措施在输入或输出阶段运行。 +你可以为输入或输出定义自定义安全防护措施。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 整体整合 +## 集成运行 -让我们把以上内容整合起来，运行整个工作流，使用任务转移和输入安全防护措施。 +把以上全部组合起来，运行完整工作流，使用任务转移和输入安全防护措施。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,9 +190,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 追踪查看 +## 查看你的追踪 -要回顾智能体运行期间发生的事件，请前往 [OpenAI 控制台中的 Trace viewer](https://platform.openai.com/traces) 查看你的运行追踪。 +要回顾智能体运行期间发生的事情，请前往 [OpenAI 控制台的 Trace viewer](https://platform.openai.com/traces) 查看你的智能体运行追踪。 ## 后续步骤 @@ -200,4 +200,4 @@ if __name__ == "__main__": - 学习如何配置[智能体](agents.md)。 - 了解[运行智能体](running_agents.md)。 -- 了解[工具](tools.md)、[安全防护措施](guardrails.md)和[模型](models/index.md)。 \ No newline at end of file +- 了解[tools](tools.md)、[安全防护措施](guardrails.md)和[模型](models/index.md)。 \ No newline at end of file diff --git a/docs/zh/realtime/guide.md b/docs/zh/realtime/guide.md index 2ae9fbadb..72dea435c 100644 --- a/docs/zh/realtime/guide.md +++ b/docs/zh/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # 指南 -本指南将深入介绍如何使用 OpenAI Agents SDK 的实时功能来构建语音驱动的 AI 智能体。 +本指南将深入介绍如何使用 OpenAI Agents SDK 的实时功能构建支持语音的 AI 智能体。 !!! warning "Beta feature" -实时智能体处于 Beta 阶段。随着实现的改进，可能会发生不兼容的变更。 +实时智能体处于测试阶段。随着我们改进实现，可能会发生不兼容变更。 -## 概览 +## 概述 -实时智能体支持会话式流程，可实时处理音频与文本输入，并以实时音频作出响应。它们与 OpenAI 的 Realtime API 保持持久连接，从而实现低延迟的自然语音对话，并能优雅地处理打断。 +实时智能体支持会话式交互，可实时处理音频与文本输入，并以实时音频作出响应。它们与 OpenAI 的 Realtime API 保持持久连接，实现低延迟、可自然打断的语音对话体验。 ## 架构 ### 核心组件 -实时系统由以下关键组件组成： +实时系统由以下关键组件构成： -- **RealtimeAgent**: 一个智能体，通过 instructions、tools 和 任务转移 进行配置。 -- **RealtimeRunner**: 管理配置。你可以调用 `runner.run()` 获取一个会话。 -- **RealtimeSession**: 单次交互会话。通常在每次用户发起对话时创建一个，并保持其存活直到对话结束。 -- **RealtimeModel**: 底层模型接口（通常是 OpenAI 的 WebSocket 实现） +- **RealtimeAgent**: 一个智能体，由 instructions、tools 和 任务转移（handoffs）进行配置。 +- **RealtimeRunner**: 管理配置。可调用 `runner.run()` 获取一个会话。 +- **RealtimeSession**: 一次交互会话。通常在每次用户开始对话时创建一个，并保持至对话结束。 +- **RealtimeModel**: 底层模型接口（通常是 OpenAI 的 WebSocket 实现） ### 会话流程 典型的实时会话流程如下： -1. **创建你的 RealtimeAgent**，并配置 instructions、tools 和 任务转移。 -2. **设置 RealtimeRunner**，传入智能体和配置选项 -3. **启动会话**，使用 `await runner.run()` 返回一个 RealtimeSession。 -4. **向会话发送音频或文本消息**，使用 `send_audio()` 或 `send_message()` -5. **监听事件**，通过迭代会话对象获取事件——包括音频输出、转写、工具调用、任务转移以及错误 -6. **处理打断**，当用户打断发言时，会自动停止当前音频生成 +1. 使用 instructions、tools 和 任务转移（handoffs）**创建 RealtimeAgent（们）**。 +2. **设置 RealtimeRunner**，指定智能体与配置选项。 +3. 使用 `await runner.run()` **启动会话**，返回一个 RealtimeSession。 +4. 使用 `send_audio()` 或 `send_message()` **向会话发送音频或文本消息**。 +5. **监听事件**，通过遍历会话对象来获取事件——事件包括音频输出、转写文本、工具调用、任务转移以及错误等。 +6. **处理中断**，当用户打断发言时，会自动停止当前音频生成。 会话会维护对话历史，并管理与实时模型的持久连接。 ## 智能体配置 -RealtimeAgent 的工作方式与常规 Agent 类似，但有一些关键差异。完整 API 详情参见 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 参考。 +RealtimeAgent 的工作方式与常规 Agent 类似，但有一些关键差异。完整 API 详情请参阅 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 参考。 与常规智能体的主要差异： -- 模型选择在会话级别配置，而非智能体级别。 -- 不支持 structured outputs（不支持 `outputType`）。 -- 语音可按智能体配置，但在第一个智能体开始说话后无法更改。 -- 其他特性如 tools、任务转移 和 instructions 的工作方式相同。 +- 模型选择在会话级配置，而不是智能体级。 +- 不支持 structured outputs（不支持 `outputType`）。 +- 语音可按智能体配置，但在首次发声后无法更改。 +- 其他功能（如 tools、任务转移和 instructions）与常规智能体相同。 ## 会话配置 ### 模型设置 -会话配置允许你控制底层实时模型的行为。你可以配置模型名称（如 `gpt-realtime`）、语音选择（alloy、echo、fable、onyx、nova、shimmer），以及支持的模态（文本和/或音频）。可为输入和输出设置音频格式，默认是 PCM16。 +会话配置可控制底层实时模型的行为。你可以配置模型名称（如 `gpt-realtime`）、语音选择（alloy、echo、fable、onyx、nova、shimmer）以及支持的模态（文本和/或音频）。音频格式可分别为输入与输出设置，默认使用 PCM16。 ### 音频配置 -音频设置控制会话如何处理语音输入与输出。你可以使用诸如 Whisper 的模型配置输入音频转写、设置语言偏好，并提供转写提示以提升特定领域术语的准确性。轮次检测设置控制智能体何时开始与停止响应，可配置语音活动检测阈值、静音时长以及检测语音的前后填充。 +音频设置控制会话如何处理语音输入与输出。你可以使用诸如 Whisper 的模型进行输入音频转写、设置语言偏好，并提供转写提示以提高领域术语的准确性。轮次检测（turn detection）设置控制智能体何时开始和停止响应，提供语音活动检测阈值、静音时长以及对检测到的语音的前后填充等选项。 ## 工具与函数 ### 添加工具 -与常规智能体一样，实时智能体支持在对话中执行的 工具调用： +与常规智能体相同，实时智能体支持在对话中执行的 工具调用： ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### 创建任务转移 -任务转移允许在专业化智能体之间转移对话。 +任务转移允许在不同的专业化智能体之间转移会话。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## 事件处理 -会话会以流式方式发送事件，你可以通过迭代会话对象来监听。事件包括音频输出分片、转写结果、工具执行开始与结束、智能体任务转移以及错误。需要重点处理的事件包括： +会话会以流式方式发送事件，你可以通过遍历会话对象来监听。事件包括音频输出分片、转写结果、工具执行开始与结束、智能体任务转移以及错误。需要重点处理的事件包括： -- **audio**: 来自智能体响应的原始音频数据 -- **audio_end**: 智能体结束发言 -- **audio_interrupted**: 用户打断了智能体 -- **tool_start/tool_end**: 工具执行的生命周期 -- **handoff**: 发生了智能体任务转移 -- **error**: 处理过程中发生错误 +- **audio**: 智能体响应的原始音频数据 +- **audio_end**: 智能体结束发声 +- **audio_interrupted**: 用户打断了智能体 +- **tool_start/tool_end**: 工具执行生命周期 +- **handoff**: 发生了智能体任务转移 +- **error**: 处理过程中发生错误 -完整事件详情参见 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]。 +完整事件详情请参阅 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]。 ## 安全防护措施 -实时智能体仅支持输出安全防护措施。这些安全防护措施会进行防抖并定期运行（不是每个词都执行），以避免实时生成过程中的性能问题。默认防抖长度为 100 个字符，但可配置。 +实时智能体仅支持输出安全防护措施。这些防护采用去抖动策略，定期运行（非每个词触发），以避免实时生成过程中的性能问题。默认去抖长度为 100 个字符，可进行配置。 -安全防护措施可直接附加到 `RealtimeAgent`，也可通过会话的 `run_config` 提供。来自两处的防护会共同生效。 +可以将安全防护措施直接附加到 `RealtimeAgent`，或通过会话的 `run_config` 提供。两处提供的防护会共同生效。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,19 +152,19 @@ agent = RealtimeAgent( ) ``` -当安全防护措施被触发时，会生成 `guardrail_tripped` 事件，并可打断智能体当前的响应。防抖行为有助于在安全性与实时性能之间取得平衡。与文本智能体不同，实时智能体在触发安全防护措施时**不会**抛出异常。 +当安全防护措施被触发时，会生成 `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` 事件，以便在用户打断智能体时立即停止播放，并清空任何已排队的音频。 +对于音频输出，监听 `audio` 事件，并通过你偏好的音频库播放音频数据。务必监听 `audio_interrupted` 事件，以便在用户打断智能体时立即停止播放并清空已排队的音频。 ## SIP 集成 -你可以将实时智能体附加到通过 [Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip) 到达的电话呼叫。SDK 提供了 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]，在通过 SIP 协商媒体的同时复用相同的智能体流程。 +你可以将实时智能体附加到通过 [Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip) 接入的来电。SDK 提供了 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]，在通过 SIP 协商媒体的同时复用相同的智能体流程。 -要使用它，请将模型实例传给 runner，并在启动会话时提供 SIP 的 `call_id`。呼叫 ID 由指示来电的 webhook 传递。 +要使用它，将该模型实例传入 runner，并在启动会话时提供 SIP 的 `call_id`。来电的 Call ID 由指示来电的 webhook 传递。 ```python from agents.realtime import RealtimeAgent, RealtimeRunner @@ -187,7 +187,7 @@ async with await runner.run( ... ``` -当主叫挂断时，SIP 会话结束，实时连接会自动关闭。完整的电话集成示例参见 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip)。 +当主叫方挂断时，SIP 会话结束，实时连接会自动关闭。完整电话集成示例参见 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip)。 ## 直接访问模型 @@ -198,8 +198,8 @@ async with await runner.run( session.model.add_listener(my_custom_listener) ``` -这将为你提供对 [`RealtimeModel`][agents.realtime.model.RealtimeModel] 接口的直接访问，适用于需要更低层连接控制的高级用例。 +这将为你提供对 [`RealtimeModel`][agents.realtime.model.RealtimeModel] 接口的直接访问，适用于需要对连接进行更底层控制的高级用例。 ## 示例 -完整可运行示例请查看 [examples/realtime 目录](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)，其中包含带 UI 和不带 UI 的演示。 \ No newline at end of file +如需完整可运行的示例，请查看 [examples/realtime 目录](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)，其中包含带 UI 与不带 UI 的演示。 \ No newline at end of file diff --git a/docs/zh/realtime/quickstart.md b/docs/zh/realtime/quickstart.md index e2c92fa1d..82a731e16 100644 --- a/docs/zh/realtime/quickstart.md +++ b/docs/zh/realtime/quickstart.md @@ -4,12 +4,12 @@ search: --- # 快速开始 -实时智能体通过 OpenAI 的 Realtime API 让你的 AI 智能体具备语音对话能力。本指南将带你创建第一个实时语音智能体。 +Realtime 智能体通过 OpenAI 的 Realtime API 实现与 AI 智能体的语音对话。本指南将带你创建你的第一个实时语音智能体。 !!! warning "测试版功能" -Realtime 智能体处于测试阶段。随着实现的改进，可能会出现不兼容的变更。 +Realtime 智能体目前为测试版。随着实现的改进，可能会有不兼容的变更。 -## 先决条件 +## 前提条件 - Python 3.9 或更高版本 - OpenAI API 密钥 @@ -198,28 +198,28 @@ if __name__ == "__main__": ### 音频设置 -- `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`: 说话前的音频填充 +- `silence_duration_ms`: 用于检测轮次结束的静音时长 +- `prefix_padding_ms`: 语音开始前的音频填充 ## 后续步骤 - [进一步了解实时智能体](guide.md) -- 查看 [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 文件夹中的可用示例 +- 在 [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 文件夹中查看可运行示例 - 为你的智能体添加工具 - 在智能体之间实现任务转移 -- 设置安全防护措施以保证安全 +- 设置安全防护措施以确保安全 ## 身份验证 -确保在环境中设置了你的 OpenAI API 密钥： +请确保在你的环境中设置了 OpenAI API 密钥： ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/zh/release.md b/docs/zh/release.md index 3f4432066..2c072c709 100644 --- a/docs/zh/release.md +++ b/docs/zh/release.md @@ -2,42 +2,42 @@ search: exclude: true --- -# 发布流程/变更日志 +# 发布流程/更新日志 -本项目采用略作修改的语义化版本控制，形式为 `0.Y.Z`。前导的 `0` 表示该 SDK 仍在快速演进中。各组件的递增规则如下： +该项目采用经过轻微修改的语义化版本控制，形式为 `0.Y.Z`。前导的 `0` 表示该 SDK 仍在快速演进中。各组件按如下方式递增： -## 次要（`Y`）版本 +## 次版本（`Y`） -对于未标记为 beta 的任何公共接口出现**破坏性变更**时，我们会提升次要版本 `Y`。例如，从 `0.0.x` 升级到 `0.1.x` 可能包含破坏性变更。 +对于未标记为 beta 的任何公共接口出现**破坏性变更**时，我们将增加次版本号 `Y`。例如，从 `0.0.x` 到 `0.1.x` 可能包含破坏性变更。 -如果你不希望引入破坏性变更，建议在你的项目中固定到 `0.0.x` 版本。 +如果你不希望引入破坏性变更，建议在项目中固定到 `0.0.x` 版本。 -## 补丁（`Z`）版本 +## 修订版本（`Z`） -对于非破坏性变更，我们会递增 `Z`： +对于非破坏性变更，我们将增加 `Z`： - Bug 修复 -- 新增特性 -- 对私有接口的更改 -- 对 beta 特性的更新 +- 新功能 +- 私有接口的变更 +- beta 功能的更新 ## 破坏性变更日志 ### 0.6.0 -在该版本中，默认的任务转移历史现被打包为单条 assistant 消息，而不是暴露原始的用户/assistant 轮次，从而为下游智能体提供简洁、可预测的回顾 -- 现有的单消息任务转移记录默认以 "For context, here is the conversation so far between the user and the previous agent:" 开始，位于 `` 块之前，以便下游智能体获得清晰标注的回顾 +在该版本中，默认的任务转移历史现在被封装为单条助手消息，而不是暴露原始的 用户/助手 轮次，从而为下游智能体提供简洁、可预测的回顾 +- 现有的单消息任务转移记录现在默认在 `` 块之前以“For context, here is the conversation so far between the user and the previous agent:”开头，以便下游智能体获得清晰标注的回顾 ### 0.5.0 -此版本没有引入可见的破坏性变更，但包含新特性以及若干重要的底层更新： +该版本未引入可见的破坏性变更，但包含新功能以及一些重要的底层更新： -- 为 `RealtimeRunner` 新增了处理 [SIP 协议连接](https://platform.openai.com/docs/guides/realtime-sip) 的支持 -- 大幅修订了 `Runner#run_sync` 的内部逻辑，以兼容 Python 3.14 +- 为 `RealtimeRunner` 添加对 [SIP 协议连接](https://platform.openai.com/docs/guides/realtime-sip) 的支持 +- 大幅修订了 `Runner#run_sync` 的内部逻辑以兼容 Python 3.14 ### 0.4.0 -在该版本中，[openai](https://pypi.org/project/openai/) 包的 v1.x 版本不再受支持。请将 openai 升级到 v2.x 并与本 SDK 搭配使用。 +在该版本中，不再支持 [openai](https://pypi.org/project/openai/) 包的 v1.x 版本。请将 openai 升级到 v2.x 并与本 SDK 搭配使用。 ### 0.3.0 @@ -45,8 +45,8 @@ search: ### 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`。你需要为继承 `MCPServer` 的任何类添加这些参数。 \ No newline at end of file +在该版本中，[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] 新增两个参数：`run_context` 和 `agent`。你需要在任何继承 `MCPServer` 的类中添加这些参数。 \ No newline at end of file diff --git a/docs/zh/repl.md b/docs/zh/repl.md index 9d033b672..4f3437246 100644 --- a/docs/zh/repl.md +++ b/docs/zh/repl.md @@ -4,7 +4,7 @@ search: --- # REPL 实用工具 -该 SDK 提供 `run_demo_loop`，可在你的终端中直接对智能体的行为进行快速、交互式测试。 +该 SDK 提供 `run_demo_loop`，可在终端中快速、交互式地测试智能体的行为。 ```python import asyncio @@ -18,6 +18,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` 会在循环中提示用户输入，并在每轮之间保留对话历史。默认情况下，它会在生成时流式传输模型输出。运行上面的示例时，run_demo_loop 会启动一个交互式聊天会话。它会持续请求你的输入，在轮次之间记住完整的对话历史（使你的智能体了解已讨论的内容），并在生成过程中实时将智能体的回复以流式传输方式输出给你。 +`run_demo_loop` 会在循环中提示用户输入，并在回合之间保留对话历史。默认情况下，它会在模型生成输出时进行流式传输。运行上述示例后，run_demo_loop 会启动交互式聊天会话：它会持续请求你的输入、在回合之间记住完整的对话历史（使你的智能体了解已讨论内容），并在生成过程中将智能体的响应实时流式传输给你。 -若要结束此聊天会话，只需输入 `quit` 或 `exit`（并按 Enter），或使用 `Ctrl-D` 键盘快捷键。 \ No newline at end of file +要结束此聊天会话，只需输入 `quit` 或 `exit`（然后按 Enter），或使用键盘快捷键 `Ctrl-D`。 \ No newline at end of file diff --git a/docs/zh/results.md b/docs/zh/results.md index af05da163..012d9ef56 100644 --- a/docs/zh/results.md +++ b/docs/zh/results.md @@ -6,51 +6,51 @@ search: 当你调用 `Runner.run` 方法时，你会得到： -- 如果调用 `run` 或 `run_sync`，则返回 [`RunResult`][agents.result.RunResult] -- 如果调用 `run_streamed`，则返回 [`RunResultStreaming`][agents.result.RunResultStreaming] +- [运行结果（RunResult）][agents.result.RunResult]，如果你调用的是 `run` 或 `run_sync` +- [流式运行结果（RunResultStreaming）][agents.result.RunResultStreaming]，如果你调用的是 `run_streamed` -二者都继承自 [`RunResultBase`][agents.result.RunResultBase]，其中包含大多数有用信息。 +这两者都继承自[运行结果基类（RunResultBase）][agents.result.RunResultBase]，大多数有用信息都在这里。 ## 最终输出 -[`final_output`][agents.result.RunResultBase.final_output] 属性包含最后一个运行的智能体的最终输出。它可能是： +[`final_output`][agents.result.RunResultBase.final_output] 属性包含最后一个运行的智能体的最终输出。可能是： -- `str`，如果最后一个智能体没有定义 `output_type` -- 类型为 `last_agent.output_type` 的对象，如果该智能体定义了输出类型 +- `str`，如果最后一个智能体未定义 `output_type` +- 类型为 `last_agent.output_type` 的对象，如果该智能体定义了输出类型。 !!! note - `final_output` 的类型为 `Any`。由于存在 任务转移，我们无法进行静态类型标注。如果发生 任务转移，意味着任意智能体都可能成为最后一个，因此我们无法静态地知道可能的输出类型集合。 + `final_output` 的类型为 `Any`。由于存在任务转移，我们无法进行静态类型标注。如果发生任务转移，意味着任意智能体都可能成为最后一个，因此我们无法静态地知道可能的输出类型集合。 ## 下一轮输入 -你可以使用 [`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 将结果转换为一个输入列表，该列表把你提供的原始输入与智能体运行期间生成的条目进行拼接。这样可以方便地将一次智能体运行的输出传递给另一次运行，或在循环中运行并每次附加新的用户输入。 +你可以使用 [`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 将结果转换为一个输入列表，该列表把你提供的原始输入与智能体运行期间生成的条目连接起来。这样便于将一次智能体运行的输出传递给另一次运行，或者在循环中每次追加新的用户输入。 ## 最后一个智能体 -[`last_agent`][agents.result.RunResultBase.last_agent] 属性包含最后一个运行的智能体。根据你的应用，这通常对下一次用户输入很有用。例如，如果你有一个前线分诊智能体会将任务转移给特定语言的智能体，你可以存储下最后一个智能体，并在下次用户向智能体发送消息时复用它。 +[`last_agent`][agents.result.RunResultBase.last_agent] 属性包含最后一个运行的智能体。根据你的应用，这对下一次用户输入时通常很有用。例如，如果你有一个一线分诊智能体会将任务转移到某个特定语言的智能体，你可以存储并在下次用户向智能体发送消息时复用这个最后的智能体。 -## 新增条目 +## 新条目 -[`new_items`][agents.result.RunResultBase.new_items] 属性包含本次运行期间生成的新条目。条目是 [`RunItem`][agents.items.RunItem]。运行条目封装了由 LLM 生成的原始条目。 +[`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 的推理条目。原始条目是生成的推理内容。 +- [消息输出条目（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] 属性包含安全防护措施的结果（如果有）。安全防护措施结果有时包含你可能希望记录或存储的有用信息，因此我们将其提供给你。 +[`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]。 +[`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/zh/running_agents.md b/docs/zh/running_agents.md index 7938e4cec..1d20ee790 100644 --- a/docs/zh/running_agents.md +++ b/docs/zh/running_agents.md @@ -4,11 +4,11 @@ search: --- # 运行智能体 -你可以通过 [`Runner`][agents.run.Runner] 类来运行智能体。你有 3 种选择： +你可以通过 [`Runner`][agents.run.Runner] 类来运行智能体。你有 3 种方式： -1. [`Runner.run()`][agents.run.Runner.run]：异步运行并返回一个 [`RunResult`][agents.result.RunResult]。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]：同步方法，内部实际调用 `.run()`。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]：异步运行并返回一个 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式方式调用 LLM，并在接收事件时将其流式传输给你。 +1. [`Runner.run()`][agents.run.Runner.run]：异步运行，并返回 [`RunResult`][agents.result.RunResult]。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]：同步方法，内部调用 `.run()`。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]：异步运行，并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式方式调用 LLM，并在接收时将事件流式传输给你。 ```python from agents import Agent, Runner @@ -27,55 +27,55 @@ async def main(): ## 智能体循环 -当你在 `Runner` 中使用 run 方法时，你会传入一个起始智能体和输入。输入可以是字符串（被视为用户消息），也可以是输入项列表，这些输入项符合 OpenAI Responses API 的格式。 +当你在 `Runner` 中使用 run 方法时，你需要传入一个起始智能体和输入。输入可以是字符串（视为用户消息），也可以是输入项列表，即 OpenAI Responses API 中的项。 -接着，runner 会运行一个循环： +runner 随后会运行一个循环： -1. 我们使用当前输入调用当前智能体的 LLM。 -2. LLM 产生输出。 +1. 使用当前输入调用当前智能体的 LLM。 +2. LLM 生成输出。 1. 如果 LLM 返回 `final_output`，循环结束并返回结果。 - 2. 如果 LLM 执行任务转移，我们会更新当前智能体和输入，并重新运行循环。 - 3. 如果 LLM 产生工具调用，我们会运行这些工具调用，追加结果，并重新运行循环。 -3. 如果超过传入的 `max_turns`，将抛出 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。 + 2. 如果 LLM 进行任务转移（handoff），我们会更新当前智能体和输入，然后重新运行循环。 + 3. 如果 LLM 产生工具调用（tool calls），我们会运行这些工具调用，追加结果，然后重新运行循环。 +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]：允许设置一个全局的 LLM 模型使用，而不考虑每个 Agent 上的 `model`。 +- [`model`][agents.run.RunConfig.model]：允许设置一个全局 LLM 模型使用，而不管每个 Agent 自身的 `model`。 - [`model_provider`][agents.run.RunConfig.model_provider]：用于查找模型名称的模型提供方，默认是 OpenAI。 -- [`model_settings`][agents.run.RunConfig.model_settings]：覆盖智能体特定设置。例如，你可以设置一个全局的 `temperature` 或 `top_p`。 +- [`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] 的文档。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：当为 `True`（默认）时，runner 会在调用下一个智能体之前，将此前的对话记录折叠为一条助手消息。辅助机制会将内容放入一个 `` 块中，并在后续任务转移发生时持续追加新轮次。如果你更希望传递原始对话记录，请将其设为 `False` 或提供自定义的 handoff 过滤器。所有 [`Runner` 方法](agents.run.Runner) 在你未显式传入时会自动创建一个 `RunConfig`，因此快速入门与 code examples 会自动采用此默认值，而任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍将覆盖它。单个任务转移可通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖该设置。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选的可调用对象，当 `nest_handoff_history` 为 `True` 时接收标准化的转录（历史 + handoff 项）。它必须返回要转发给下一个智能体的输入项的精确列表，使你无需编写完整的 handoff 过滤器即可替换内置摘要。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：为所有任务转移应用的全局输入过滤器（如果该 handoff 尚未设置）。输入过滤器允许你编辑发送给新智能体的输入。更多详情参见 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 的文档。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：当为 `True`（默认）时，runner 会在调用下一个智能体前，将先前的对话记录折叠为单条 assistant 消息。辅助工具会将内容置于一个不断追加新轮次的 `` 块中。若你希望传递原始对话记录，请将其设为 `False`，或提供自定义 handoff 过滤器。当你未传入时，所有 [`Runner` 方法](agents.run.Runner) 会自动创建一个 `RunConfig`，因此快速上手和 code examples 会自动使用此默认值，且任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍将覆盖它。单次 handoff 可通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选的可调用对象，当 `nest_handoff_history` 为 `True` 时接收规范化的对话记录（history + handoff 项）。它必须返回要转发给下一个智能体的精确输入项列表，允许你在不编写完整 handoff 过滤器的情况下替换内置摘要。 - [`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]：要包含在所有追踪中的元数据。 +- [`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]：为此次运行设置追踪的工作流名称、trace ID 和 trace group ID。我们建议至少设置 `workflow_name`。group ID 是可选字段，用于将多次运行的追踪关联起来。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]：在所有追踪中包含的元数据。 -默认情况下，SDK 在智能体进行任务转移时，会将之前的轮次嵌套到单条助手摘要消息中。这减少了重复的助手消息，并将完整的对话转录置于单个块中，便于新智能体快速扫描。如果你想回到旧行为，传入 `RunConfig(nest_handoff_history=False)`，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`）以按需转发对话。你也可以在某个特定 handoff 上选择退出（或启用），通过设置 `handoff(..., nest_handoff_history=False)` 或 `True`。若想在不编写自定义映射器的情况下更改生成摘要所用的包装文本，调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 恢复默认值）。 +默认情况下，SDK 现在在智能体进行任务转移时，会将先前的多轮对话嵌套进单条 assistant 摘要消息中。这样减少重复的 assistant 消息，并将完整对话记录保存在一个新智能体可快速扫描的单一块中。若你希望恢复旧行为，传入 `RunConfig(nest_handoff_history=False)`，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`）以按需原样转发对话。你也可以为特定 handoff 选择退出（或加入），通过设置 `handoff(..., nest_handoff_history=False)` 或 `True`。若仅想修改生成摘要中使用的包装文本，而不编写自定义 mapper，可调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（使用 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 恢复默认值）。 -## 对话/聊天线程 +## 会话/聊天线程 -调用任一运行方法可能导致一个或多个智能体运行（因此会有一次或多次 LLM 调用），但它代表一次聊天对话中的单个逻辑轮次。例如： +调用任意 run 方法可能会导致一个或多个智能体运行（从而进行一次或多次 LLM 调用），但它代表聊天会话中的单个逻辑轮次。例如： 1. 用户轮次：用户输入文本 -2. Runner 运行：第一个智能体调用 LLM、运行工具、进行一次任务转移到第二个智能体，第二个智能体再运行更多工具，然后产生一个输出。 +2. Runner 运行：第一个智能体调用 LLM，运行工具，进行一次任务转移到第二个智能体；第二个智能体运行更多工具，然后生成输出。 -在智能体运行结束时，你可以选择向用户展示什么。例如，你可以向用户展示由智能体生成的每个新条目，或仅展示最终输出。无论哪种方式，用户都可能接着提出跟进问题，此时你可以再次调用运行方法。 +在智能体运行结束时，你可以选择向用户展示什么内容。例如，你可以展示智能体生成的每一条新项，或只展示最终输出。无论哪种方式，用户都可能提出追问，此时你可以再次调用 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(): @@ -95,9 +95,9 @@ async def main(): # California ``` -### 使用 Sessions 的自动对话管理 +### 使用 Sessions 的自动会话管理 -为简化流程，你可以使用 [Sessions](sessions/index.md) 自动处理对话历史，而无需手动调用 `.to_input_list()`： +更简单的方式是使用 [Sessions](sessions/index.md)，自动处理会话历史，而无需手动调用 `.to_input_list()`： ```python from agents import Agent, Runner, SQLiteSession @@ -123,21 +123,21 @@ async def main(): Sessions 会自动： -- 在每次运行前获取对话历史 +- 在每次运行前检索会话历史 - 在每次运行后存储新消息 -- 为不同的会话 ID 维护独立对话 +- 为不同的 session ID 维护独立会话 更多详情参见 [Sessions 文档](sessions/index.md)。 -### 服务端托管的对话 +### 由服务端管理的会话 -你也可以让 OpenAI 的会话状态特性在服务端管理对话状态，而不是通过 `to_input_list()` 或 `Sessions` 在本地处理。这样可以在无需手动重发所有历史消息的情况下保留对话历史。详情参见 [OpenAI Conversation state 指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 +你也可以让 OpenAI 的对话状态功能在服务端管理会话状态，而不是通过 `to_input_list()` 或 `Sessions` 在本地处理。这样可以在无需手动重发全部历史消息的情况下保留会话历史。参见 [OpenAI Conversation state 指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)了解更多。 OpenAI 提供两种跨轮次跟踪状态的方式： #### 1. 使用 `conversation_id` -你先使用 OpenAI Conversations API 创建一个对话，然后在每次后续调用中复用其 ID： +先使用 OpenAI Conversations API 创建一个会话，然后在后续每次调用中复用其 ID： ```python from agents import Agent, Runner @@ -169,7 +169,7 @@ async def main(): #### 2. 使用 `previous_response_id` -另一种选择是**响应链式调用**，其中每一轮都显式链接到上一轮的响应 ID。 +另一种方式是**响应链（response chaining）**，每一轮显式链接到上一轮的 response ID。 ```python from agents import Agent, Runner @@ -193,18 +193,18 @@ async def main(): ``` -## 长运行智能体与人工在环 +## 长时运行的智能体与人类参与（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/) 集成来运行持久的、长时运行的工作流，包括含有人类参与的任务。在[这个视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)中查看 Temporal 与 Agents SDK 协作完成长时任务的演示，并[查看此处的文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 ## 异常 -SDK 在某些情况下会抛出异常。完整列表在 [`agents.exceptions`][] 中。概览如下： +SDK 会在特定情况下抛出异常。完整列表见 [`agents.exceptions`][]。概览如下： -- [`AgentsException`][agents.exceptions.AgentsException]：SDK 内抛出的所有异常的基类。它作为通用类型，其他特定异常均由其派生。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传递给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 的 `max_turns` 限制时抛出。表示智能体无法在指定的交互轮次内完成任务。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）产生意外或无效输出时发生。这可能包括： - - JSON 结构不合法：当模型为工具调用或其直接输出提供了不合法的 JSON 结构时，尤其是在定义了特定 `output_type` 的情况下。 - - 与工具相关的意外失败：当模型未能以预期方式使用工具时 -- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时犯错时抛出。通常由不正确的代码实现、无效的配置或对 SDK 的 API 的误用导致。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当输入安全防护措施或输出安全防护措施的条件被满足时分别抛出。输入安全防护措施在处理前检查传入消息，而输出安全防护措施在交付前检查智能体的最终响应。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]：SDK 中所有异常的基类。它作为通用类型，其他特定异常均从此派生。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 方法的 `max_turns` 限制时抛出。表示智能体无法在指定的交互轮次内完成任务。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）产生意外或无效输出时发生，包括： + - JSON 结构不合法：当模型为工具调用或直接输出提供了格式错误的 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/zh/sessions/advanced_sqlite_session.md b/docs/zh/sessions/advanced_sqlite_session.md index 625958cf0..6f7d600ab 100644 --- a/docs/zh/sessions/advanced_sqlite_session.md +++ b/docs/zh/sessions/advanced_sqlite_session.md @@ -4,15 +4,15 @@ search: --- # 高级 SQLite 会话 -`AdvancedSQLiteSession` 是基本 `SQLiteSession` 的增强版本，提供高级的对话管理能力，包括对话分支、详细的使用情况分析，以及结构化的对话查询。 +`AdvancedSQLiteSession` 是对基础 `SQLiteSession` 的增强版本，提供包括会话分支、详细使用分析以及结构化会话查询在内的高级对话管理能力。 ## 功能 -- **对话分支**: 可从任意用户消息创建替代对话路径 -- **使用情况追踪**: 每轮交互的详细 token 使用分析，并提供完整的 JSON 明细 -- **结构化查询**: 按轮次获取对话、工具使用统计等 +- **会话分支**: 可从任一用户消息创建替代的对话路径 +- **使用跟踪**: 每轮的详细 token 使用分析，并提供完整的 JSON 明细 +- **结构化查询**: 按轮次获取会话、工具使用统计等 - **分支管理**: 独立的分支切换与管理 -- **消息结构元数据**: 追踪消息类型、工具使用与对话流 +- **消息结构元数据**: 跟踪消息类型、工具使用与会话流转 ## 快速开始 @@ -84,14 +84,14 @@ session = AdvancedSQLiteSession( ### 参数 -- `session_id` (str): 对话会话的唯一标识 -- `db_path` (str | Path): SQLite 数据库文件路径。默认为 `:memory:`，使用内存存储 +- `session_id` (str): 会话会话的唯一标识符 +- `db_path` (str | Path): SQLite 数据库文件路径。默认为 `:memory:`（内存存储） - `create_tables` (bool): 是否自动创建高级表。默认为 `False` -- `logger` (logging.Logger | None): 会话使用的自定义 logger。默认为模块 logger +- `logger` (logging.Logger | None): 会话的自定义日志记录器。默认为模块级日志记录器 -## 使用情况追踪 +## 使用跟踪 -AdvancedSQLiteSession 通过按对话轮次存储 token 使用数据提供详细的使用情况分析。**这完全依赖于每次智能体运行后调用 `store_run_usage` 方法。** +AdvancedSQLiteSession 通过按对话轮次存储 token 使用数据来提供详细的使用分析。**这完全取决于在每次智能体运行后调用 `store_run_usage` 方法。** ### 存储使用数据 @@ -135,9 +135,9 @@ for turn_data in turn_usage: turn_2_usage = await session.get_turn_usage(user_turn_number=2) ``` -## 对话分支 +## 会话分支 -AdvancedSQLiteSession 的关键功能之一是能够从任意用户消息创建对话分支，便于探索替代的对话路径。 +AdvancedSQLiteSession 的关键特性之一是在任一用户消息处创建会话分支，从而探索替代的对话路径。 ### 创建分支 @@ -217,9 +217,9 @@ await session.store_run_usage(result) ## 结构化查询 -AdvancedSQLiteSession 提供多种方法来分析对话的结构与内容。 +AdvancedSQLiteSession 提供多种方法来分析会话结构与内容。 -### 对话分析 +### 会话分析 ```python # Get conversation organized by turns @@ -245,17 +245,17 @@ for turn in matching_turns: ### 消息结构 -会话会自动追踪消息结构，包括： +该会话会自动跟踪消息结构，包括： - 消息类型（user、assistant、tool_call 等） -- 工具调用对应的工具名称 -- 轮次编号与序号 +- 工具调用的工具名 +- 轮次编号与序列号 - 分支关联 - 时间戳 ## 数据库模式 -AdvancedSQLiteSession 在基础的 SQLite 模式上扩展了两个额外的表： +AdvancedSQLiteSession 在基础 SQLite 模式上扩展了两个附加表： ### message_structure 表 @@ -298,8 +298,7 @@ CREATE TABLE turn_usage ( ## 完整示例 -查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，了解所有功能的综合演示。 - +查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，以全面演示所有功能。 ## API 参考 diff --git a/docs/zh/sessions/encrypted_session.md b/docs/zh/sessions/encrypted_session.md index b37662aa1..0ffe6d98e 100644 --- a/docs/zh/sessions/encrypted_session.md +++ b/docs/zh/sessions/encrypted_session.md @@ -4,18 +4,18 @@ search: --- # 加密会话 -`EncryptedSession` 为任何会话实现提供透明加密，通过自动过期机制保护会话数据并自动忽略过期项。 +`EncryptedSession` 为任何会话实现提供透明加密，通过自动过期机制保护会话数据并自动跳过过期项。 ## 功能 -- **透明加密**: 使用 Fernet 加密封装任意会话 -- **每会话唯一密钥**: 使用 HKDF 密钥派生，为每个会话生成独立密钥 -- **自动过期**: 当 TTL 过期时，旧项会被静默跳过 -- **可直接替换**: 适用于任何现有会话实现 +- **透明加密**：使用 Fernet 加密封装任何会话 +- **每会话唯一密钥**：通过 HKDF 密钥派生为每个会话生成唯一密钥 +- **自动过期**：当 TTL 过期时静默跳过旧项目 +- **可直接替换**：适用于任何现有会话实现 ## 安装 -加密会话需要安装 `encrypt` 扩展： +加密会话需要安装 `encrypt` 可选组件： ```bash pip install openai-agents[encrypt] @@ -57,7 +57,7 @@ if __name__ == "__main__": ### 加密密钥 -加密密钥可以是一个 Fernet 密钥或任意字符串： +加密密钥可以是 Fernet 密钥或任意字符串： ```python from agents.extensions.memory import EncryptedSession @@ -79,9 +79,9 @@ session = EncryptedSession( ) ``` -### TTL（存活时间） +### TTL（生存时间） -设置加密项保持有效的时长： +设置加密项的有效期： ```python # Items expire after 1 hour @@ -101,9 +101,9 @@ session = EncryptedSession( ) ``` -## 与不同会话类型的用法 +## 在不同会话类型中的用法 -### 配合 SQLite 会话 +### 用于 SQLite 会话 ```python from agents import SQLiteSession @@ -119,7 +119,7 @@ session = EncryptedSession( ) ``` -### 配合 SQLAlchemy 会话 +### 用于 SQLAlchemy 会话 ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -140,10 +140,10 @@ session = EncryptedSession( !!! warning "高级会话功能" - 当将 `EncryptedSession` 与诸如 `AdvancedSQLiteSession` 之类的高级会话实现一起使用时，请注意： + 当将 `EncryptedSession` 与诸如 `AdvancedSQLiteSession` 等高级会话实现一起使用时，请注意： - - 由于消息内容已被加密，`find_turns_by_content()` 等方法将无法有效工作 - - 基于内容的检索会在加密数据上进行，从而降低其有效性 + - 由于消息内容已加密，`find_turns_by_content()` 等方法将无法有效工作 + - 基于内容的搜索在加密数据上运行，效果会受限 @@ -151,19 +151,19 @@ session = EncryptedSession( EncryptedSession 使用 HKDF（基于 HMAC 的密钥派生函数）为每个会话派生唯一的加密密钥： -- **主密钥**: 你提供的加密密钥 -- **会话盐值**: 会话 ID -- **Info 字符串**: `"agents.session-store.hkdf.v1"` -- **输出**: 32 字节 Fernet 密钥 +- **主密钥**：你提供的加密密钥 +- **会话盐值**：会话 ID +- **信息字符串**：`"agents.session-store.hkdf.v1"` +- **输出**：32 字节的 Fernet 密钥 -这确保了： +这可确保： - 每个会话都有唯一的加密密钥 -- 没有主密钥无法推导出各会话密钥 -- 不同会话之间无法互相解密会话数据 +- 没有主密钥无法推导出密钥 +- 不同会话之间的会话数据无法互相解密 ## 自动过期 -当项目超过 TTL 时，在检索时会被自动跳过： +当项目超过 TTL 时，检索时会被自动跳过： ```python # Items older than TTL are silently ignored diff --git a/docs/zh/sessions/index.md b/docs/zh/sessions/index.md index 7aae73cf0..fad3b7bdd 100644 --- a/docs/zh/sessions/index.md +++ b/docs/zh/sessions/index.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. **每次运行前**：运行器会自动检索该会话的对话历史，并将其预置到输入项前。 +2. **每次运行后**：在运行期间生成的所有新项目（用户输入、助手回复、工具调用等）都会自动存入会话。 +3. **上下文保留**：后续使用相同会话的每次运行都会包含完整的对话历史，帮助智能体维持上下文。 这消除了在运行之间手动调用 `.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 @@ -119,11 +119,11 @@ print(f"Agent: {result.final_output}") ## 会话类型 -SDK 提供了多种会话实现以适配不同用例： +SDK 提供了多种适用于不同用例的会话实现： ### OpenAI Conversations API 会话 -通过 `OpenAIConversationsSession` 使用 [OpenAI 的 Conversations API](https://platform.openai.com/docs/api-reference/conversations)。 +通过 `OpenAIConversationsSession` 使用 [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations)。 ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -159,7 +159,7 @@ print(result.final_output) # "California" ### SQLite 会话 -默认的、轻量级的 SQLite 会话实现： +默认的轻量级 SQLite 实现： ```python from agents import SQLiteSession @@ -180,7 +180,7 @@ result = await Runner.run( ### SQLAlchemy 会话 -可用于生产环境的会话，实现于任何 SQLAlchemy 支持的数据库之上： +使用任一 SQLAlchemy 支持的数据库的生产级会话： ```python from agents.extensions.memory import SQLAlchemySession @@ -198,13 +198,13 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -参见 [SQLAlchemy 会话](sqlalchemy_session.md) 获取详细文档。 +详见 [SQLAlchemy Sessions](sqlalchemy_session.md) 的详细文档。 ### 高级 SQLite 会话 -增强型 SQLite 会话，提供会话分支、使用情况分析以及结构化查询： +具备会话分支、用量分析与结构化查询的增强型 SQLite 会话： ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -224,11 +224,11 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -参见 [高级 SQLite 会话](advanced_sqlite_session.md) 获取详细文档。 +详见 [Advanced SQLite Sessions](advanced_sqlite_session.md) 的详细文档。 ### 加密会话 -针对任意会话实现的透明加密封装： +适用于任意会话实现的透明加密封装： ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -251,27 +251,27 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -参见 [加密会话](encrypted_session.md) 获取详细文档。 +详见 [Encrypted Sessions](encrypted_session.md) 的详细文档。 ### 其他会话类型 -还有一些其他内置选项。请参考 `examples/memory/` 以及 `extensions/memory/` 下的源码。 +还有更多内置选项。请参阅 `examples/memory/` 以及 `extensions/memory/` 下的源代码。 ## 会话管理 ### 会话 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)`）用于生产系统，适配 SQLAlchemy 支持的现有数据库 +- 使用文件型 SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）用于持久对话 +- 使用 SQLAlchemy 驱动的会话（`SQLAlchemySession("session_id", engine=engine, create_tables=True")`）用于由 SQLAlchemy 支持的现有数据库的生产系统 - 使用 Dapr 状态存储会话（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）用于生产级云原生部署，支持 30+ 种数据库后端，并内置遥测、追踪与数据隔离 - 当你希望将历史存储在 OpenAI Conversations API 中时，使用 OpenAI 托管的存储（`OpenAIConversationsSession()`） - 使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任意会话提供透明加密与基于 TTL 的过期 @@ -387,7 +387,7 @@ if __name__ == "__main__": ## 自定义会话实现 -你可以通过创建一个遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自定义会话记忆： +你可以通过创建遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自定义会话内存： ```python from agents.memory.session import SessionABC @@ -430,14 +430,24 @@ result = await Runner.run( ) ``` +## 社区会话实现 + +社区已开发了更多会话实现： + +| Package | Description | +|---------|-------------| +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 基于 Django ORM 的会话，适用于任何 Django 支持的数据库（PostgreSQL、MySQL、SQLite 等） | + +如果你构建了会话实现，欢迎提交文档 PR 将其添加到此处！ + ## API 参考 -详细 API 文档参见： +详细 API 文档请参阅： - [`Session`][agents.memory.session.Session] - 协议接口 - [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 实现 -- [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基础 SQLite 实现 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 基于 SQLAlchemy 的实现 +- [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本 SQLite 实现 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 驱动实现 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状态存储实现 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 带分支与分析能力的增强型 SQLite +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 具备分支与分析的增强型 SQLite - [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任意会话的加密封装 \ No newline at end of file diff --git a/docs/zh/sessions/sqlalchemy_session.md b/docs/zh/sessions/sqlalchemy_session.md index 4275a8b52..200726f1f 100644 --- a/docs/zh/sessions/sqlalchemy_session.md +++ b/docs/zh/sessions/sqlalchemy_session.md @@ -4,11 +4,11 @@ search: --- # SQLAlchemy 会话 -`SQLAlchemySession` 使用 SQLAlchemy 提供可用于生产的会话实现，使你可以将 SQLAlchemy 支持的任意数据库（PostgreSQL、MySQL、SQLite 等）用于会话存储。 +`SQLAlchemySession` 使用 SQLAlchemy 提供生产可用的会话实现，使你可以将 SQLAlchemy 支持的任意数据库（PostgreSQL、MySQL、SQLite 等）用于会话存储。 ## 安装 -SQLAlchemy 会话需要安装 `sqlalchemy` 额外依赖： +SQLAlchemy 会话需要 `sqlalchemy` 扩展： ```bash pip install openai-agents[sqlalchemy] @@ -42,9 +42,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -### 使用已有引擎 +### 使用现有 engine -适用于已存在 SQLAlchemy 引擎的应用： +适用于已有 SQLAlchemy engine 的应用： ```python import asyncio diff --git a/docs/zh/streaming.md b/docs/zh/streaming.md index 377458435..79866a43d 100644 --- a/docs/zh/streaming.md +++ b/docs/zh/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] 对象流，详见下文。 ## 原始响应事件 -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] 是直接从 LLM 传递过来的原始事件。它们采用 OpenAI Responses API 格式，这意味着每个事件都有一个类型（如 `response.created`、`response.output_text.delta` 等）以及相应的数据。如果你希望在生成后立即将响应消息流式传输给用户，这些事件会很有用。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] 是直接由 LLM 传递的原始事件。它们采用 OpenAI Responses API 格式，这意味着每个事件都有一个类型（如 `response.created`、`response.output_text.delta` 等）和数据。如果你希望在响应生成时立刻将消息流式传输给用户，这些事件会很有用。 -例如，以下代码会按 token 逐步输出由 LLM 生成的文本。 +例如，下面的代码会逐 token 输出 LLM 生成的文本。 ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## 运行项事件与智能体事件 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 属于更高层级的事件。它们会在某个项已完全生成后通知你。这样，你可以在“消息已生成”“工具已运行”等层级推送进度更新，而不是按每个 token。类似地，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如由于一次任务转移）向你提供更新。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 属于更高层级的事件。它们会在某个条目完全生成时通知你。这使你可以在“消息已生成”“工具已运行”等层级（而非每个 token）推送进度更新。类似地，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如由于一次任务转移）向你提供更新。 -例如，以下代码会忽略原始事件，仅向用户流式传输更新。 +例如，下面的代码会忽略原始事件并向用户流式传输更新。 ```python import asyncio diff --git a/docs/zh/tools.md b/docs/zh/tools.md index efceb4878..97ba2c61b 100644 --- a/docs/zh/tools.md +++ b/docs/zh/tools.md @@ -4,22 +4,22 @@ search: --- # 工具 -工具让智能体采取行动：例如获取数据、运行代码、调用外部 API，甚至进行计算机操作。Agents SDK 中有三类工具： +工具让智能体能够执行操作：如获取数据、运行代码、调用外部 API，甚至进行计算机操作。在 Agents SDK 中，工具分为三类： -- Hosted tools：这些在 LLM 服务 旁与 AI 模型一起运行。OpenAI 提供检索、网络检索 和 计算机操作 作为托管工具。 -- Function calling：这些允许你将任意 Python 函数用作工具。 -- 将智能体作为工具：这允许你把一个智能体当作工具使用，使智能体可以调用其他智能体而无需进行任务转移。 +- 由OpenAI托管的工具：这些在 LLM 服务 旁与 AI 模型一起运行。OpenAI 提供 retrieval、网络检索 和 计算机操作 作为托管工具。 +- Function Calling：这些允许你将任意 Python 函数用作工具。 +- 智能体作为工具：这允许你将一个智能体作为工具，从而让智能体调用其他智能体，而无需进行任务转移。 -## 托管工具 +## 由OpenAI托管的工具 使用 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 时，OpenAI 提供了一些内置工具： - [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体进行网络检索。 -- [`FileSearchTool`][agents.tool.FileSearchTool] 允许从你的 OpenAI 向量存储 中检索信息。 -- [`ComputerTool`][agents.tool.ComputerTool] 允许自动化计算机操作任务。 +- [`FileSearchTool`][agents.tool.FileSearchTool] 支持从你的 OpenAI 向量存储 中检索信息。 +- [`ComputerTool`][agents.tool.ComputerTool] 支持自动化的计算机操作任务。 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙箱环境中执行代码。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] 向模型暴露远程 MCP 服务 的工具。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 根据提示词生成图像。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务 的工具暴露给模型。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 根据提示生成图像。 - [`LocalShellTool`][agents.tool.LocalShellTool] 在你的机器上运行 shell 命令。 ```python @@ -43,14 +43,14 @@ async def main(): ## 工具调用 -你可以将任何 Python 函数用作工具。Agents SDK 会自动设置该工具： +你可以将任意 Python 函数作为工具使用。Agents SDK 会自动完成工具设置： -- 工具名称将是 Python 函数名（或你可以提供一个名称） -- 工具描述将取自函数的 docstring（或你可以提供描述） -- 函数输入的 schema 会根据函数的参数自动创建 -- 每个输入的描述将取自函数的 docstring，除非禁用 +- 工具名将采用该 Python 函数的名称（或你可以自定义名称） +- 工具描述将来自函数的 docstring（或你可以自定义描述） +- 函数输入的 schema 会从函数的参数自动创建 +- 各输入的描述会从函数的 docstring 中提取，除非你禁用了该行为 -我们使用 Python 的 `inspect` 模块提取函数签名，使用 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，并使用 `pydantic` 创建 schema。 +我们使用 Python 的 `inspect` 模块提取函数签名，使用 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，并使用 `pydantic` 来创建 schema。 ```python import json @@ -102,10 +102,10 @@ for tool in agent.tools: ``` -1. 你可以在函数参数中使用任何 Python 类型，函数可为同步或异步。 -2. 如果存在 docstring，将用于捕获描述和参数说明。 -3. 函数可选地接收 `context`（必须是第一个参数）。你也可以设置覆盖项，如工具名称、描述、docstring 风格等。 -4. 你可以将装饰后的函数传递给工具列表。 +1. 你可以使用任意 Python 类型作为函数参数，函数可以是同步或异步。 +2. 若存在 docstring，将用于捕获描述和参数说明。 +3. 函数可选接收 `context`（必须为第一个参数）。你也可以设置覆盖项，如工具名称、描述、docstring 风格等。 +4. 你可以将装饰后的函数传入工具列表。 ??? note "展开以查看输出" @@ -179,20 +179,20 @@ for tool in agent.tools: ### 从工具调用返回图像或文件 -除了返回文本输出外，你还可以将一个或多个图像或文件作为函数工具的输出。可返回以下任意类型： +除了返回文本输出外，你还可以将一个或多个图像或文件作为工具调用的输出。为此，你可以返回以下任意类型： -- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） -- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） -- 文本：字符串或可转为字符串的对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） +- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或其 TypedDict 版本，[`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） +- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或其 TypedDict 版本，[`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） +- 文本：字符串或可字符串化对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或其 TypedDict 版本，[`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） -### 自定义函数工具 +### 自定义工具调用 -有时，你可能不想将 Python 函数用作工具。如果你愿意，可以直接创建一个 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供： +有时你并不想使用 Python 函数作为工具。如果你愿意，可以直接创建一个 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供： - `name` - `description` - `params_json_schema`，即参数的 JSON schema -- `on_invoke_tool`，这是一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和作为 JSON 字符串的参数，并且必须以字符串形式返回工具输出。 +- `on_invoke_tool`，一个异步函数，它接收 [`ToolContext`][agents.tool_context.ToolContext] 和作为 JSON 字符串的参数，并且必须以字符串形式返回工具输出。 ```python from typing import Any @@ -225,18 +225,18 @@ tool = FunctionTool( ) ``` -### 参数与 docstring 的自动解析 +### 自动解析参数与文档字符串 -如前所述，我们会自动解析函数签名以提取工具的 schema，并解析 docstring 以提取工具及各参数的描述。注意事项： +如前所述，我们会自动解析函数签名以提取工具的 schema，并解析 docstring 以提取工具和各参数的描述。注意事项如下： -1. 使用 `inspect` 模块进行签名解析。我们使用类型注解理解参数类型，并动态构建一个 Pydantic 模型来表示整体 schema。支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。 -2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式有 `google`、`sphinx` 和 `numpy`。我们会尽力自动检测 docstring 格式，但这只是尽力而为；你也可以在调用 `function_tool` 时显式设置。你也可以通过将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。 +1. 使用 `inspect` 模块进行签名解析。我们利用类型注解了解参数类型，并动态构建一个 Pydantic 模型来表示整体 schema。它支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。 +2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这只是尽力而为；你可以在调用 `function_tool` 时显式设置。你也可以通过将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。 -用于 schema 提取的代码位于 [`agents.function_schema`][]。 +用于 schema 提取的代码位于 [`agents.function_schema`][] 中。 -## 将智能体用作工具 +## 智能体作为工具 -在某些工作流中，你可能希望由一个中心智能体来编排一组专业化智能体，而不是进行任务转移。你可以通过将智能体建模为工具来实现。 +在某些工作流中，你可能希望由一个中心智能体来编排一组专业化智能体，而不是进行控制权的任务转移。你可以通过将智能体建模为工具来实现这一点。 ```python from agents import Agent, Runner @@ -275,9 +275,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 @@ -298,11 +298,11 @@ async def run_my_agent() -> str: ### 自定义输出提取 -在某些情况下，你可能希望在将工具化智能体的输出返回给中心智能体之前对其进行修改。如果你希望： +在某些情况下，你可能希望在将工具化智能体的输出返回给中心智能体之前进行修改。这在以下情形很有用： - 从子智能体的对话历史中提取特定信息（例如 JSON 负载）。 - 转换或重新格式化智能体的最终答案（例如将 Markdown 转换为纯文本或 CSV）。 -- 验证输出，或在响应缺失或格式错误时提供回退值。 +- 验证输出，或在智能体响应缺失或格式错误时提供回退值。 你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现： @@ -323,9 +323,9 @@ json_tool = data_agent.as_tool( ) ``` -### 条件启用工具 +### 条件式启用工具 -你可以在运行时使用 `is_enabled` 参数有条件地启用或禁用智能体工具。这允许你根据上下文、用户偏好或运行时条件，动态筛选对 LLM 可用的工具。 +你可以在运行时使用 `is_enabled` 参数有条件地启用或禁用智能体工具。这允许你基于上下文、用户偏好或运行时条件，动态筛选 LLM 可用的工具。 ```python import asyncio @@ -389,17 +389,17 @@ asyncio.run(main()) 被禁用的工具在运行时对 LLM 完全不可见，适用于： - 基于用户权限的功能开关 -- 特定环境的工具可用性（开发 vs 生产） -- 对不同工具配置进行 A/B 测试 -- 基于运行时状态的动态工具筛选 +- 特定环境的工具可用性（dev 与 prod） +- 针对不同工具配置的 A/B 测试 +- 基于运行时状态的动态工具过滤 ## 在工具调用中处理错误 -当你通过 `@function_tool` 创建函数工具时，可以传入 `failure_error_function`。该函数在工具调用崩溃时向 LLM 提供错误响应。 +当你通过 `@function_tool` 创建工具调用时，你可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。 -- 默认情况下（即未传入时），会运行 `default_tool_error_function`，告知 LLM 发生了错误。 -- 如果你传入了自定义错误函数，则会运行该函数，并将响应发送给 LLM。 -- 如果你显式传入 `None`，则任何工具调用错误都会被重新抛出以供你处理。若模型生成了无效 JSON，可能会是 `ModelBehaviorError`；若你的代码崩溃，可能会是 `UserError`，等等。 +- 默认情况下（即你未传入任何内容），会运行 `default_tool_error_function`，告知 LLM 发生了错误。 +- 如果你传入了自定义错误函数，就会执行该函数，并将其响应发送给 LLM。 +- 如果你显式传入 `None`，则任何工具调用错误都会被重新抛出以供你处理。若模型生成了无效 JSON，则可能是 `ModelBehaviorError`；若你的代码崩溃，则可能是 `UserError`，等等。 ```python from agents import function_tool, RunContextWrapper diff --git a/docs/zh/tracing.md b/docs/zh/tracing.md index a5c9f7650..2c395fdfc 100644 --- a/docs/zh/tracing.md +++ b/docs/zh/tracing.md @@ -4,52 +4,52 @@ search: --- # 追踪 -Agents SDK 内置了追踪功能，会在一次智能体运行中收集完整的事件记录：LLM 生成、工具调用、任务转移、安全防护措施，甚至自定义事件。使用 [Traces 仪表板](https://platform.openai.com/traces)，你可以在开发与生产环境中调试、可视化并监控工作流。 +Agents SDK 内置了追踪功能，会在一次智能体运行期间收集完整的事件记录：LLM 生成、工具调用、任务转移、安全防护措施，甚至自定义事件。使用 [Traces dashboard](https://platform.openai.com/traces)，你可以在开发和生产中调试、可视化并监控工作流。 !!!note - 追踪默认启用。可以通过两种方式禁用追踪： + 追踪默认启用。可以通过以下两种方式禁用追踪： 1. 通过设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING=1` 全局禁用追踪 - 2. 通过将 [`agents.run.RunConfig.tracing_disabled`][] 设为 `True`，对单次运行禁用追踪 + 2. 通过将 [`agents.run.RunConfig.tracing_disabled`][] 设为 `True` 来只对单次运行禁用追踪 -***对于在使用 OpenAI API 且采用 Zero Data Retention (ZDR) 策略的组织，不支持追踪。*** +***对于在使用 OpenAI API 且实行 Zero Data Retention (ZDR) 策略的组织，追踪不可用。*** -## Traces 与 spans +## 追踪与 Span -- **Traces** 表示“工作流”的一次端到端操作。它们由多个 Span 组成。Trace 具有以下属性： - - `workflow_name`：逻辑上的工作流或应用名称。例如“代码生成”或“客户服务”。 - - `trace_id`：Trace 的唯一 ID。如果未传入，将自动生成。必须符合 `trace_<32_alphanumeric>` 格式。 - - `group_id`：可选的分组 ID，用于将同一会话中的多个 Trace 关联起来。例如，你可以使用聊天线程 ID。 - - `disabled`：若为 True，则不会记录该 Trace。 - - `metadata`：Trace 的可选元数据。 -- **Spans** 表示具有开始和结束时间的操作。Span 具有： +- **Traces（追踪）** 表示一次“工作流”的端到端操作。它们由 Spans 组成。追踪具备以下属性： + - `workflow_name`：逻辑上的工作流或应用。例如 “Code generation” 或 “Customer service”。 + - `trace_id`：追踪的唯一 ID。如果未传入会自动生成。必须符合 `trace_<32_alphanumeric>` 格式。 + - `group_id`：可选的分组 ID，用于关联同一会话中的多个追踪。例如，你可以使用聊天线程 ID。 + - `disabled`：如果为 True，则不会记录该追踪。 + - `metadata`：追踪的可选元数据。 +- **Spans（Span）** 表示具有开始和结束时间的操作。Span 具有： - `started_at` 和 `ended_at` 时间戳。 - - `trace_id`，表示其所属的 Trace - - `parent_id`，指向该 Span 的父级 Span（如有） - - `span_data`，即关于 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息，等。 + - `trace_id`，表示其所属的追踪 + - `parent_id`，指向该 Span 的父 Span（如果有） + - `span_data`，即有关该 Span 的信息。例如，`AgentSpanData` 包含有关智能体的信息，`GenerationSpanData` 包含有关 LLM 生成的信息，等等。 ## 默认追踪 默认情况下，SDK 会追踪以下内容： -- 整个 `Runner.{run, run_sync, run_streamed}()` 被包裹在 `trace()` 中。 +- 整个 `Runner.{run, run_sync, run_streamed}()` 会被包裹在一个 `trace()` 中。 - 每次智能体运行都会包裹在 `agent_span()` 中 - LLM 生成会包裹在 `generation_span()` 中 -- 工具调用会分别包裹在 `function_span()` 中 +- 工具调用的每次调用会包裹在 `function_span()` 中 - 安全防护措施会包裹在 `guardrail_span()` 中 - 任务转移会包裹在 `handoff_span()` 中 - 音频输入（语音转文本）会包裹在 `transcription_span()` 中 - 音频输出（文本转语音）会包裹在 `speech_span()` 中 -- 相关音频 spans 可能会归入 `speech_group_span()` 之下 +- 相关的音频 spans 可能会被归属在 `speech_group_span()` 之下 -默认情况下，Trace 名称为 “Agent workflow”。如果使用 `trace`，你可以设置此名称；或者通过 [`RunConfig`][agents.run.RunConfig] 配置名称及其他属性。 +默认情况下，追踪名称为 “Agent workflow”。如果你使用 `trace`，可以设置该名称，或者通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 -此外，你可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪数据推送到其他目的地（作为替代，或作为次要目的地）。 +此外，你可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪发送到其他目标（作为替代或次要目标）。 -## 高层级追踪 +## 更高层级的追踪 -有时你可能希望多次调用 `run()` 属于同一个 Trace。可以将整段代码包裹在 `trace()` 中实现。 +有时，你可能希望多次调用 `run()` 隶属于同一个追踪。你可以通过将整段代码包裹在 `trace()` 中来实现。 ```python from agents import Agent, Runner, trace @@ -64,46 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 因为两次对 `Runner.run` 的调用都放在 `with trace()` 中，单次运行会成为整体 Trace 的组成部分，而不是创建两个独立的 Trace。 +1. 由于两次对 `Runner.run` 的调用都包裹在 `with trace()` 中，单次运行将属于整体追踪的一部分，而不会创建两个追踪。 -## 创建 traces +## 创建追踪 -你可以使用 [`trace()`][agents.tracing.trace] 函数创建 Trace。Trace 需要开始与结束。你有两种方式： +你可以使用 [`trace()`][agents.tracing.trace] 函数创建追踪。追踪需要被启动并结束。你有两种方式： -1. 推荐：将 trace 作为上下文管理器使用，即 `with trace(...) as my_trace`。它会在合适的时机自动开始和结束 Trace。 -2. 也可以手动调用 [`trace.start()`][agents.tracing.Trace.start] 和 [`trace.finish()`][agents.tracing.Trace.finish]。 +1. **推荐**：将追踪作为上下文管理器使用，即 `with trace(...) as my_trace`。这会在正确的时间自动启动并结束追踪。 +2. 你也可以手动调用 [`trace.start()`][agents.tracing.Trace.start] 和 [`trace.finish()`][agents.tracing.Trace.finish]。 -当前 Trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。这意味着它会自动适配并发场景。如果你手动开始/结束 Trace，需要在 `start()`/`finish()` 中传入 `mark_as_current` 和 `reset_current` 来更新当前 Trace。 +当前追踪通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。这意味着它能自动与并发配合。如果你手动启动/结束追踪，你需要在 `start()`/`finish()` 中传递 `mark_as_current` 和 `reset_current` 来更新当前追踪。 -## 创建 spans +## 创建 Span -你可以使用各类 [`*_span()`][agents.tracing.create] 方法创建 Span。一般情况下，不需要手动创建 Spans。提供了 [`custom_span()`][agents.tracing.custom_span] 函数以追踪自定义 Span 信息。 +你可以使用各种 [`*_span()`][agents.tracing.create] 方法创建 Span。通常你不需要手动创建 Span。提供了一个 [`custom_span()`][agents.tracing.custom_span] 函数用于跟踪自定义 Span 信息。 -Spans 会自动加入当前 Trace，并嵌套在最近的当前 Span 之下，而该信息通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。 +Span 会自动归属到当前追踪中，并嵌套在最近的当前 Span 之下，后者通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。 ## 敏感数据 某些 Span 可能会捕获潜在的敏感数据。 -`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] 来禁用这些数据的捕获。 -同样地，音频相关的 Spans 默认包含输入与输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 来禁用这些音频数据的采集。 +类似地，音频 Span 默认会包含输入与输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 禁用这些音频数据的捕获。 ## 自定义追踪进程 追踪的高层架构如下： -- 初始化时，我们创建一个全局的 [`TraceProvider`][agents.tracing.setup.TraceProvider]，负责创建 Traces。 -- 我们将 `TraceProvider` 配置为使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 批量发送 Traces/Spans 到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者会将 Spans 与 Traces 批量导出到 OpenAI 后端。 +- 在初始化时，我们会创建一个全局的 [`TraceProvider`][agents.tracing.setup.TraceProvider]，负责创建追踪。 +- 我们为 `TraceProvider` 配置一个 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，该进程会将追踪/Span 批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，由其将 Span 与追踪批量导出到 OpenAI 后端。 -若要自定义此默认设置，以便将追踪发送到替代或附加后端，或修改导出器行为，你有两种选择： +要自定义此默认设置，以将追踪发送到替代或附加的后端，或修改导出器行为，你有两种选择： -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加“额外”的追踪进程，它会在 Traces 与 Spans 准备就绪时接收它们。这样你可以在将追踪发送到 OpenAI 后端之外，执行自定义处理。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你“替换”默认的进程为你自定义的追踪进程。除非你包含一个负责发送到 OpenAI 后端的 `TracingProcessor`，否则 Traces 将不会发送到 OpenAI 后端。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外的**追踪进程，该进程会在追踪与 Span 就绪时收到它们。这使你可以在将追踪发送到 OpenAI 后端之外执行自定义处理。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你**替换**默认进程为你自己的追踪进程。这意味着除非你包含一个执行该功能的 `TracingProcessor`，否则追踪将不会被发送到 OpenAI 后端。 ## 使用非 OpenAI 模型进行追踪 -你可以在非 OpenAI 模型中使用 OpenAI API key 启用在 OpenAI Traces 仪表板中的免费追踪，而无需禁用追踪。 +你可以使用 OpenAI API key 搭配非 OpenAI 模型，在无需禁用追踪的情况下，在 OpenAI Traces 仪表盘启用免费的追踪。 ```python import os @@ -124,16 +124,16 @@ agent = Agent( ) ``` -## 备注 -- 在 Openai Traces 仪表板查看免费追踪。 +## 注意 +- 可在 OpenAI Traces 仪表盘查看免费追踪。 ## 外部追踪进程列表 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow（自托管/OSS）](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow（Databricks 托管）](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/zh/usage.md b/docs/zh/usage.md index 990071f57..8a748511c 100644 --- a/docs/zh/usage.md +++ b/docs/zh/usage.md @@ -4,22 +4,22 @@ search: --- # 用量 -Agents SDK 会自动跟踪每次运行的 token 用量。你可以从运行上下文中访问它，用于监控成本、执行限制或记录分析数据。 +Agents SDK 会自动为每次运行跟踪令牌用量。你可以从运行上下文中访问它，用于监控成本、实施限制或记录分析。 ## 跟踪内容 - **requests**: 进行的 LLM API 调用次数 -- **input_tokens**: 发送的输入 token 总数 -- **output_tokens**: 接收的输出 token 总数 +- **input_tokens**: 发送的输入令牌总数 +- **output_tokens**: 接收的输出令牌总数 - **total_tokens**: 输入 + 输出 - **request_usage_entries**: 每次请求的用量明细列表 - **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?") @@ -31,11 +31,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -用量会在此次运行中的所有模型调用间聚合（包括工具调用和任务转移）。 +用量会在运行期间所有模型调用中聚合（包括工具调用和 handoffs）。 ### 在 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 @@ -53,7 +53,7 @@ print(result.context_wrapper.usage.total_tokens) ## 按请求的用量跟踪 -SDK 会自动在 `request_usage_entries` 中跟踪每个 API 请求的用量，便于进行精细的成本计算和监控上下文窗口消耗。 +SDK 会在 `request_usage_entries` 中自动跟踪每个 API 请求的用量，便于进行细粒度的成本计算与上下文窗口消耗监控。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -62,9 +62,9 @@ for request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## 在会话中访问用量 +## 会话中的用量访问 -当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行的用量。会话会维护对话历史用于上下文，但每次运行的用量彼此独立。 +当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行的用量。会话会为上下文维护对话历史，但每次运行的用量彼此独立。 ```python session = SQLiteSession("my_conversation") @@ -76,11 +76,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -请注意，虽然会话会在运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的用量指标仅代表该次执行。在会话中，之前的消息可能会作为输入重新提供给每次运行，这会影响后续轮次的输入 token 计数。 +请注意，尽管会话会在运行间保留对话上下文，但每次 `Runner.run()` 返回的用量指标仅代表该次执行。在会话中，先前消息可能会在每次运行时重新作为输入提供，从而影响后续轮次的输入令牌计数。 -## 在钩子中使用用量 +## 钩子中的用量 -如果你使用 `RunHooks`，传递给每个钩子的 `context` 对象包含 `usage`。这使你可以在关键生命周期时刻记录用量。 +如果你在使用 `RunHooks`，传递给每个钩子的 `context` 对象包含 `usage`。这使你可以在关键生命周期节点记录用量。 ```python class MyHooks(RunHooks): @@ -91,9 +91,9 @@ class MyHooks(RunHooks): ## API 参考 -如需详细的 API 文档，请参见： +欲了解详细的 API 文档，请参阅： - [`Usage`][agents.usage.Usage] - 用量跟踪数据结构 - [`RequestUsage`][agents.usage.RequestUsage] - 按请求的用量详情 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问用量 -- [`RunHooks`][agents.run.RunHooks] - 接入用量跟踪的生命周期 \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 挂接到用量跟踪的生命周期 \ No newline at end of file diff --git a/docs/zh/visualization.md b/docs/zh/visualization.md index af338a05e..7a4b3a2dd 100644 --- a/docs/zh/visualization.md +++ b/docs/zh/visualization.md @@ -4,7 +4,7 @@ search: --- # 智能体可视化 -智能体可视化允许你使用 **Graphviz** 生成智能体及其关系的结构化图形表示。这有助于理解应用中智能体、工具与任务转移之间的交互方式。 +智能体可视化允许你使用 **Graphviz** 生成智能体及其关系的结构化图形表示。这有助于理解应用中智能体、工具与任务转移的交互方式。 ## 安装 @@ -18,10 +18,10 @@ pip install "openai-agents[viz]" 你可以使用 `draw_graph` 函数生成智能体可视化。该函数会创建一个有向图，其中： -- **智能体** 用黄色方框表示。 -- **MCP 服务** 用灰色方框表示。 -- **工具** 用绿色椭圆表示。 -- **任务转移** 以从一个智能体指向另一个智能体的有向边表示。 +- **智能体** 使用黄色方框表示。 +- **MCP 服务** 使用灰色方框表示。 +- **工具** 使用绿色椭圆表示。 +- **任务转移** 是从一个智能体指向另一个智能体的有向边。 ### 示例用法 @@ -69,36 +69,36 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -这将生成一个图，直观展示 **分诊智能体** 的结构及其与子智能体和工具的连接关系。 +这会生成一个图形，直观展示 **分诊智能体** 的结构以及其与子智能体和工具的连接。 -## 可视化说明 +## 理解可视化 -生成的图包含： +生成的图形包含： -- 一个 **起始节点**（`__start__`），表示入口点。 -- 用黄色填充的 **矩形** 表示智能体。 -- 用绿色填充的 **椭圆** 表示工具。 -- 用灰色填充的 **矩形** 表示 MCP 服务。 -- 用有向边表示交互： - - **实线箭头** 表示智能体之间的任务转移。 - - **虚线点状箭头** 表示工具调用。 +- 一个表示入口点的 **起始节点**（`__start__`）。 +- 使用黄色填充的**矩形**表示智能体。 +- 使用绿色填充的**椭圆**表示工具。 +- 使用灰色填充的**矩形**表示 MCP 服务。 +- 表示交互的有向边： + - **实线箭头** 表示智能体到智能体的任务转移。 + - **点线箭头** 表示工具调用。 - **虚线箭头** 表示 MCP 服务调用。 -- 一个 **结束节点**（`__end__`），表示执行终止位置。 +- 一个表示执行终止位置的 **结束节点**（`__end__`）。 -**注意：** 在较新的 `agents` 软件包版本中会渲染 MCP 服务（在 **v0.2.8** 中已验证）。如果在可视化中未看到 MCP 方框，请升级到最新版本。 +**注意：** 在最近版本的 `agents` 包（在 **v0.2.8** 验证）中会渲染 MCP 服务。如果在你的可视化中看不到 MCP 方框，请升级到最新版本。 -## 图形自定义 +## 自定义图形 ### 显示图形 -默认情况下，`draw_graph` 会内联显示图形。要在单独窗口中显示，编写如下代码： +默认情况下，`draw_graph` 会内联显示图形。若要在单独窗口中显示，请编写： ```python draw_graph(triage_agent).view() ``` ### 保存图形 -默认情况下，`draw_graph` 会内联显示图形。要将其保存为文件，请指定文件名： +默认情况下，`draw_graph` 会内联显示图形。若要将其保存为文件，请指定文件名： ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/zh/voice/pipeline.md b/docs/zh/voice/pipeline.md index d6bc2a1f9..ed2149f0b 100644 --- a/docs/zh/voice/pipeline.md +++ b/docs/zh/voice/pipeline.md @@ -2,9 +2,9 @@ search: exclude: true --- -# 流水线与工作流 +# 管线与工作流 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个类，可将你的智能体工作流轻松变成语音应用。你传入一个需要运行的工作流，流水线会负责转录输入音频、检测音频结束时间、在正确的时间调用你的工作流，并将工作流输出再转换为音频。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个类，可让你轻松将智能体工作流变成语音应用。你传入要运行的工作流，管线会负责转写输入音频、检测音频结束时机、在合适的时刻调用你的工作流，并将工作流输出再转换为音频。 ```mermaid graph LR @@ -32,31 +32,31 @@ graph LR ``` -## 配置流水线 +## 配置管线 -创建流水线时，你可以设置以下内容： +创建管线时，你可以设置以下内容： -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]：每次有新音频被转录时运行的代码。 -2. 所使用的 [`speech-to-text`][agents.voice.model.STTModel] 和 [`text-to-speech`][agents.voice.model.TTSModel] 模型。 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]：用于配置如下内容： - - 模型提供方，可将模型名称映射到具体模型 +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 模型的设置，例如使用的 prompt、语言和数据类型 + - TTS 和 STT 模型的设置，例如提示词、语言和使用的数据类型 -## 运行流水线 +## 运行管线 -你可以通过 [`run()`][agents.voice.pipeline.VoicePipeline.run] 方法运行流水线，它允许你以两种形式传入音频输入： +你可以通过 [`run()`][agents.voice.pipeline.VoicePipeline.run] 方法运行管线，它允许以两种形式传入音频输入： -1. 当你已有完整的音频转录，并只需为其生成结果时，使用 [`AudioInput`][agents.voice.input.AudioInput]。这在不需要检测说话者何时说完的场景很有用；例如，有预先录制的音频，或在按键说话应用中用户何时说完非常明确。 -2. 当你可能需要检测用户何时说完时，使用 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]。它允许你在检测到时不断推送音频块，语音流水线将通过称为“activity detection（活动检测）”的过程，在合适的时间自动运行智能体工作流。 +1. 当你已有完整的音频转写并仅想产出结果时，使用 [`AudioInput`][agents.voice.input.AudioInput]。当你不需要检测说话者何时结束说话时很有用；例如，对预录音频，或在按键说话应用中用户结束说话的时间点很明确。 +2. 当你可能需要检测用户何时结束说话时，使用 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]。它允许你在检测到音频片段时推送这些片段，语音管线会通过一种称为“活动检测”的过程，在正确的时间自动运行智能体工作流。 ## 结果 -一次语音流水线运行的结果是 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]。这是一个对象，允许你在事件发生时进行流式接收。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] 包括几种类型： +语音管线运行的结果是 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]。这是一个对象，允许你在事件发生时进行流式传输。有几种 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] 类型，包括： -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]，包含一段音频数据。 -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]，告知诸如轮次开始或结束等生命周期事件。 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]，表示错误事件。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]，包含一段音频。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]，用于通知回合开始或结束等生命周期事件。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]，为错误事件。 ```python @@ -74,6 +74,6 @@ 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/zh/voice/quickstart.md b/docs/zh/voice/quickstart.md index 63e8e68f2..8267ecc5a 100644 --- a/docs/zh/voice/quickstart.md +++ b/docs/zh/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,7 +14,7 @@ pip install 'openai-agents[voice]' ## 概念 -这里的核心概念是一个[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]，它包含 3 个步骤： +这里需要了解的主要概念是一个 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]，它是一个包含 3 步的流程： 1. 运行语音转文本模型，将音频转换为文本。 2. 运行你的代码（通常是一个智能体工作流）以生成结果。 @@ -48,7 +48,7 @@ graph LR ## 智能体 -首先，让我们设置一些智能体。如果你已经用这个 SDK 构建过智能体，这一步会很熟悉。我们会创建几个智能体、一次任务转移，以及一个工具。 +首先，我们来设置一些智能体。如果你已经用这个 SDK 构建过智能体，这部分应该很熟悉。我们会创建几个智能体、一次任务转移，以及一个工具。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 语音流水线 -我们将设置一个简单的语音流水线，使用[`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]作为工作流。 +我们将设置一个简单的语音流水线，并使用 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] 作为工作流。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## 整体串联 +## 整合起来 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -如果你运行这个示例，智能体会对你说话！查看[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)中的示例，体验一个你可以与智能体对话的演示。 \ No newline at end of file +如果你运行这个示例，智能体会和你说话！查看示例 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)，观看一个你可以亲自与智能体对话的演示。 \ No newline at end of file diff --git a/docs/zh/voice/tracing.md b/docs/zh/voice/tracing.md index f8ca42c69..c571165d4 100644 --- a/docs/zh/voice/tracing.md +++ b/docs/zh/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # 追踪 -就像[智能体的追踪](../tracing.md)一样，语音流水线也会被自动追踪。 +与[智能体如何被追踪](../tracing.md)相同，语音流水线也会被自动追踪。 -你可以参考上面关于追踪的文档了解基础信息，此外还可以通过[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]对流水线的追踪进行配置。 +你可以阅读上面的追踪文档以获取基础信息，此外还可以通过[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]对流水线的追踪进行配置。 与追踪相关的关键字段包括： -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：控制是否禁用追踪。默认启用追踪。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：控制追踪是否包含潜在敏感数据，例如音频转录。这仅适用于语音流水线，不影响你的 Workflow 内部发生的任何事情。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]：控制追踪是否包含音频数据。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]：追踪工作流的名称。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]：追踪的`group_id`，用于关联多个追踪。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：要随追踪一同包含的附加元数据。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 控制是否禁用追踪。默认启用追踪。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 控制追踪是否包含可能的敏感数据，例如音频转写。该设置仅针对语音流水线，不影响你的工作流内部发生的任何内容。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 控制追踪是否包含音频数据。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 追踪工作流名称。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 追踪的`group_id`，用于关联多个追踪。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 需要随追踪一同包含的附加元数据。 \ No newline at end of file