diff --git a/docs/ja/agents.md b/docs/ja/agents.md index fa82510ab..adca0e74a 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは、 instructions とツールで構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる構成要素です。エージェントは、指示とツールで構成された大規模言語モデル（ LLM ）です。 -## 基本設定 +## 基本構成 エージェントで最も一般的に設定するプロパティは次のとおりです。 - `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer message または system prompt とも呼ばれます。 -- `model`: どの LLM を使うか、また `model_settings` で temperature、top_p などのモデル調整パラメーターを設定できます。 -- `tools`: エージェントがタスクを達成するために使用できるツールです。 +- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 +- `model`: どの LLM を使用するかを指定し、任意で `model_settings` により temperature、top_p などのモデル調整パラメーターを設定します。 +- `tools`: エージェントがタスクの達成に使用できるツールです。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態をまとめて持つ入れ物として機能します。任意の Python オブジェクトをコンテキストとして提供できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態の寄せ集めとして機能します。コンテキストには任意の Python オブジェクトを指定できます。 ```python @dataclass @@ -52,7 +52,7 @@ agent = Agent[UserContext]( ## 出力タイプ -デフォルトでは、エージェントはプレーンテキスト（つまり `str`）の出力を生成します。特定のタイプの出力を生成したい場合は、`output_type` パラメーターを使用できます。一般的な選択は [Pydantic](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、リスト、TypedDict など）をサポートします。 ```python from pydantic import BaseModel @@ -77,16 +77,16 @@ agent = Agent( ## マルチエージェント システムの設計パターン -マルチエージェント システムの設計方法は多数ありますが、汎用的に適用できるパターンとしてよく見られるのは次の 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](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 @@ -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` プロパティでエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 +場合によっては、エージェントのライフサイクルを観測したいことがあります。たとえば、イベントをログに記録したり、特定のイベント発生時にデータを事前取得したりすることが考えられます。`hooks` プロパティを使ってエージェントのライフサイクルにフックできます。[`AgentHooks`][agents.lifecycle.AgentHooks] クラスをサブクラス化し、関心のあるメソッドをオーバーライドしてください。 ## ガードレール -ガードレールにより、エージェントの実行と並行して ユーザー 入力に対するチェック/検証を実行し、エージェントの出力が生成された後にもチェック/検証を実行できます。たとえば、 ユーザー の入力とエージェントの出力を関連性でスクリーニングできます。詳しくは [guardrails](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 にツールを使用しない（_not_）ことを必須にします。 -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 2e6244d25..c91a68512 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 を使用します。これを上書きして Chat Completions API を使うには、[set_default_openai_api()][agents.set_default_openai_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,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグ ログ +## デバッグロギング -SDK にはハンドラー未設定の 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送られ、それ以外のログは抑制されることを意味します。 +SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これにより警告とエラーは `stdout` に送信されますが、その他のログは抑制されます。 -詳細なログを有効化するには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 +詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 ```python from agents import enable_verbose_stdout_logging @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) を参照してください。 +また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging ガイド](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 8e87ae091..7ae3b41ba 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという語は多義的です。ここで関心があるコンテキストには主に 2 つのクラスがあります。 +コンテキストという用語は多義的です。考慮すべき主なコンテキストには次の 2 つのクラスがあります。 -1. コードからローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要となるデータや依存関係です。 -2. LLM に利用可能なコンテキスト: 応答を生成する際に LLM が参照できるデータです。 +1. コードからローカルに利用可能なコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に利用可能なコンテキスト: 応答生成時に LLM が目にするデータです。 ## ローカルコンテキスト これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的なパターンとしては、データクラスや 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` でアクセスできます。 -これは **最重要** のポイントですが、あるエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じ種類（_type_）のコンテキストを使用する必要があります。 +**最も重要** な注意点: あるエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じ型のコンテキストを使用する必要があります。 コンテキストは次のような用途に使えます: -- 実行用のコンテキストデータ（例: ユーザー名 / uid やその他のユーザー情報） +- 実行のためのコンテキストデータ（例: ユーザー名/uid などユーザーに関する情報） - 依存関係（例: ロガーオブジェクト、データフェッチャーなど） - ヘルパー関数 !!! danger "Note" - コンテキストオブジェクトは **送信されません** LLM に。ローカル専用のオブジェクトであり、読み取り・書き込みやメソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM には送信されません。読み書きやメソッド呼び出しができる、純粋にローカルなオブジェクトです。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここではデータクラスを使用していますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っているのがわかります。ツールの実装はコンテキストから値を読み取ります。 -3. エージェントにはジェネリクスの `UserInfo` を付与して、型チェッカーがエラーを検出できるようにします（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツールの実装はコンテキストから読み取ります。 +3. 型チェッカーでエラーを検出できるように、ジェネリックの `UserInfo` をエージェントに指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 4. `run` 関数にコンテキストを渡します。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 -## エージェント / LLM のコンテキスト +## エージェント/LLM のコンテキスト -LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。つまり、LLM に新しいデータを利用させたい場合は、その履歴で利用可能になる形で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴のものだけです。つまり、LLM に新しいデータを利用させたい場合は、その履歴で利用可能になるような方法で提供する必要があります。方法はいくつかあります。 -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. リトリーバル（ファイル検索（retrieval））や Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル / ファイル検索）、あるいはウェブ（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答を「グラウンディング」するのに有用です。 \ No newline at end of file +1. Agent の `instructions` に追加します。これは「システムプロンプト」または「developer message」とも呼ばれます。システムプロンプトは静的な文字列でも、コンテキストを受け取って文字列を出力する動的関数でもかまいません。常に有用な情報（例: ユーザー名や現在の日付）に適した一般的な手法です。 +2. `Runner.run` を呼ぶ際の `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) の下位にメッセージを配置できます。 +3. 関数ツールを通じて公開します。これはオンデマンドのコンテキストに有用です。LLM は必要なときにデータを要求し、ツールを呼び出してそのデータを取得できます。 +4. リトリーバルや Web 検索を使用します。これらは、ファイルやデータベース（リトリーバル）またはウェブ（Web 検索）から関連データを取得できる特別なツールです。関連するコンテキストデータに基づいて応答を「グラウンディング」するのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index adecccd5e..47f5e163f 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) の examples セクションで、SDK のさまざまなサンプル実装をご覧ください。これらのコード例は、異なるパターンや機能を示すいくつかの カテゴリー に整理されています。 +[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):** - この カテゴリー のコード例は、次のような一般的な エージェント の設計パターンを示します。 + このカテゴリーの例では、一般的な エージェント の設計パターンを示します。例えば、 - - 決定的なワークフロー + - 決定論的ワークフロー - ツールとしての エージェント - エージェント の並列実行 - - 条件付きツール利用 - - 入出力 ガードレール - - 判定者としての LLM + - 条件付きのツール使用 + - 入力/出力 ガードレール + - LLM を審査員として利用 - ルーティング - ストリーミング ガードレール - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - このコード例では、SDK の基礎的な機能を次のように紹介します。 + このカテゴリーの例では、次のような SDK の基礎的な機能を紹介します。 - - Hello World のコード例（ Default model、GPT-5、open-weight model） + - Hello World の code examples（Default model、 GPT-5、 open-weight model） - エージェント のライフサイクル管理 - 動的な システムプロンプト - - ストリーミング 出力（text、items、function call args） - - プロンプト テンプレート - - ファイル処理（ローカル と リモート、画像 と 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):** - hosted 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 セッション ストレージ + - 暗号化セッション ストレージ + - OpenAI セッション ストレージ - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - カスタム プロバイダや LiteLLM 連携を含め、非 OpenAI モデルを SDK で使用する方法を探ります。 + カスタム プロバイダーや LiteLLM 連携を含む、非 OpenAI モデルを SDK で使う方法。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイムな体験を構築する方法のコード例。以下を含みます: + SDK を使ってリアルタイムな体験を構築する方法の例。以下を含みます: - Web アプリケーション - コマンドライン インターフェイス - 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 cb7e80db5..58127e4a4 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールは、あなたのエージェントと _並行して_ 実行され、ユーザー入力のチェックと検証を可能にします。たとえば、顧客からのリクエスト対応に、非常に賢い（つまり遅く/高価な）モデルを使うエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせるようなことは避けたいはずです。そこで、速く/安価なモデルでガードレールを実行できます。ガードレールが悪意ある使用を検知した場合は、即座にエラーを発生させ、高価なモデルの実行を止めて時間やコストを節約できます。 +ガードレールはエージェントと並行して実行され、ユーザー入力のチェックと検証を行います。例えば、非常に賢い（つまり遅く/高価な）モデルでカスタマーリクエストを支援するエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせるよう求めることは避けたいはずです。そのため、速く/安価なモデルでガードレールを実行できます。ガードレールが不正使用を検出すると、即座にエラーを発生させ、高価なモデルの実行を停止して時間とコストを節約できます。 -ガードレールには 2 種類あります: +ガードレールには次の 2 種類があります。 -1. 入力ガードレールは最初のユーザー入力で実行されます -2. 出力ガードレールは最終的なエージェント出力で実行されます +1. 入力ガードレールは初期のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェントの出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 ステップで実行されます: +入力ガードレールは 3 つの手順で動作します。 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップします。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 入力ガードレールはユーザー入力での実行を想定しているため、あるエージェントのガードレールは、そのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行することになるので、コードを同じ場所に置くと可読性が向上します。 + 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールは、そのエージェントが最初のエージェントの場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡されないのかと疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 ## 出力ガードレール -出力ガードレールは 3 ステップで実行されます: +出力ガードレールは 3 つの手順で動作します。 1. まず、ガードレールはエージェントが生成した出力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、これを [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップします。 -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出され、ユーザーへの適切な応答や例外処理が可能になります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。 !!! Note - 出力ガードレールは最終的なエージェント出力での実行を想定しているため、あるエージェントのガードレールは、そのエージェントが「最後の」エージェントである場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所に置くと可読性が向上します。 + 出力ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントのガードレールは、そのエージェントが最後のエージェントの場合にのみ実行されます。入力ガードレールと同様に、ガードレールは実際のエージェントに密接に関連する傾向があるため、コードを同じ場所に置くことで可読性が向上します。 ## トリップワイヤー -入力または出力がガードレールに不合格となった場合、ガードレールはトリップワイヤーでその事実を知らせます。トリップワイヤーが作動したガードレールを検知するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。 +入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤーでそれを示せます。トリップワイヤーが作動したガードレールを検出するとすぐに、`{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェントの実行を停止します。 ## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、内部でエージェントを実行してこれを行います。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。次の例では、内部でエージェントを実行してこれを行います。 ```python from pydantic import BaseModel @@ -96,7 +96,7 @@ async def main(): 1. このエージェントをガードレール関数内で使用します。 2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果に追加情報を含めることができます。 +3. ガードレールの結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 出力ガードレールも同様です。 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index d6d627926..63eede9c0 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] 関数を使うと、さまざまなカスタマイズが可能です。 -- `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` パラメーターで制御します。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されたことが分かった時点でデータ取得を開始するなどに役立ちます。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 - `input_type`: ハンドオフが想定する入力の型（任意）。 - `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうか。ブール値またはブール値を返す関数を指定でき、実行時に動的に有効・無効を切り替えられます。 +- `is_enabled`: ハンドオフを有効にするかどうか。ブール値、またはブール値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## ハンドオフの入力 -状況によっては、ハンドオフを呼び出す際に LLM にデータを提供してほしい場合があります。例えば「エスカレーション エージェント」へのハンドオフを想像してください。ログを取れるように理由を提供してほしいかもしれません。 +状況によっては、ハンドオフを呼び出す際に LLM によるデータの提供が必要になることがあります。例えば、「エスカレーションエージェント」へのハンドオフを想定してください。記録のために、理由を渡したい場合があります。 ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継いだかのように振る舞い、過去の会話履歴全体を参照できます。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、これまでの会話履歴全体を参照できるかのように動作します。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、既存の入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。 -いくつかの一般的なパターン（例えば履歴からすべてのツール呼び出しを取り除くなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 +いくつかの一般的なパターン（例えば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装済みです。 ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. これにより、`FAQ agent` が呼び出されたときに履歴からツールが自動的にすべて削除されます。 +1. これは、`FAQ agent` が呼び出されたときに履歴からすべてのツールを自動的に削除します。 ## 推奨プロンプト -LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスを用意しています。または、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動的に追加できます。 +LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨のプレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出すことで、推奨データをプロンプトに自動的に追加できます。 ```python from agents import Agent diff --git a/docs/ja/index.md b/docs/ja/index.md index a460484af..cff1eb5bb 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 -- **ハンドオフ**、特定のタスクでエージェントが他のエージェントに委譲できる機能 -- **ガードレール**、エージェントの入力と出力の検証を可能にする機能 -- **セッション**、エージェントの実行をまたいで会話履歴を自動で維持する機能 +- **エージェント**: 指示とツールを備えた LLM +- **ハンドオフ**: 特定のタスクで他のエージェントに委譲できる機能 +- **ガードレール**: エージェントの入力と出力を検証する機能 +- **セッション**: 複数のエージェント実行間で会話履歴を自動的に維持 -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を十分に表現でき、急な学習曲線なしに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化・デバッグでき、評価やアプリケーション向けモデルのファインチューニングにも活用できます。 +Python と組み合わせることで、これらの基本コンポーネントはツールとエージェント間の複雑な関係を表現でき、学習コストをかけずに実運用レベルのアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** があり、エージェントのフローを可視化してデバッグできるほか、評価したり、アプリケーション向けにモデルをファインチューニングすることも可能です。 ## Agents SDK を使う理由 -この SDK には 2 つの設計原則があります。 +SDK の設計原則は次の 2 点です。 -1. 使う価値があるだけの機能は備えるが、学習が速いよう基本コンポーネントの数は少なく。 -2. そのままでも高い品質で動作し、必要に応じて挙動を細かくカスタマイズ可能。 +1. 使う価値があるだけの機能を備えつつ、学習が早く済むよう基本コンポーネントは少数に保つ。 +2. すぐに使えて動作が良好でありながら、挙動を細部までカスタマイズできる。 SDK の主な機能は次のとおりです。 -- エージェント ループ: ツールの呼び出し、結果を LLM に渡す処理、LLM が完了するまでのループを内蔵で処理します。 -- Python ファースト: 新しい抽象を学ぶ必要はなく、言語の組み込み機能でエージェントをオーケストレーションし、連結できます。 -- ハンドオフ: 複数のエージェント間での調整と委譲を可能にする強力な機能です。 -- ガードレール: エージェントと並行して入力の検証やチェックを実行し、失敗時には早期に中断できます。 -- セッション: エージェントの実行をまたいだ会話履歴を自動管理し、手動の状態管理を不要にします。 -- 関数ツール: 任意の Python 関数をツールに変換し、自動スキーマ生成と 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 @@ -51,7 +51,7 @@ print(result.final_output) # Infinite loop's dance. ``` -(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_) +( _これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定してください_ ) ```bash export OPENAI_API_KEY=sk-... diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index 71b6b495a..ed0056cdd 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -6,32 +6,34 @@ search: [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. +> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP を AI +> アプリケーション向けの USB-C ポートのようなものだと考えてください。USB-C が、さまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は +> AI モデルを多様なデータソースやツールに接続する標準化された方法を提供します。 -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 サーバーを呼び出させたい | **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 サーバーを呼び出させる | **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] 経由で | -以下のセクションでは、それぞれのオプション、設定方法、そしてどのトランスポートを選ぶべきかについて説明します。 +以下のセクションでは、それぞれのオプションの設定方法と、どのトランスポートを選ぶべきかの目安を説明します。 ## 1. Hosted MCP server tools -Hosted ツールは、ツールのラウンドトリップ全体を OpenAI のインフラに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、あなたの Python プロセスへの追加のコールバックなしにそれらを呼び出します。Hosted ツールは現在、Responses API の hosted MCP 統合をサポートする OpenAI モデルで動作します。 +Hosted ツールは、ツールの往復処理全体を OpenAI のインフラストラクチャに委ねます。あなたのコードがツールを列挙・呼び出す代わりに、 +[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、あなたの Python プロセスへの追加コールバックなしにそれらを呼び出します。Hosted ツールは現在、Responses API の hosted MCP 統合をサポートする OpenAI モデルで動作します。 -### 基本的な hosted MCP ツール +### Basic hosted MCP tool -エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` の dict は、REST API に送信する JSON を反映します: +エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` +の dict は、REST API に送信する JSON を反映します: ```python import asyncio @@ -59,11 +61,11 @@ async def main() -> None: asyncio.run(main()) ``` -hosted サーバーはそのツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 +Hosted サーバーはそのツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 -### ストリーミング対応の hosted MCP 実行結果 +### Streaming hosted MCP results -Hosted ツールは 関数ツール とまったく同じ方法で ストリーミング に対応します。`Runner.run_streamed` に `stream=True` を渡すと、モデルがまだ動作中でも MCP の出力を増分で取り込めます: +Hosted ツールは、関数ツールとまったく同じ方法で ストリーミング 結果をサポートします。モデルがまだ処理中の間に増分的な MCP 出力を消費するには、`Runner.run_streamed` に `stream=True` を渡します: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -73,9 +75,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 @@ -103,11 +106,12 @@ agent = Agent( ) ``` -コールバックは同期・非同期のどちらでもよく、モデルが実行を続けるために承認データを必要とするたびに呼び出されます。 +このコールバックは同期または非同期のいずれでもよく、モデルが処理を続けるために承認データを必要とするたびに呼び出されます。 -### コネクタ対応の hosted サーバー +### Connector-backed hosted servers -Hosted MCP は OpenAI connectors にも対応します。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、hosted サーバーがそのコネクタのツールを公開します。 +Hosted MCP は OpenAI connectors もサポートします。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。 +Responses API が認証を処理し、hosted サーバーがコネクタのツールを公開します。 ```python import os @@ -123,12 +127,13 @@ HostedMCPTool( ) ``` -ストリーミング、承認、コネクタを含む、完全に動作する hosted ツールのサンプルは +ストリーミング、承認、コネクタを含む完全な 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 +168,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) を参照）。 +- `max_retry_attempts` と `retry_backoff_seconds_base` は、`list_tools()` と `call_tool()` の自動リトライを追加します。 +- `tool_filter` により、公開するツールのサブセットだけを露出できます（[Tool filtering](#tool-filtering) を参照）。 ## 3. HTTP with SSE MCP servers -MCP サーバーが HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 +MCP サーバーが HTTP with SSE トランスポートを実装している場合は、 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外は、API は Streamable HTTP サーバーと同一です。 ```python @@ -201,7 +207,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 @@ -227,13 +233,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 @@ -251,11 +257,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] を受け取る callable を渡します。callable は同期または非同期のいずれでもよく、ツールを公開すべき場合に `True` を返します。 ```python from pathlib import Path @@ -279,14 +285,15 @@ async with MCPServerStdio( ... ``` -フィルタコンテキストは、アクティブな `run_context`、ツールを要求している `agent`、そして `server_name` を公開します。 +フィルタコンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 -## プロンプト +## Prompts -MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトに対応するサーバーは次の 2 つのメソッドを公開します: +MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 +つのメソッドを公開します: - `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じて パラメーター 付きの具体的なプロンプトを取得します。 +- `get_prompt(name, arguments)` は、任意のパラメーターとともに具体的なプロンプトを取得します。 ```python from agents import Agent @@ -304,11 +311,11 @@ agent = Agent( ) ``` -## キャッシュ +## Caching -すべての エージェント 実行は各 MCP サーバーに対して `list_tools()` を呼び出します。リモートサーバーは顕著なレイテンシを招く可能性があるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開します。ツール定義が頻繁に変わらないと確信できる場合にのみ `True` に設定してください。後で新しいリストを強制するには、サーバーインスタンスで `invalidate_tools_cache()` を呼び出します。 +各 エージェント 実行では、各 MCP サーバーに対して `list_tools()` を呼び出します。リモートサーバーは目立つレイテンシーをもたらす可能性があるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変わらないと確信できる場合にのみ `True` に設定してください。後で新しい一覧を強制するには、サーバーインスタンスで `invalidate_tools_cache()` を呼び出します。 -## トレーシング +## Tracing [Tracing](./tracing.md) は MCP のアクティビティを自動的に捕捉します。含まれるもの: @@ -317,8 +324,8 @@ agent = Agent( ![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 78069412a..d9d0ba9ba 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には、OpenAI モデルをすぐに使える形で 2 種類サポートしています。 +Agents SDK には 2 種類の OpenAI モデルのサポートが標準搭載されています。 -- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 +- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい Responses API(https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。Chat Completions API(https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。 ## OpenAI モデル -`Agent` を初期化する際にモデルを指定しない場合、デフォルトのモデルが使われます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント型ワークフローにおける予測可能性と低レイテンシのバランスに優れています。 +`Agent` を初期化するときにモデルを指定しない場合は、デフォルトのモデルが使用されます。現在のデフォルトは [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) で、エージェント的ワークフローにおける予測可能性と低レイテンシのバランスに優れています。 -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など別のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) など他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 -### 既定の OpenAI モデル +### デフォルトの OpenAI モデル -カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使いたい場合は、エージェントを実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。 +カスタムモデルを設定していないすべての エージェント で特定のモデルを一貫して使用したい場合は、 エージェント を実行する前に `OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 モデル -この方法で GPT-5 のいずれかの推論モデル（[`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 モデル -[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", ...) @@ -67,29 +67,29 @@ gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ### 非 OpenAI モデルを使う他の方法 -他の LLM プロバイダを統合する方法はさらに 3 つあります（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーを 3 つの方法で統合できます（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使いたい場合に便利です。これは、LLM プロバイダが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能な code examples は [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` レベルで指定します。これにより、「この実行のすべてのエージェントにカスタムモデルプロバイダを使う」と指定できます。設定可能な code examples は [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 インスタンスでモデルを指定できます。これにより、エージェントごとに異なるプロバイダを組み合わせて使えます。設定可能な code examples は [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/モデルを使用しています。もしお使いの LLM プロバイダが Responses をサポートしている場合は、Responses の使用をおすすめします。 + これらの例では、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] の両方の形状をサポートしていますが、両者はサポートする機能やツールのセットが異なるため、各ワークフローでは 1 つのモデル形状に統一することをおすすめします。ワークフローでモデル形状を混在させる必要がある場合は、使用する機能が両方で利用可能であることを確認してください。 + 本 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] の実装を提供します。 -エージェントで使用するモデルをさらに設定したい場合は、[`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 を使用する際には、他にもいくつかの任意 パラメーター（例: `user`、`service_tier` など）があります(https://platform.openai.com/docs/api-reference/responses/create)。トップレベルで利用できない場合は、`extra_args` を使ってそれらを渡せます。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダ使用時の一般的な問題 +## 他の LLM プロバイダー使用時の一般的な問題 -### トレーシング クライアントエラー 401 +### トレーシング クライアントのエラー 401 -トレーシング関連のエラーが発生する場合、トレースは OpenAI サーバーにアップロードされる一方で、OpenAI の API キーを持っていないことが原因です。解決策は次の 3 つです。 +トレーシング に関連するエラーが発生する場合、トレースは OpenAI サーバー にアップロードされるため、OpenAI の API キーがないことが原因です。解決策は次の 3 つです。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードのみに使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. 非 OpenAI のトレース プロセッサーを使用する。[tracing のドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +2. トレーシング 用に OpenAI のキーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 +3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシング ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決策は次の 2 つです。 +SDK はデフォルトで Responses API を使用しますが、多くの他の LLM プロバイダーはまだ対応していません。その結果、404 などの問題が発生することがあります。解決するには、次のいずれかを行います。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +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、マルチモーダル入力、ホスト型のファイル検索や Web 検索をサポートしていますが、他の多くのプロバイダはこれらをサポートしていません。以下の制限に注意してください。 +モデルプロバイダー間の機能差に注意しないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、多くの他のプロバイダーはそれらをサポートしていません。次の制限に注意してください。 -- サポートしていない `tools` を理解できないプロバイダに送らないでください -- テキスト専用モデルを呼び出す前に、マルチモーダル入力をフィルタリングしてください -- structured JSON 出力をサポートしていないプロバイダは、無効な JSON を生成することがあります \ No newline at end of file +- サポートしていない `tools` を理解しないプロバイダーに送らない +- テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングする +- 構造化された JSON 出力をサポートしないプロバイダーは、無効な JSON を生成する場合がある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 6e28977af..7201476b5 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -2,17 +2,17 @@ search: exclude: true --- -# LiteLLM 経由での任意モデルの利用 +# LiteLLM 経由で任意のモデルの使用 !!! note - LiteLLM 連携はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [GitHub の issues](https://github.com/openai/openai-agents-python/issues) にご報告ください。迅速に修正します。 + LiteLLM 統合はベータ版です。特に小規模なモデルプロバイダーでは問題が発生する可能性があります。問題があれば [Github issues](https://github.com/openai/openai-agents-python/issues) からご報告ください。迅速に修正します。 -[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 連携を追加し、任意の AI モデルを利用できるようにしました。 +[LiteLLM](https://docs.litellm.ai/docs/) は、単一のインターフェースで 100+ のモデルを利用できるライブラリです。Agents SDK に LiteLLM 統合を追加し、任意の AI モデルを使用できるようにしました。 ## セットアップ -`litellm` が利用可能である必要があります。オプションの `litellm` 依存関係グループをインストールしてください。 +`litellm` が利用可能であることを確認する必要があります。オプションの `litellm` 依存関係グループをインストールしてください: ```bash pip install "openai-agents[litellm]" @@ -22,13 +22,13 @@ pip install "openai-agents[litellm]" ## 例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます。 +これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます: -- `openai/gpt-4.1` をモデルに、OpenAI API キー +- `openai/gpt-4.1` をモデルに、OpenAI の API キー - `anthropic/claude-3-5-sonnet-20240620` をモデルに、Anthropic の API キー - など -LiteLLM でサポートされているモデルの完全な一覧は、[litellm providers ドキュメント](https://docs.litellm.ai/docs/providers)をご覧ください。 +LiteLLM でサポートされているモデルの完全な一覧は、[litellm providers docs](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 8de26ec1b..544421d75 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順番で実行され、次に何をするかをどのように決めるのか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で動き、次に何をするかをどのように決めるのか。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定させる方法: LLM の知能を使って計画・推論し、それに基づいて実行すべき手順を決めます。 -2. コードでオーケストレーションする方法: コードでエージェントのフローを決定します。 +1. LLM に意思決定を任せる: LLM の知性を使って計画・推論し、それに基づいて取るべき手順を決めます。 +2. コードでオーケストレーションする: コードでエージェントの流れを決定します。 -これらのパターンは組み合わせて使えます。各方法にはそれぞれトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、ツール、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたとき、LLM がツールを使って行動したりデータを取得したり、ハンドオフを使ってサブエージェントにタスクを委譲したりしながら、タスクへの取り組み方を自律的に計画できることを意味します。例えば、リサーチ用エージェントには次のようなツールを備えられます。 +エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はタスクへの取り組み方を自律的に計画し、ツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントにタスクを委任できます。例えば、リサーチ用エージェントには次のようなツールを装備できます。 -- オンラインで情報を見つけるための Web 検索 -- プロプライエタリデータやコネクションを検索するための ファイル検索 と取得 -- コンピュータ上で行動を実行するための コンピュータ操作 -- データ分析を行うためのコード実行 -- 計画やレポート作成などに優れた専門エージェントへのハンドオフ +- Web 検索でオンラインの情報を見つける +- ファイル検索と取得で独自データや接続を横断的に検索する +- コンピュータ操作でコンピュータ上のアクションを実行する +- コード実行でデータ分析を行う +- 計画やレポート作成などに優れた特化型エージェントへのハンドオフ -このパターンは、タスクがオープンエンドで、LLM の知能に依存したい場合に有効です。ここで重要な戦術は次のとおりです。 +このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に有効です。ここで最も重要な戦術は次のとおりです。 -1. 良いプロンプトに投資する。利用可能なツール、その使い方、運用すべきパラメーターを明確にします。 -2. アプリを監視し、反復改善する。問題が起きる箇所を把握し、プロンプトを改善します。 -3. エージェントに内省と改善を許可する。例えばループで実行して自己批評させる、またはエラーメッセージを提供して自己改善させます。 -4. 何でもこなす汎用エージェントではなく、1 つのタスクに特化して優れる専門エージェントを用意する。 -5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを訓練し、タスクの上達を図れます。 +1. 良いプロンプトを作り込みましょう。利用可能なツール、その使い方、そしてどのパラメーター内で動作すべきかを明確にします。 +2. アプリをモニタリングして改善を重ねましょう。問題が起きる箇所を観察し、プロンプトを反復改善します。 +3. エージェントが内省して改善できるようにしましょう。例えばループで実行し、自己批評させる、あるいはエラーメッセージを渡して改善させます。 +4. 何でもそつなくこなす汎用エージェントではなく、1 つのタスクに秀でた特化エージェントを用意しましょう。 +5. [評価 (evals)](https://platform.openai.com/docs/guides/evals) に投資しましょう。これによりエージェントを訓練し、タスク遂行能力を向上できます。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・パフォーマンスの観点でより決定的かつ予測可能になります。一般的なパターンは次のとおりです。 -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかのカテゴリーに分類させ、その カテゴリー に基づいて次のエージェントを選ぶことができます。 -- 複数のエージェントを、前の出力を次の入力に変換して連鎖させる。ブログ記事の執筆のようなタスクを、リサーチ→アウトライン作成→本文執筆→批評→改善といった一連のステップに分解できます。 -- タスクを実行するエージェントと、評価とフィードバックを行うエージェントを `while` ループで回し、評価者が特定の基準を満たしたと判断するまで続ける。 -- 複数のエージェントを並行実行する（例: Python の基本コンポーネントである `asyncio.gather` を使用）。相互依存のない複数タスクがある場合、速度向上に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる 適切な形式のデータ を生成する。例えば、エージェントにタスクをいくつかの カテゴリー に分類させ、その カテゴリー に基づいて次のエージェントを選ぶ、といったことができます。 +- 複数のエージェントを連鎖させ、あるエージェントの出力を次のエージェントの入力に変換する。ブログ記事の執筆なら、リサーチ、アウトライン作成、本文執筆、批評、改善といった一連のステップに分解できます。 +- タスクを実行するエージェントと、評価・フィードバックを行うエージェントを `while` ループで回し、評価者が出力が一定の基準を満たしたと判断するまで実行する。 +- 複数のエージェントを並列実行する（例: Python の基本コンポーネントである `asyncio.gather` を使用）。相互依存しない複数のタスクがある場合、速度向上に有効です。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数の code examples があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の例があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index b58b99615..f178c8171 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -6,7 +6,7 @@ search: ## プロジェクトと仮想環境の作成 -一度だけ実行すれば大丈夫です。 +これは一度だけ実行すれば十分です。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナル セッションを開始するたびに実行します。 +新しいターミナルセッションを開始するたびに実行します。 ```bash source .venv/bin/activate @@ -30,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 @@ -71,7 +71,7 @@ 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 @@ -192,12 +192,12 @@ if __name__ == "__main__": ## トレースの表示 -エージェント 実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動して、エージェント 実行のトレースを表示します。 +エージェントの実行で何が起きたかを確認するには、OpenAI Dashboard の Trace viewer に移動して、エージェント実行のトレースを表示します。 ## 次のステップ -より複雑な エージェント フローの構築方法: +より複雑なエージェント フローの構築方法: -- [エージェント](agents.md) の設定方法について学びます。 -- [エージェントの実行](running_agents.md) について学びます。 -- [ツール](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 facace1d3..25180af06 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # ガイド -このガイドでは、 OpenAI Agents SDK の realtime 機能を使用して音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、OpenAI Agents SDK のリアルタイム機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +リアルタイム エージェントはベータ版です。実装の改善に伴い破壊的変更が入る可能性があります。 ## 概要 -Realtime エージェントは、会話フローを可能にし、音声とテキスト入力をリアルタイムで処理し、リアルタイム音声で応答します。OpenAI の Realtime API との永続的な接続を維持し、低遅延で自然な音声会話と、割り込みへの柔軟な対応を実現します。 +リアルタイム エージェントは、会話フローを可能にし、音声とテキストの入力をリアルタイムで処理し、リアルタイム音声で応答します。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話と、割り込みへの優雅な対応を実現します。 ## アーキテクチャ ### コアコンポーネント -realtime システムは次の主要コンポーネントで構成されます: +リアルタイム システムは、次の主要なコンポーネントで構成されます。 -- **RealtimeAgent**: instructions、ツール、ハンドオフで構成されたエージェント。 -- **RealtimeRunner**: 構成を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッション。通常、ユーザー が会話を開始するたびに作成し、会話が終了するまで存続させます。 -- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeAgent**: `instructions`、`tools`、`handoffs` を設定したエージェントです。 +- **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 +- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデル インターフェース（通常は OpenAI の WebSocket 実装） ### セッションフロー -一般的な realtime セッションの流れは次のとおりです: +一般的なリアルタイム セッションは次のフローに従います。 -1. instructions、ツール、ハンドオフを使用して **RealtimeAgent を作成** します。 -2. エージェントと構成オプションで **RealtimeRunner を設定** します。 -3. `await runner.run()` を使用して **セッションを開始** し、 RealtimeSession が返されます。 -4. `send_audio()` または `send_message()` を使用して **音声またはテキストメッセージを送信** します。 -5. セッションを反復処理して **イベントをリッスン** します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. ユーザー がエージェントの発話に被せて話した場合の **割り込みを処理** します。これにより現在の音声生成は自動で停止します。 +1. **RealtimeAgent を作成** し、`instructions`、`tools`、`handoffs` を設定します。 +2. **RealtimeRunner をセットアップ** し、エージェントと設定オプションを渡します。 +3. `await runner.run()` を使って **セッションを開始** し、RealtimeSession を受け取ります。 +4. `send_audio()` または `send_message()` を使用して **音声またはテキスト メッセージを送信** します。 +5. セッションをイテレートして **イベントをリッスン** します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザーがエージェントの発話に被せて話したときに発生する **割り込みに対応** します。これにより現在の音声生成は自動的に停止します。 -セッションは会話履歴を維持し、realtime モデルとの永続的な接続を管理します。 +セッションは会話履歴を保持し、リアルタイム モデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は、通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。完全な API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご確認ください。 +RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な相違点があります。完全な API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェント レベルではなく、セッション レベルで設定します。 -- structured outputs のサポートはありません（`outputType` はサポートされません）。 -- 声質はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- ツール、ハンドオフ、instructions などのその他の機能は同様に動作します。 +- モデルの選択はエージェント レベルではなく、セッション レベルで設定します。 +- structured output のサポートはありません（`outputType` はサポートされません）。 +- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- ツール、ハンドオフ、instructions など、その他の機能は同様に動作します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となる realtime モデルの動作を制御できます。モデル名（`gpt-realtime` など）、声質（alloy、echo、fable、onyx、nova、shimmer）およびサポートするモダリティ（テキストおよび/または音声）を設定できます。音声フォーマットは入力と出力の両方に設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となるリアルタイム モデルの動作を制御できます。モデル名（例: `gpt-realtime`）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、サポートするモダリティ（テキストおよび/または音声）を設定できます。音声のフォーマットは入力・出力の両方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定は、セッションが音声入力と出力をどのように扱うかを制御します。Whisper などのモデルを使用した入力音声の書き起こし、言語設定、ドメイン固有用語の精度を高めるための書き起こしプロンプトを設定できます。発話区間検出（turn detection）の設定では、エージェントが応答を開始・終了するタイミングを制御でき、音声活動検出のしきい値、無音時間、検出された音声の前後に付与するパディングなどのオプションがあります。 +音声設定では、セッションが音声の入出力をどのように扱うかを制御します。Whisper などのモデルを使用した入力音声の文字起こし、言語設定、ドメイン特有の用語に対する精度を高めるための書き起こしプロンプトを指定できます。ターン検出の設定により、音声活動検出の閾値、無音時間、検出された音声の前後パディングなどを通じて、エージェントがいつ応答を開始・終了すべきかを制御できます。 ## ツールと関数 ### ツールの追加 -通常のエージェントと同様に、realtime エージェントは会話中に実行される 関数ツール をサポートします: +通常のエージェントと同様に、リアルタイム エージェントは会話中に実行される 関数ツール をサポートします。 ```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**: エージェントの応答からの raw な音声データ +- **audio_end**: エージェントが話し終えました +- **audio_interrupted**: ユーザーがエージェントを割り込みました +- **tool_start/tool_end**: ツール実行のライフサイクル +- **handoff**: エージェントのハンドオフが発生しました +- **error**: 処理中にエラーが発生しました -完全なイベントの詳細は、[`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 +完全なイベントの詳細は [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent] を参照してください。 ## ガードレール -Realtime エージェントでサポートされるのは出力用ガードレールのみです。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるため、（単語ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 +リアルタイム エージェントでサポートされるのは出力 ガードレール のみです。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために（毎語ではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースのガードレールは併用して実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースからのガードレールは併せて実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,17 +152,17 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントが生成され、エージェントの現在の応答を中断できます。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキスト エージェントと異なり、realtime エージェントはガードレールが作動しても **Exception** は発生させません。 +ガードレールがトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を割り込むことがあります。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキスト エージェントとは異なり、リアルタイム エージェントはガードレールに引っかかっても例外をスローしません。 ## 音声処理 -[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用してセッションに音声を送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 +[`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] を使用して音声をセッションに送信するか、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用してテキストを送信します。 -音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで音声データを再生してください。ユーザー がエージェントを割り込んだ場合に即座に再生を停止し、キューにある音声をクリアするため、`audio_interrupted` イベントも必ずリッスンしてください。 +音声出力については、`audio` イベントをリッスンし、任意の音声ライブラリで音声データを再生します。ユーザーがエージェントを割り込んだ際に即座に再生を停止し、キューにある音声をクリアできるよう、`audio_interrupted` イベントを必ずリッスンしてください。 -## 直接モデルアクセス +## 直接的なモデルアクセス -基盤となるモデルにアクセスして、カスタムリスナーを追加したり高度な操作を実行したりできます: +基盤となるモデルにアクセスして、カスタム リスナーを追加したり高度な操作を実行したりできます。 ```python # Add a custom listener to the model @@ -171,6 +171,6 @@ session.model.add_listener(my_custom_listener) これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## 例 +## コード例 -動作する完全な例は、[examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。UI コンポーネントの有無それぞれのデモが含まれています。 \ No newline at end of file +完全に動作するサンプルは、UI コンポーネントあり/なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index 91b9ea43d..86e1e46eb 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,20 +4,20 @@ search: --- # クイックスタート -リアルタイム エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声会話を可能にします。このガイドでは、最初のリアルタイム音声エージェントの作成方法を順を追って説明します。 +リアルタイム エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声対話を可能にします。このガイドでは、最初のリアルタイム音声エージェントを作成する手順を説明します。 !!! warning "ベータ機能" -リアルタイム エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 +Realtime agents はベータ版です。実装の改善に伴い、破壊的な変更が発生する可能性があります。 ## 前提条件 -- 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 @@ -109,9 +109,9 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 完全な例 +## 完全なコード例 -動作する完全な例はこちらです: +以下は動作する完全な例です: ```python import asyncio @@ -192,34 +192,34 @@ 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`: 発話前の音声パディング ## 次のステップ -- [リアルタイム エージェントの詳細](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) フォルダ内の動作するサンプルコードを確認 +- エージェントにツールを追加 +- エージェント間のハンドオフを実装 +- 安全性のためのガードレールを設定 ## 認証 -環境変数に OpenAI API キーが設定されていることを確認します: +環境に OpenAI API キーが設定されていることを確認してください: ```bash export OPENAI_API_KEY="your-api-key-here" diff --git a/docs/ja/release.md b/docs/ja/release.md index d1990e04c..1c2ba837f 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,17 +4,17 @@ search: --- # リリースプロセス/変更履歴 -本プロジェクトは、`0.Y.Z` 形式のセマンティック バージョニングを一部調整して採用しています。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 +このプロジェクトは、`0.Y.Z` という形式を用いた、やや変更を加えたセマンティック バージョニングに従います。先頭の `0` は、SDK がなお急速に進化していることを示します。各コンポーネントの増分は次のとおりです。 -## マイナー（`Y`）バージョン +## マイナー (`Y`) バージョン -ベータとしてマークされていない公開インターフェースに対する **破壊的変更** の場合、マイナー バージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への更新には破壊的変更が含まれることがあります。 +ベータとしてマークされていない公開インターフェースに対する **破壊的変更** がある場合、マイナー バージョン `Y` を上げます。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる可能性があります。 破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 -## パッチ（`Z`）バージョン +## パッチ (`Z`) バージョン -互換性を壊さない変更の場合に `Z` を増やします: +後方互換性を壊さない変更については `Z` を増分します。 - バグ修正 - 新機能 @@ -25,8 +25,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` の 2 つの params が追加されました。`MCPServer` をサブクラス化しているクラスには、これらの params を追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に新しいパラメーターが 2 つ追加されました: `run_context` と `agent`。`MCPServer` を継承するすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 33770c514..2f88466c6 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,9 +4,8 @@ search: --- # REPL ユーティリティ -この SDK は、`run_demo_loop` を提供しており、ターミナルでエージェントの動作を素早く対話的にテストできます。 +この SDK は、ターミナルでエージェントの動作を素早く対話的にテストできる `run_demo_loop` を提供します。 - ```python import asyncio from agents import Agent, run_demo_loop @@ -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 +このチャットセッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボードショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index bfcade689..4a87b3c70 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -2,55 +2,55 @@ search: exclude: true --- -# 実行結果 +# 結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが得られます。 +`Runner.run` メソッドを呼び出すと、次のいずれかが返ります。 -- `run` または `run_sync` を呼び出した場合は [`RunResult`][agents.result.RunResult] -- `run_streamed` を呼び出した場合は [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -これらはいずれも [`RunResultBase`][agents.result.RunResultBase] を継承しており、最も有用な情報の多くがここに含まれます。 +どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はそこに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。次のいずれかです。 - 最後のエージェントに `output_type` が定義されていない場合は `str` - エージェントに出力タイプが定義されている場合は `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] です。Run item は、LLM によって生成された raw アイテムをラップします。 +[`new_items`][agents.result.RunResultBase.new_items] プロパティには、実行中に生成された新しいアイテムが含まれます。アイテムは [`RunItem`][agents.items.RunItem] です。実行アイテムは、LLM が生成した raw アイテムをラップします。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] は LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] は、LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM のツール呼び出しアイテムです。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] は、ハンドオフが発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 -- [`ToolCallItem`][agents.items.ToolCallItem] は、LLM がツールを呼び出したことを示します。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] は、ツールが呼び出されたことを示します。raw アイテムはツールの応答です。アイテムからツールの出力にもアクセスできます。 -- [`ReasoningItem`][agents.items.ReasoningItem] は、LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 +- [`MessageOutputItem`][agents.items.MessageOutputItem]: LLM からのメッセージを示します。raw アイテムは生成されたメッセージです。 +- [`HandoffCallItem`][agents.items.HandoffCallItem]: LLM がハンドオフ ツールを呼び出したことを示します。raw アイテムは LLM からのツール呼び出しアイテムです。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem]: ハンドオフ が発生したことを示します。raw アイテムはハンドオフ ツール呼び出しへのツール応答です。アイテムからソース/ターゲットのエージェントにもアクセスできます。 +- [`ToolCallItem`][agents.items.ToolCallItem]: LLM がツールを呼び出したことを示します。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]: ツールが呼び出されたことを示します。raw アイテムはツール応答です。アイテムからツール出力にもアクセスできます。 +- [`ReasoningItem`][agents.items.ReasoningItem]: LLM からの推論アイテムを示します。raw アイテムは生成された推論です。 ## その他の情報 -### ガードレールの実行結果 +### ガードレールの結果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、ガードレールの実行結果が（存在する場合）含まれます。ガードレールの実行結果には、ログや保存に役立つ有用な情報が含まれることがあるため、参照できるようにしています。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] と [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] プロパティには、存在する場合、ガードレールの結果が含まれます。ガードレールの結果には、記録や保存をしたい有用な情報が含まれることがあるため、これらを参照できるようにしています。 -### raw レスポンス +### Raw レスポンス [`raw_responses`][agents.result.RunResultBase.raw_responses] プロパティには、LLM によって生成された [`ModelResponse`][agents.items.ModelResponse] が含まれます。 ### 元の入力 -[`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 e6abfb762..e3cc6c51f 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,53 +23,53 @@ async def main(): # Infinite loop's dance ``` -詳しくは [結果ガイド](results.md) を参照してください。 +詳細は [結果ガイド](results.md) を参照してください。 ## エージェントループ -`Runner` の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ユーザー メッセージと見なされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）です。 +`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ ユーザー メッセージと見なされます）または入力アイテムのリスト（ OpenAI Responses API のアイテム）です。 -Runner は次のループを実行します。 +ランナーは次のループを実行します。 -1. 現在のエージェントと入力で LLM を呼び出します。 +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 の出力が「最終出力 (final output)」と見なされる条件は、求められる型のテキスト出力を生成し、かつツール呼び出しがないことです。 + LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、かつツール呼び出しがない場合です。 ## ストリーミング -ストリーミングを有効にすると、LLM の実行中にストリーミング イベントも受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミング イベントは `.stream_events()` を呼び出してください。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 +ストリーミングを使うと、LLM の実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] に、生成されたすべての新しい出力を含む実行全体の情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すことで取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 -## 実行設定 (Run config) +## 実行設定 `run_config` パラメーターでは、エージェント実行のグローバル設定を構成できます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関係なく、使用するグローバルな LLM モデルを設定します。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するモデルプロバイダーで、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力 ガードレール のリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに入力フィルターが未設定の場合に適用されるグローバル入力フィルターです。入力フィルターでは、新しいエージェントに送信する入力を編集できます。詳しくは [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、LLM やツール呼び出しの入出力など、機微なデータを含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` を設定することを推奨します。グループ ID は任意で、複数の実行にわたってトレースを関連付けられます。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関係なく、使用するグローバルな LLM モデルを設定できます。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力 ガードレール のリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既にフィルターがない場合に適用するグローバル入力フィルターです。入力フィルターでは、新しいエージェントに送信する入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話/チャットスレッド -いずれの run メソッドを呼び出しても、1 回で 1 つ以上のエージェント（つまり 1 回以上の LLM 呼び出し）が実行される可能性はありますが、チャット会話における 1 回の論理的なターンを表します。例: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される場合がありますが、チャット会話における 1 回の論理的なターンを表します。例: -1. ユーザーのターン: ユーザーがテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ、2 番目のエージェントがさらにツールを実行し、その後に出力を生成。 +1. ユーザー ターン: ユーザー がテキストを入力 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ、2 番目のエージェントがさらにツールを実行し、その後出力を生成。 -エージェントの実行終了時に、ユーザーへ何を表示するかを選べます。たとえば、エージェントが生成したすべての新規アイテムを表示するか、最終出力のみを表示するかです。いずれの場合も、ユーザーが追質問をしたら、再度 run メソッドを呼び出せます。 +エージェント実行の最後に、 ユーザー に何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを見せる、または最終出力のみを見せることが可能です。いずれにせよ、 ユーザー が追質問をするかもしれません。その場合は、再度 run メソッドを呼び出します。 -### 手動での会話管理 +### 手動の会話管理 次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 @@ -93,7 +93,7 @@ async def main(): ### Sessions による自動会話管理 -よりシンプルな方法として、[Sessions](sessions.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動処理できます。 +より簡単な方法として、[Sessions](sessions.md) を使えば、`.to_input_list()` を手動で呼び出さずに会話履歴を自動で処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -119,20 +119,20 @@ async def main(): Sessions は自動で次を行います。 -- 各実行前に会話履歴を取得 -- 各実行後に新しいメッセージを保存 -- セッション ID ごとに個別の会話を維持 +- 各実行前に会話履歴を取得 +- 各実行後に新しいメッセージを保存 +- 異なるセッション ID ごとに会話を分離して維持 -詳しくは [Sessions のドキュメント](sessions.md) を参照してください。 +詳細は [Sessions のドキュメント](sessions.md) を参照してください。 ### サーバー管理の会話 -`to_input_list()` や `Sessions` でローカルに管理する代わりに、OpenAI の conversation state 機能にサーバー 側での会話状態管理を任せることもできます。これにより、過去のすべてのメッセージを手動で再送しなくても会話履歴を保持できます。詳しくは [OpenAI Conversation state ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 +`to_input_list()` や `Sessions` でローカルに管理する代わりに、OpenAI の conversation state 機能により サーバー 側で会話状態を管理することもできます。これにより、過去のメッセージをすべて手動で再送信せずに会話履歴を保持できます。詳細は [OpenAI Conversation state ガイド](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 を以降のすべての呼び出しで再利用します。 @@ -164,9 +164,9 @@ async def main(): # California ``` -#### 2. `previous_response_id` を使う +#### 2. `previous_response_id` を使用 -もう 1 つの方法は **response chaining** で、各ターンが前のターンのレスポンス ID に明示的にリンクします。 +もう 1 つの方法は **response chaining** で、各ターンを前のターンのレスポンス ID に明示的に紐付けます。 ```python from agents import Agent, Runner @@ -190,18 +190,18 @@ async def main(): ``` -## 長時間実行エージェントと 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/) 連携を使うと、ヒューマン・イン・ザ・ループのタスクを含む永続的で長時間実行のワークフローを実行できます。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 の API の誤用に起因します。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力 ガードレール または出力 ガードレール の条件が満たされたときに送出されます。入力 ガードレール は処理前に受信メッセージをチェックし、出力 ガードレール はエージェントの最終応答を配信前にチェックします。 \ No newline at end of file diff --git a/docs/ja/sessions.md b/docs/ja/sessions.md index 7e942e461..542b70e74 100644 --- a/docs/ja/sessions.md +++ b/docs/ja/sessions.md @@ -4,9 +4,9 @@ search: --- # セッション -Agents SDK は、複数のエージェント実行にわたって会話履歴を自動で維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 +Agents SDK には、複数のエージェント実行にわたって会話履歴を自動的に保持する組み込みのセッションメモリがあり、ターン間で手動で `.to_input_list()` を扱う必要がなくなります。 -セッションは特定のセッションに対する会話履歴を保存し、明示的な手動メモリ管理なしでエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションやマルチターン会話の構築に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理なしにエージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションやマルチターンの会話を構築する際に特に有用です。 ## クイックスタート @@ -51,17 +51,17 @@ print(result.final_output) # "Approximately 39 million" セッションメモリが有効な場合: -1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの前に付与します。 -2. **各実行の後**: 実行中に生成された新しいアイテム（ユーザー入力、アシスタント応答、ツール呼び出しなど）はすべて自動的にセッションに保存されます。 -3. **コンテキストの保持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーがそのセッションの会話履歴を自動取得し、入力アイテムの先頭に付加します。 +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,7 +119,7 @@ print(f"Agent: {result.final_output}") ## メモリオプション -### メモリなし（デフォルト） +### メモリなし (デフォルト) ```python # Default behavior - no session memory @@ -128,7 +128,7 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API メモリ -自前のデータベースを管理せずに [会話状態](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api) を永続化するには、[OpenAI Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) を使用します。これは、会話履歴の保存に OpenAI がホストするインフラにすでに依存している場合に便利です。 +自前のデータベースを管理せずに [conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api) を永続化するには、[OpenAI Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) を使用します。これは、会話履歴の保存に OpenAI がホストするインフラストラクチャにすでに依存している場合に便利です。 ```python from agents import OpenAIConversationsSession @@ -189,11 +189,11 @@ result2 = await Runner.run( ### SQLAlchemy ベースのセッション -より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）をセッションストレージとして使用できます。 +より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、セッションの保存先として SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) を使用できます。 -**例 1: `from_url` とインメモリ SQLite の使用** +**例 1: `from_url` を使ったインメモリ SQLite の利用** -これは最も簡単な開始方法で、開発やテストに最適です。 +開発やテストに最適な、最も簡単な始め方です。 ```python import asyncio @@ -216,7 +216,7 @@ if __name__ == "__main__": **例 2: 既存の SQLAlchemy エンジンの使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性があります。これをそのままセッションに渡せます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを保有している可能性が高いです。これをセッションに直接渡せます。 ```python import asyncio @@ -244,10 +244,61 @@ if __name__ == "__main__": asyncio.run(main()) ``` +### 暗号化されたセッション + +保存時に会話データの暗号化が必要なアプリケーションでは、`EncryptedSession` を使用して任意のセッションバックエンドを透過的な暗号化と自動 TTL ベースの有効期限でラップできます。これは `encrypt` 追加機能が必要です: `pip install openai-agents[encrypt]`。 + +`EncryptedSession` は、セッションごとの鍵導出 (HKDF) を用いた Fernet 暗号化を使用し、古いメッセージの自動期限切れをサポートします。アイテムが TTL を超えた場合、取得時に黙ってスキップされます。 + +**例: SQLAlchemy セッションデータの暗号化** + +```python +import asyncio +from agents import Agent, Runner +from agents.extensions.memory import EncryptedSession, SQLAlchemySession + +async def main(): + # Create underlying session (works with any SessionABC implementation) + underlying_session = SQLAlchemySession.from_url( + session_id="user-123", + url="postgresql+asyncpg://app:secret@db.example.com/agents", + create_tables=True, + ) + + # Wrap with encryption and TTL-based expiration + session = EncryptedSession( + session_id="user-123", + underlying_session=underlying_session, + encryption_key="your-encryption-key", # Use a secure key from your secrets management + ttl=600, # 10 minutes - items older than this are silently skipped + ) + + agent = Agent("Assistant") + result = await Runner.run(agent, "Hello", session=session) + print(result.final_output) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**主な特長:** + +- **透過的な暗号化**: 保存前にすべてのセッションアイテムを自動的に暗号化し、取得時に復号します +- **セッションごとの鍵導出**: セッション ID をソルトとした HKDF を使用して一意の暗号鍵を導出します +- **TTL ベースの期限管理**: 設定可能な有効期限 (デフォルト: 10 分) に基づいて古いメッセージを自動的に失効させます +- **柔軟な鍵入力**: Fernet キーまたは生の文字列のいずれかを暗号鍵として受け付けます +- **あらゆるセッションをラップ**: SQLite、SQLAlchemy、またはカスタムセッション実装で動作します + +!!! warning "重要なセキュリティに関する注意" + + - 暗号鍵は安全に保管してください (例: 環境変数、シークレットマネージャー) + - 期限切れトークンはアプリケーションサーバーのシステムクロックに基づいて拒否されます。クロックドリフトにより有効なトークンが拒否されないよう、すべてのサーバーが NTP で時刻同期されていることを確認してください + - 基盤となるセッションは引き続き暗号化済みデータを保存するため、データベースインフラの管理は引き続き行えます + ## カスタムメモリ実装 -[`Session`][agents.memory.session.Session] プロトコルに準拠するクラスを作成することで、独自のセッションメモリを実装できます: +[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます: ```python from agents.memory.session import SessionABC @@ -294,19 +345,20 @@ result = await Runner.run( ### セッション ID の命名 -会話を整理しやすくする意味のあるセッション ID を使用します: +会話の整理に役立つ意味のあるセッション ID を使用します: -- ユーザー単位: `"user_12345"` -- スレッド単位: `"thread_abc123"` -- コンテキスト単位: `"support_ticket_456"` +- ユーザー基準: `"user_12345"` +- スレッド基準: `"thread_abc123"` +- コンテキスト基準: `"support_ticket_456"` ### メモリの永続化 -- 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します -- 永続的な会話にはファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します -- 既存のデータベースを使用する本番システムには SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します -- OpenAI Conversations API に履歴を保存したい場合は OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します -- さらに高度なユースケースでは、他の本番システム（Redis、Django など）向けにカスタムセッションバックエンドの実装を検討します +- 一時的な会話にはインメモリ SQLite (`SQLiteSession("session_id")`) を使用します +- 永続的な会話にはファイルベースの SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) を使用します +- 既存のデータベースを持つ本番システムには SQLAlchemy ベースのセッション (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) を使用します +- 履歴を OpenAI Conversations API に保存したい場合は OpenAI がホストするストレージ (`OpenAIConversationsSession()`) を使用します +- 透過的な暗号化と TTL ベースの期限切れを付与するには暗号化セッション (`EncryptedSession(session_id, underlying_session, encryption_key)`) で任意のセッションをラップします +- さらに高度なユースケースでは、他の本番システム (Redis、Django など) 向けのカスタムセッションバックエンドの実装を検討してください ### セッション管理 @@ -334,7 +386,7 @@ result2 = await Runner.run( ## 完全な例 -セッションメモリの動作を示す完全な例は次のとおりです: +セッションメモリが動作する完全な例を次に示します: ```python import asyncio @@ -398,9 +450,10 @@ if __name__ == "__main__": ## API リファレンス -詳細な API ドキュメントは次を参照してください: +詳細な API ドキュメントは次をご覧ください: -- [`Session`][agents.memory.Session] - プロトコルインターフェース -- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 -- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 \ No newline at end of file +- [`Session`][agents.memory.Session] - プロトコルインターフェース +- [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 実装 +- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 実装 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装 +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - TTL 付き暗号化セッションラッパー \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 4770c8862..cc4ca7fb3 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、進行中の エージェント の実行の更新を購読できます。これはエンド ユーザー に進捗や部分的な応答を表示するのに有用です。 +ストリーミングを使うと、進行中の エージェント の実行に関する更新を購読できます。これはエンドユーザーに進捗や部分的なレスポンスを表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出すと、[`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼ぶと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 -## raw 応答イベント +## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これは OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、生成され次第 ユーザー に応答メッセージをストリーミングしたい場合に便利です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。生成され次第、ユーザーにレスポンスメッセージをストリーミングしたい場合に有用です。 -たとえば、これは LLM が生成したテキストをトークンごとに出力します。 +たとえば、次のコードは LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## 実行アイテムイベントと エージェント イベント -[`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 0e1204630..9d272ef81 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント にアクションを実行させます。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には、ツールは次の 3 つのクラスに分類されます。 +ツールは エージェント がアクションを実行できるようにします。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの操作などです。Agents SDK には 3 つのクラスのツールがあります: -- Hosted tools: これらは LLM サーバー 上で AI モデルと並行して実行されます。OpenAI は、リトリーバル、Web 検索、コンピュータ操作 をホスト型ツールとして提供します。 -- 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` モジュールを使用し、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` を第 1 引数として受け取れます。ツール名、説明、docstring スタイルなどの上書き設定も可能です。 -4. デコレートした関数を tools のリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期どちらでも構いません。 +2. docstring が存在する場合、説明や引数の説明の取得に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名や説明、docstring スタイルなどのオーバーライドも設定できます。 +4. デコレートされた関数をツールのリストに渡せます。 -??? note "出力を表示" +??? note "Expand to see output" ``` fetch_weather @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。その場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を指定する必要があります。 +Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: - `name` - `description` - `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力の文字列を返す async 関数） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力の文字列を返す非同期関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、関数シグネチャを自動解析してツールのスキーマを抽出し、docstring を解析してツール全体および各引数の説明を抽出します。補足事項は次のとおりです。 +前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足事項は以下のとおりです: -1. シグネチャの解析は `inspect` モジュールで行います。引数の型は型アノテーションから読み取り、全体スキーマを表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、多くの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。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 @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### ツール化したエージェントのカスタマイズ +### ツール化した エージェントのカスタマイズ -`agent.as_tool` は、エージェント を簡単にツール化するための便宜メソッドです。ただし、すべての設定に対応しているわけではありません（例: `max_turns` は設定不可）。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください。 +`agent.as_tool` 関数は エージェント をツール化するための簡便なメソッドです。ただし、すべての設定をサポートするわけではありません。たとえば `max_turns` は設定できません。高度なユースケースでは、ツール実装内で直接 `Runner.run` を使用してください: ```python @function_tool @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### カスタム出力抽出 -場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を変更したいことがあります。これは次のような場合に有用です。 +場合によっては、中央の エージェント に返す前にツール化した エージェント の出力を加工したいことがあります。たとえば次のような用途です: -- サブエージェント のチャット履歴から特定情報（例: JSON ペイロード）を抽出する。 +- サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 - エージェント の最終回答を変換・再整形する（例: Markdown をプレーンテキストや CSV に変換）。 - 出力を検証し、エージェント の応答が欠落または不正な場合にフォールバック値を提供する。 -これは、`as_tool` メソッドに `custom_output_extractor` 引数を渡すことで実現できます。 +これは `as_tool` メソッドに `custom_output_extractor` 引数を渡すことで可能です: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 条件付きツール有効化 -`is_enabled` パラメーター を使って、実行時に エージェント ツールを条件付きで有効化/無効化できます。これにより、コンテキスト、ユーザー の設定、実行時の条件に基づいて、LLM に提供するツールを動的に絞り込めます。 +実行時に `is_enabled` パラメーターを使って エージェント ツールを条件付きで有効化・無効化できます。これにより、コンテキスト、ユーザー の設定、実行時条件に基づいて LLM に利用可能なツールを動的にフィルタリングできます。 ```python import asyncio @@ -372,26 +372,26 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーター は次を受け付けます。 +`is_enabled` パラメーターは次を受け付けます: - **Boolean 値**: `True`（常に有効）または `False`（常に無効） -- **Callable 関数**: `(context, agent)` を受け取り boolean を返す関数 -- **Async 関数**: 複雑な条件ロジックのための非同期関数 +- **呼び出し可能な関数**: `(context, agent)` を受け取り boolean を返す関数 +- **非同期関数**: 複雑な条件ロジック向けの async 関数 -無効化されたツールは実行時に LLM から完全に隠蔽されるため、次の用途に役立ちます。 +無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: - ユーザー 権限に基づく機能ゲーティング -- 環境別のツール提供（dev と prod） +- 環境別のツール可用性（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` などになり得ます。 +- 既定では（何も渡さない場合）、エラーが発生したことを 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 c6aab21b5..64b24f5b2 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 つあります: 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます + 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を利用し Zero Data Retention (ZDR) ポリシーで運用する組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーの下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンドの処理を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります: - - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service"。 - - `trace_id`: トレースの一意の ID。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースを関連付けます。たとえばチャットスレッド ID など。 +- **トレース** は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" + - `trace_id`: トレースの一意の ID。指定しなければ自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースをリンクするために使用します。たとえば、チャットスレッド ID を使えます。 - `disabled`: True の場合、このトレースは記録されません。 - `metadata`: トレースの任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ処理を表します。スパンには次があります: - - `started_at` と `ended_at` タイムスタンプ - - 属するトレースを示す `trace_id` - - 親スパン（ある場合）を指す `parent_id` - - スパンに関する情報である `span_data`。たとえば、`AgentSpanData` はエージェントに関する情報、`GenerationSpanData` は LLM 生成に関する情報などを含みます。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: + - `started_at` と `ended_at` のタイムスタンプ + - 所属するトレースを表す `trace_id` + - 親スパン (ある場合) を指す `parent_id` + - スパンに関する情報を含む `span_data`。例えば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLM 生成に関する情報を含みます。 ## デフォルトのトレーシング -デフォルトでは、 SDK は次をトレースします: +デフォルトでは、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()` でラップされます -- 関連する音声スパンは `speech_group_span()` の子になる場合があります +- 音声入力 (音声認識) は `transcription_span()` でラップされます +- 音声出力 (音声合成) は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の配下に置かれる場合があります -デフォルトでは、トレース名は "Agent workflow" です。`trace` を使う場合にこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 -さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先に出力できます（置き換え、または副次的な送信先として）。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先に送信できます (置き換えとして、または二次的な宛先として)。 -## 上位レベルのトレース +## 高レベルのトレース -`run()` への複数回の呼び出しを 1 つのトレースにまとめたい場合があります。これを行うには、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 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`）。これにより、適切なタイミングで自動的に開始・終了します。 -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` に、スパン/トレースをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。`BackendSpanExporter` は OpenAI バックエンドへバッチでエクスポートします。 +- 初期化時に、トレースの作成を担当するグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 +- `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] を使うと、デフォルトのプロセッサーを独自のトレースプロセッサーに置き換えることができます。これを行うと、OpenAI バックエンドにトレースは送信されません。送信するには、そのための `TracingProcessor` を含める必要があります。 ## 非 OpenAI モデルでのトレーシング -OpenAI の API キーを非 OpenAI モデルで使用すると、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。 +OpenAI の API キーを非 OpenAI のモデルで使用して、トレーシングを無効化することなく、OpenAI の Traces ダッシュボードで無料のトレーシングを有効化できます。 ```python import os @@ -125,15 +125,15 @@ 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 (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (自己ホスト/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks ホスト)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 290914a9e..3956e00f0 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -4,11 +4,11 @@ search: --- # 使用状況 -Agents SDK は、各実行のトークン使用状況を自動的に追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。 +Agents SDK は、すべての実行におけるトークンの使用状況を自動で追跡します。実行コンテキストから参照でき、コストの監視、制限の適用、分析の記録に利用できます。 ## 追跡対象 -- **requests**: 実行された LLM API 呼び出し数 +- **requests**: 実行された LLM API 呼び出しの数 - **input_tokens**: 送信された入力トークンの合計 - **output_tokens**: 受信した出力トークンの合計 - **total_tokens**: input + output @@ -30,11 +30,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 @@ -52,7 +52,7 @@ print(result.context_wrapper.usage.total_tokens) ## セッションでの使用状況の取得 -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -64,11 +64,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、その特定の実行のみを表します。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、その結果、後続ターンの入力トークン数に影響します。 +セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用状況メトリクスは、あくまでその実行のみを表します。セッションでは、以前のメッセージが各実行の入力として再投入される場合があり、その結果、以後のターンで入力トークン数に影響します。 -## フックでの使用状況の利用 +## フックでの使用状況の活用 -`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用状況を記録できます。 +`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、重要なライフサイクルのタイミングで使用状況を記録できます。 ```python class MyHooks(RunHooks): @@ -79,8 +79,8 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは以下をご覧ください。 +詳細な API ドキュメントは以下を参照してください。 -- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況へアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡のライフサイクルにフックする \ No newline at end of file +- [`Usage`][agents.usage.Usage] - 使用状況の追跡データ構造 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用状況にアクセス +- [`RunHooks`][agents.run.RunHooks] - 使用状況追跡ライフサイクルへのフック \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index b8db162bf..5a71d9cdb 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -4,7 +4,7 @@ search: --- # エージェントの可視化 -エージェントの可視化では、 **Graphviz** を使用してエージェントとその関係を構造的に表現したグラフィカルな図を生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、 **Graphviz** を使ってエージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール @@ -16,12 +16,12 @@ pip install "openai-agents[viz]" ## グラフの生成 -`draw_graph` 関数を使用してエージェントの可視化を生成できます。この関数は、次のような有向グラフを作成します: +`draw_graph` 関数を使ってエージェントの可視化を生成できます。この関数は以下のような有向グラフを作成します: -- **エージェント** は黄色のボックスで表されます。 -- **MCP サーバー** は灰色のボックスで表されます。 -- **ツール** は緑色の楕円で表されます。 -- **ハンドオフ** はエージェント間の有向エッジで表されます。 +- **エージェント** は黄色のボックスで表現されます。 +- **MCP サーバー** はグレーのボックスで表現されます。 +- **ツール** は緑色の楕円で表現されます。 +- **ハンドオフ** は一方のエージェントから別のエージェントへの有向エッジです。 ### 使用例 @@ -69,29 +69,29 @@ draw_graph(triage_agent) ![エージェント グラフ](../assets/images/graph.png) -これにより、 **トリアージ エージェント** の構造と、サブエージェントやツールへの接続を視覚的に表すグラフが生成されます。 +これは、 **トリアージ エージェント** とそのサブエージェントおよびツールへの接続の構造を視覚的に表すグラフを生成します。 ## 可視化の理解 生成されるグラフには以下が含まれます: -- エントリポイントを示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた **長方形** として表されたエージェント。 -- 緑色で塗りつぶされた **楕円** として表されたツール。 -- 灰色で塗りつぶされた **長方形** として表された MCP サーバー。 +- エントリーポイントを示す **開始ノード** (`__start__`)。 +- 黄色で塗りつぶされた長方形で表現される **エージェント**。 +- 緑色で塗りつぶされた楕円で表現される **ツール**。 +- グレーで塗りつぶされた長方形で表現される **MCP サーバー**。 - 相互作用を示す有向エッジ: - - エージェント間のハンドオフを示す **実線の矢印**。 - - ツール呼び出しを示す **点線の矢印**。 - - MCP サーバー呼び出しを示す **破線の矢印**。 -- 実行が終了する位置を示す **終了ノード** (`__end__`)。 + - エージェント間のハンドオフには **実線の矢印**。 + - ツール呼び出しには **点線の矢印**。 + - MCP サーバー呼び出しには **破線の矢印**。 +- 実行が終了する場所を示す **終了ノード** (`__end__`)。 -**Note:** MCP サーバーは、 `agents` パッケージの最近のバージョンで描画されます（ **v0.2.8** で確認済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**注意:** MCP サーバーは最近の `agents` パッケージのバージョンでレンダリングされます（ **v0.2.8** で確認済み）。可視化に MCP のボックスが表示されない場合は、最新リリースにアップグレードしてください。 ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウで表示するには、次のように記述します: +デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウでグラフを表示するには、次のように記述します: ```python draw_graph(triage_agent).view() diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 2f05f11e3..1679e52d7 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,25 +34,25 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際、次の項目を設定できます。 +パイプラインの作成時に、次の項目を設定できます。 -1. 毎回新しい音声が文字起こしされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル -3. 次のような項目を設定できる [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - - モデルプロバイダー（モデル名をモデルにマッピング可能） - - トレーシング（トレーシングの無効化可否、音声ファイルのアップロード可否、ワークフロー名、トレース ID など） - - TTS および STT モデルの設定（プロンプト、言語、使用するデータ型など） +1. 毎回新しい音声が書き起こされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル +3. 次のような設定を行える [`config`][agents.voice.pipeline_config.VoicePipelineConfig] + - モデル名をモデルにマッピングできるモデルプロバイダー + - トレーシング（トレーシングの無効化可否、音声ファイルのアップロード有無、ワークフロー名、trace ID など） + - プロンプト、言語、使用するデータ型など、TTS および STT モデルの設定 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 +パイプラインは、音声入力を 2 つの形式で渡せる [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声書き起こしがあり、その結果のみを生成したい場合に使用します。話者の発話終了を検知する必要がないケース（事前録音の音声や、ユーザーの発話終了が明確なプッシュトゥトーク型のアプリなど）に便利です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了の検知が必要な場合に使用します。検知された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検知」と呼ばれるプロセスによって適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声書き起こしがあり、その結果だけを生成したい場合に使用します。これは、話者の発話終了を検知する必要がないケース、たとえば事前録音の音声や、ユーザーの発話終了が明確なプッシュトゥトーク アプリで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検知する必要がある場合に使用します。検知された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスによって、適切なタイミングでエージェントのワークフローを自動実行します。 ## 結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生するイベントをストリーミングで受け取れるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次のものを含みます。 +音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントを随時ストリーミングできるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 1. 音声チャンクを含む [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] 2. ターンの開始や終了などのライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] @@ -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 859182670..84ffa3aff 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -OpenAI Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします: +OpenAI Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境を設定してください。そのうえで、SDK からオプションの音声依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 概念 -主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、3 つのステップから成るプロセスです: +主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスです。 1. 音声をテキストに変換するために音声認識モデルを実行します。 -2. 通常はエージェント駆動のワークフローであるあなたのコードを実行し、結果を生成します。 -3. 結果のテキストを音声に戻すためにテキスト読み上げモデルを実行します。 +2. 通常はエージェント的なワークフローとなるあなたのコードを実行して結果を生成します。 +3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントをセットアップします。この SDK でエージェントを作成したことがあれば、見覚えがあるはずです。ここでは 2 つのエージェント、ハンドオフ、ツールを用意します。 +まず、いくつかのエージェントを設定します。これは、この SDK でエージェントを作成したことがある方には馴染みがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインを設定します。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使い、シンプルな音声パイプラインを設定します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## 統合 +## すべてをまとめる ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントが話します。自分でエージェントに話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。 \ No newline at end of file +このサンプルを実行すると、エージェントがあなたに話します。自分でエージェントに話しかけられるデモは、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) をご覧ください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 2c6f1656b..2364fdb28 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -6,13 +6,13 @@ search: [エージェントのトレーシング](../tracing.md) と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のドキュメントをご覧ください。また、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを追加で構成できます。 +基本的なトレーシング情報については上記のドキュメントをご覧ください。加えて、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを構成できます。 -トレーシングに関連する主なフィールドは次のとおりです: +主なトレーシング関連フィールドは次のとおりです。 -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトではトレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしのような機微なデータをトレースに含めるかどうかを制御します。これは特に音声パイプライン向けで、あなたの Workflow 内部で行われる処理には適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース Workflow の名前。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための、トレースの `group_id` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加のメタデータ。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。既定ではトレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声の書き起こしなど、機微な可能性のあるデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、ワークフロー内部で行われる処理には適用されません。 +- [`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 91d13ea65..ffb4d8201 100644 --- a/docs/ko/agents.md +++ b/docs/ko/agents.md @@ -4,16 +4,16 @@ search: --- # 에이전트 -에이전트는 앱의 핵심 빌딩 블록입니다. 에이전트는 instructions 와 도구로 구성된 대규모 언어 모델(LLM)입니다. +에이전트는 앱의 핵심 기본 구성 요소입니다. 에이전트는 instructions와 도구로 구성된 대규모 언어 모델(LLM)입니다. ## 기본 구성 -에이전트에서 가장 자주 구성하는 속성은 다음과 같습니다: +에이전트에서 가장 자주 설정하는 속성은 다음과 같습니다: -- `name`: 에이전트를 식별하는 필수 문자열 -- `instructions`: 개발자 메시지 또는 시스템 프롬프트로도 알려져 있음 -- `model`: 사용할 LLM, 그리고 temperature, top_p 등 모델 튜닝 매개변수를 구성하는 선택적 `model_settings` -- `tools`: 에이전트가 작업을 수행하기 위해 사용할 수 있는 도구 +- `name`: 에이전트를 식별하는 필수 문자열 +- `instructions`: 개발자 메시지 또는 시스템 프롬프트로도 알려짐 +- `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` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구로, 여러분이 생성하여 `Runner.run()`에 전달하는 객체이며 모든 에이전트, 도구, 핸드오프 등으로 전달되어 에이전트 실행을 위한 의존성과 상태를 담는 바구니 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다. ```python @dataclass @@ -50,9 +50,9 @@ 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( @@ -151,17 +151,17 @@ agent = Agent[UserContext]( ) ``` -## 수명 주기 이벤트(훅) +## 라이프사이클 이벤트(훅) -때로는 에이전트의 수명 주기를 관찰하고 싶을 수 있습니다. 예를 들어, 이벤트를 로깅하거나 특정 이벤트가 발생할 때 데이터를 미리 가져오고 싶을 수 있습니다. `hooks` 속성을 사용해 에이전트 수명 주기에 훅을 걸 수 있습니다. [`AgentHooks`][agents.lifecycle.AgentHooks] 클래스를 상속하고, 필요한 메서드를 오버라이드하세요. +때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어, 이벤트를 로깅하거나 특정 이벤트가 발생할 때 데이터를 미리 가져오고자 할 수 있습니다. `hooks` 속성으로 에이전트 라이프사이클에 훅을 연결할 수 있습니다. [`AgentHooks`][agents.lifecycle.AgentHooks] 클래스를 상속하고, 관심 있는 메서드를 오버라이드하세요. ## 가드레일 -가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대한 검사/검증을 병렬로 수행하고, 에이전트 출력이 생성된 후에도 검사를 수행할 수 있습니다. 예를 들어, 사용자 입력과 에이전트 출력을 관련성 기준으로 필터링할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 참고하세요. +가드레일을 사용하면 에이전트 실행과 병렬로 사용자 입력에 대한 검사/검증을 수행하고, 출력이 생성된 후 에이전트의 출력에 대해서도 검사/검증을 수행할 수 있습니다. 예를 들어, 사용자 입력과 에이전트 출력을 관련성 기준으로 선별할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 참조하세요. ## 에이전트 복제/복사 -에이전트의 `clone()` 메서드를 사용하면 에이전트를 복제하고, 선택적으로 원하는 속성을 변경할 수 있습니다. +에이전트에서 `clone()` 메서드를 사용하면 에이전트를 복제하고, 원하는 속성을 선택적으로 변경할 수 있습니다. ```python pirate_agent = Agent( @@ -178,12 +178,12 @@ robot_agent = pirate_agent.clone( ## 도구 사용 강제 -도구 목록을 제공해도 LLM 이 항상 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다: +도구 목록을 제공한다고 해서 LLM이 항상 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다: -1. `auto`: LLM 이 도구 사용 여부를 결정 -2. `required`: LLM 이 반드시 도구를 사용하도록 강제(단, 어떤 도구를 쓸지는 지능적으로 선택) -3. `none`: LLM 이 도구를 _사용하지 않도록_ 강제 -4. 특정 문자열 지정(예: `my_tool`): LLM 이 해당 특정 도구를 사용하도록 강제 +1. `auto`: LLM이 도구 사용 여부를 스스로 결정 +2. `required`: LLM이 반드시 도구를 사용해야 함(어떤 도구를 사용할지는 지능적으로 결정 가능) +3. `none`: LLM이 도구를 사용하지 _않도록_ 요구 +4. 특정 문자열 설정(예: `my_tool`): LLM이 해당 특정 도구를 사용하도록 요구 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -203,9 +203,9 @@ agent = Agent( ## 도구 사용 동작 -`Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력 처리 방식을 제어합니다: +`Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력이 처리되는 방식을 제어합니다: -- `"run_llm_again"`: 기본값. 도구를 실행하고, LLM 이 결과를 처리해 최종 응답을 생성 +- `"run_llm_again"`: 기본값. 도구를 실행한 후, LLM이 결과를 처리하여 최종 응답을 생성 - `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력을 추가 LLM 처리 없이 최종 응답으로 사용 ```python @@ -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/ko/config.md b/docs/ko/config.md index 1b5fe8da9..06c540c92 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는 환경 변수 또는 위에서 설정한 기본 키를 사용해 `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,7 +52,7 @@ set_tracing_disabled(True) ## 디버그 로깅 -SDK에는 핸들러가 설정되지 않은 두 개의 Python 로거가 있습니다. 기본적으로 이는 경고와 오류가 `stdout`으로 전송되고, 다른 로그는 억제됨을 의미합니다. +SDK에는 핸들러가 설정되지 않은 두 개의 Python 로거가 있습니다. 기본적으로 경고와 오류는 `stdout`으로 전송되며, 다른 로그는 숨겨집니다. 자세한 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요. @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -또는 핸들러, 필터, 포매터 등을 추가하여 로그를 커스터마이즈할 수 있습니다. 자세한 내용은 [Python logging 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. +또는 핸들러, 필터, 포매터 등을 추가해 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. ```python import logging @@ -83,7 +83,7 @@ logger.addHandler(logging.StreamHandler()) ### 로그의 민감한 데이터 -일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. 이 데이터를 로깅하지 않으려면 다음 환경 변수를 설정하세요. +일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. 이러한 데이터가 로깅되지 않도록 하려면 다음 환경 변수를 설정하세요. LLM 입력과 출력을 로깅하지 않으려면: diff --git a/docs/ko/context.md b/docs/ko/context.md index cfa0b58af..0654fa655 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. 원하는 파이썬 객체를 만듭니다. 보편적인 패턴은 dataclass 또는 Pydantic 객체를 사용하는 것입니다 +2. 해당 객체를 다양한 실행 메서드에 전달합니다(예: `Runner.run(..., **context=whatever**)`) +3. 모든 도구 호출, 라이프사이클 훅 등에는 `RunContextWrapper[T]` 래퍼 객체가 전달되며, 여기서 `T`는 컨텍스트 객체 타입을 나타내며 `wrapper.context`로 접근할 수 있습니다 -가장 중요한 점: 특정 에이전트 실행에 사용되는 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 컨텍스트의 _타입_ 을 사용해야 합니다. +**가장 중요한 점**: 특정 에이전트 실행에 포함되는 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 _타입_의 컨텍스트를 사용해야 합니다. 컨텍스트는 다음과 같은 용도로 사용할 수 있습니다: -- 실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 또는 기타 사용자 정보) +- 실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 같은 사용자 정보) - 의존성(예: 로거 객체, 데이터 페처 등) - 헬퍼 함수 !!! danger "주의" - 컨텍스트 객체는 LLM 에게 **전송되지 않습니다**. 이는 순수하게 로컬 객체로, 읽고 쓰거나 메서드를 호출할 수 있습니다. + 컨텍스트 객체는 LLM에 **전송되지 않습니다**. 순수하게 로컬 객체이며 읽고, 쓰고, 메서드를 호출할 수 있습니다. ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass 를 사용했지만, 어떤 타입이든 사용할 수 있습니다. -2. 이것은 도구입니다. `RunContextWrapper[UserInfo]` 를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다. -3. 타입 체커가 오류를 잡을 수 있도록 에이전트를 제네릭 `UserInfo` 로 표시합니다(예: 다른 컨텍스트 타입을 받는 도구를 전달하려고 하는 경우). -4. 컨텍스트는 `run` 함수에 전달됩니다. -5. 에이전트는 도구를 올바르게 호출하고 나이를 가져옵니다. +1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만, 어떤 타입이든 사용할 수 있습니다 +2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다 +3. 타입 체커가 오류를 잡을 수 있도록 제네릭 `UserInfo`로 에이전트를 표시합니다(예: 다른 컨텍스트 타입을 받는 도구를 전달하려고 할 때) +4. `run` 함수에 컨텍스트가 전달됩니다 +5. 에이전트는 도구를 올바르게 호출하고 나이를 가져옵니다 ## 에이전트/LLM 컨텍스트 -LLM 이 호출될 때, 볼 수 있는 **유일한** 데이터는 대화 기록뿐입니다. 따라서 LLM 에게 새로운 데이터를 제공하려면, 그 데이터를 대화 기록에서 볼 수 있도록 만들어야 합니다. 이를 위한 방법은 몇 가지가 있습니다: +LLM이 호출될 때, 그것이 볼 수 있는 데이터는 대화 기록뿐입니다. 따라서 LLM에 새로운 데이터를 제공하려면, 그 데이터가 해당 기록에 포함되도록 해야 합니다. 다음과 같은 방법들이 있습니다: -1. 에이전트 `instructions` 에 추가합니다. 이는 "system prompt" 또는 "developer message" 라고도 부릅니다. 시스템 프롬프트는 정적 문자열일 수도, 컨텍스트를 받아 문자열을 출력하는 동적 함수일 수도 있습니다. 항상 유용한 정보(예: 사용자 이름이나 현재 날짜)에는 흔히 쓰이는 방식입니다. -2. `Runner.run` 함수를 호출할 때 `input` 에 추가합니다. 이는 `instructions` 방식과 비슷하지만, [지휘 계통](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 메시지를 사용할 수 있게 해줍니다. -3. 함수 도구로 노출합니다. 이는 필요 시(on-demand) 컨텍스트에 유용합니다. LLM 이 언제 데이터가 필요한지 스스로 결정하고, 해당 데이터를 가져오기 위해 도구를 호출할 수 있습니다. -4. retrieval 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져오는 기능(retrieval) 또는 웹에서 데이터를 가져오는 기능(웹 검색)을 제공하는 특수 도구입니다. 관련 컨텍스트 데이터에 근거한 응답을 만들 때 유용합니다. \ 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/ko/examples.md b/docs/ko/examples.md index 27085f761..b4e48fbe0 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -2,60 +2,60 @@ search: exclude: true --- -# 예제 +# 코드 예제 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 code examples 섹션에서 SDK의 다양한 샘플 구현을 확인하세요. 예제는 여러 카테고리로 구성되어 있으며 다양한 패턴과 기능을 보여줍니다. +[repo](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 as a judge - 라우팅 - 스트리밍 가드레일 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 이 예제들은 SDK의 기초 기능을 보여줍니다 + 이 코드 예제들은 다음과 같은 SDK의 기초 기능을 보여줍니다 - - Hello World 예제 (기본 모델, GPT-5, 오픈 웨이트 모델) - - 에이전트 수명주기 관리 + - Hello World 예제(Default model, GPT-5, open-weight model) + - 에이전트 라이프사이클 관리 - 동적 시스템 프롬프트 - - 스트리밍 출력 (텍스트, 아이템, 함수 호출 args) + - 스트리밍 출력(텍스트, 아이템, 함수 호출 인자) - 프롬프트 템플릿 - - 파일 처리 (로컬 및 원격, 이미지와 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):** - 메시지 필터링과 함께하는 에이전트 핸드오프의 실용적인 예제 + 메시지 필터링이 포함된 에이전트 핸드오프의 실용적인 코드 예제 - **[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 세션 스토리지 @@ -65,29 +65,29 @@ search: - OpenAI 세션 스토리지 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 커스텀 제공자와 LiteLLM 통합을 포함하여, OpenAI 가 아닌 모델을 SDK에서 사용하는 방법 살펴보기 + 커스텀 프로바이더와 LiteLLM 통합을 포함해, OpenAI 이외의 모델을 SDK와 함께 사용하는 방법을 살펴보세요 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제, 포함 내용: + SDK를 사용해 실시간 경험을 구축하는 방법에 대한 코드 예제 - 웹 애플리케이션 - 커맨드라인 인터페이스 - - 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 호스트하는 도구를 구현하는 방법을 배웁니다 - - 웹 검색 및 필터를 포함한 웹 검색 + - 웹 검색 및 필터가 있는 웹 검색 - 파일 검색 - - 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/ko/guardrails.md b/docs/ko/guardrails.md index 559a4de31..54d4f9af6 100644 --- a/docs/ko/guardrails.md +++ b/docs/ko/guardrails.md @@ -4,44 +4,44 @@ search: --- # 가드레일 -가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력에 대한 점검과 검증을 할 수 있게 합니다. 예를 들어, 고객 요청을 처리하기 위해 매우 똑똑한(즉, 느리고/비싼) 모델을 사용하는 에이전트가 있다고 상상해 보세요. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것을 원치 않을 것입니다. 이때 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜 비용이 큰 모델의 실행을 중단하고 시간/비용을 절약할 수 있습니다. +가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력에 대한 점검과 검증을 수행합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(그만큼 느리고 비싼) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것을 원치 않을 것입니다. 이때 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜, 비용이 많이 드는 모델의 실행을 중단하고 시간과 비용을 절약합니다. 가드레일에는 두 가지 종류가 있습니다: -1. 입력 가드레일은 초기 사용자 입력에서 실행됩니다 -2. 출력 가드레일은 최종 에이전트 출력에서 실행됩니다 +1. 입력 가드레일은 최초 사용자 입력에서 실행됨 +2. 출력 가드레일은 최종 에이전트 출력에서 실행됨 ## 입력 가드레일 입력 가드레일은 3단계로 실행됩니다: 1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. -2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑됩니다. -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이를 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑합니다 +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하며, 이에 따라 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. 왜 `guardrails` 속성이 `Runner.run`에 전달되지 않고 에이전트에 있는지 궁금할 수 있습니다. 가드레일은 실제 에이전트와 연관되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하므로, 코드를 함께 배치하면 가독성에 유리합니다. + 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *처음* 에이전트일 때만 실행됩니다. `guardrails` 속성이 왜 에이전트에 있고 `Runner.run`에 전달되지 않는지 궁금할 수 있습니다. 가드레일은 실제 에이전트와 밀접하게 연관되는 경향이 있기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행할 것이므로, 코드를 함께 두면 가독성에 도움이 됩니다. ## 출력 가드레일 출력 가드레일은 3단계로 실행됩니다: 1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다. -2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑됩니다. -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이를 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑합니다 +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하며, 이에 따라 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 연관되는 경향이 있기 때문에 코드를 함께 배치하는 것이 가독성에 유리합니다. + 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 밀접하게 연관되기 때문에 코드를 함께 두면 가독성에 도움이 됩니다. ## 트립와이어 -입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. +입력 또는 출력이 가드레일을 통과하지 못하면, 가드레일은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 감지하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. ## 가드레일 구현 -입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예시에서는 내부적으로 에이전트를 실행하여 이를 수행합니다. +입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예제에서는 내부적으로 에이전트를 실행하여 이를 구현하겠습니다. ```python from pydantic import BaseModel @@ -95,9 +95,9 @@ async def main(): ``` 1. 이 에이전트를 가드레일 함수에서 사용합니다. -2. 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다. +2. 이것은 에이전트의 입력/컨텍스트를 받고 결과를 반환하는 가드레일 함수입니다. 3. 가드레일 결과에 추가 정보를 포함할 수 있습니다. -4. 워크플로를 정의하는 실제 에이전트입니다. +4. 이것은 워크플로를 정의하는 실제 에이전트입니다. 출력 가드레일도 유사합니다. @@ -152,7 +152,7 @@ async def main(): print("Math output guardrail tripped") ``` -1. 실제 에이전트의 출력 타입입니다. -2. 가드레일의 출력 타입입니다. -3. 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다. -4. 워크플로를 정의하는 실제 에이전트입니다. \ No newline at end of file +1. 이것은 실제 에이전트의 출력 타입입니다. +2. 이것은 가드레일의 출력 타입입니다. +3. 이것은 에이전트의 출력을 받고 결과를 반환하는 가드레일 함수입니다. +4. 이것은 워크플로를 정의하는 실제 에이전트입니다. \ No newline at end of file diff --git a/docs/ko/handoffs.md b/docs/ko/handoffs.md index 06f63c45e..cdf254011 100644 --- a/docs/ko/handoffs.md +++ b/docs/ko/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] 함수를 사용해 핸드오프를 생성할 수 있습니다. 이 함수로 핸드오프 대상 에이전트를 지정하고, 선택적으로 override 와 입력 필터를 설정할 수 있습니다. -### 기본 사용 +### 기본 사용법 -간단한 핸드오프를 생성하는 방법은 다음과 같습니다: +간단한 핸드오프를 만드는 방법은 다음과 같습니다: ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. 에이전트를 직접 사용할 수도 있고(예: `billing_agent`), `handoff()` 함수를 사용할 수도 있습니다. +1. `billing_agent` 처럼 에이전트를 직접 사용할 수도 있고, `handoff()` 함수를 사용할 수도 있습니다. ### `handoff()` 함수를 통한 핸드오프 커스터마이징 -[`handoff()`][agents.handoffs.handoff] 함수로 다양한 항목을 커스터마이징할 수 있습니다. +[`handoff()`][agents.handoffs.handoff] 함수로 다양한 항목을 커스터마이즈할 수 있습니다. - `agent`: 핸드오프 대상 에이전트 -- `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, 이는 `transfer_to_` 로 설정됩니다. 이를 오버라이드할 수 있습니다 -- `tool_description_override`: `Handoff.default_tool_description()` 의 기본 도구 설명을 오버라이드 -- `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출되는 즉시 데이터 페칭을 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 받고, 선택적으로 LLM 이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다 -- `input_type`: 핸드오프에서 기대하는 입력 타입(선택 사항) -- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 자세한 내용은 아래를 참조하세요 -- `is_enabled`: 핸드오프의 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수가 될 수 있어 런타임에 동적으로 활성/비활성화할 수 있습니다 +- `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, 이는 `transfer_to_` 으로 결정됩니다. 이 값을 override 할 수 있습니다. +- `tool_description_override`: `Handoff.default_tool_description()` 의 기본 도구 설명을 override +- `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출되었음을 인지하자마자 데이터 페칭을 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 받으며, 선택적으로 LLM 이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다. +- `input_type`: 핸드오프에서 기대하는 입력의 타입(선택 사항) +- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 아래 내용을 참고하세요. +- `is_enabled`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수가 될 수 있어 런타임에 동적으로 핸드오프를 활성/비활성화할 수 있습니다. ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## 핸드오프 입력 -특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 함께 제공하길 원할 수 있습니다. 예를 들어, "에스컬레이션 에이전트"로의 핸드오프를 가정해 보겠습니다. 로깅을 위해 사유가 함께 제공되면 유용할 수 있습니다. +특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하길 원할 수 있습니다. 예를 들어, "에스컬레이션 에이전트" 로의 핸드오프를 상상해 보세요. 기록을 위해 사유를 제공받고 싶을 수 있습니다. ```python from pydantic import BaseModel @@ -84,9 +84,9 @@ handoff_obj = handoff( ## 입력 필터 -핸드오프가 발생하면, 새 에이전트가 대화를 인수하여 이전 대화 내역 전체를 볼 수 있게 됩니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter] 를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData] 로 기존 입력을 받아 새로운 `HandoffInputData` 를 반환해야 하는 함수입니다. +핸드오프가 발생하면, 마치 새 에이전트가 대화를 인계받아 이전의 전체 대화 히스토리를 보게 되는 것과 같습니다. 이를 변경하고 싶다면 [`input_filter`][agents.handoffs.Handoff.input_filter] 를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData] 를 통해 기존 입력을 받고, 새로운 `HandoffInputData` 를 반환해야 하는 함수입니다. -일반적인 패턴(예: 히스토리에서 모든 도구 호출 제거)이 몇 가지 있으며, 이는 [`agents.extensions.handoff_filters`][] 에 구현되어 있습니다. +일반적인 패턴들이 일부 존재하며(예: 히스토리에서 모든 도구 호출 제거), 이는 [`agents.extensions.handoff_filters`][] 에 구현되어 있습니다. ```python from agents import Agent, handoff @@ -100,11 +100,11 @@ handoff_obj = handoff( ) ``` -1. 이는 `FAQ agent` 가 호출될 때 히스토리에서 모든 도구를 자동으로 제거합니다. +1. 이는 `FAQ 에이전트` 가 호출될 때 히스토리에서 모든 도구를 자동으로 제거합니다. -## 권장 프롬프트 +## 추천 프롬프트 -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 87cc20be6..567526c0f 100644 --- a/docs/ko/index.md +++ b/docs/ko/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)는 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 해줍니다. 이는 이전 에이전트 실험인 [Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션 준비가 된 업그레이드입니다. Agents SDK에는 소수의 기본 구성 요소만 있습니다: +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)는 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 만들 수 있게 해줍니다. 이는 이전의 에이전트 실험인 [Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션 준비된 업그레이드입니다. Agents SDK는 매우 작은 범위의 기본 구성 요소를 제공합니다: - **에이전트**: instructions와 tools를 갖춘 LLM -- **핸드오프**: 특정 작업에 대해 에이전트가 다른 에이전트에 위임할 수 있도록 함 +- **핸드오프**: 특정 작업에 대해 다른 에이전트에게 위임할 수 있게 함 - **가드레일**: 에이전트 입력과 출력의 검증을 가능하게 함 -- **세션**: 에이전트 실행 전반에 걸쳐 대화 기록을 자동으로 유지함 +- **세션**: 에이전트 실행 간 대화 기록을 자동으로 유지 관리함 -Python과 결합하면, 이 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버깅할 수 있는 내장 **트레이싱**이 포함되어 있어, 이를 평가하고 심지어 애플리케이션용 모델을 파인튜닝할 수도 있습니다. +파이썬과 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 사이의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버그하며, 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수 있게 해주는 내장 **트레이싱**이 포함되어 있습니다. -## Agents SDK를 사용하는 이유 +## Agents SDK 사용 이유 -이 SDK의 설계 원칙은 두 가지입니다: +SDK는 두 가지 설계 원칙을 따릅니다: 1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있도록 기본 구성 요소는 최소화합니다. -2. 기본 설정만으로도 훌륭하게 동작하지만, 동작 방식을 정확히 원하는 대로 사용자 정의할 수 있습니다. +2. 기본 설정으로도 훌륭하게 동작하지만, 동작 방식을 정확히 커스터마이즈할 수 있습니다. SDK의 주요 기능은 다음과 같습니다: -- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 수행하는 내장 에이전트 루프 -- 파이썬 우선: 새로운 추상화를 배울 필요 없이, 내장 언어 기능으로 에이전트를 오케스트레이션하고 체이닝 +- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 처리하는 내장 에이전트 루프 +- 파이썬 우선: 새로운 추상화를 배우지 않고도 파이썬의 내장 언어 기능으로 에이전트를 오케스트레이션하고 체이닝 - 핸드오프: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 -- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 실행하고, 점검이 실패하면 조기에 중단 -- 세션: 에이전트 실행 전반의 대화 기록을 자동으로 관리하여 수동 상태 처리를 제거 -- 함수 도구: 어떤 Python 함수든 도구로 전환하며, 스키마 자동 생성과 Pydantic 기반 검증 제공 -- 트레이싱: 워크플로를 시각화, 디버그, 모니터링할 수 있는 내장 트레이싱과 함께 OpenAI의 평가, 파인튜닝, 지식 증류 도구를 활용 가능 +- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 실행하고, 점검 실패 시 조기에 중단 +- 세션: 에이전트 실행 간 대화 기록을 자동 관리하여 수동 상태 관리 제거 +- 함수 도구: 어떤 파이썬 함수든 도구로 전환하고, 자동 스키마 생성과 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/ko/mcp.md b/docs/ko/mcp.md index 458719a04..ba6d60469 100644 --- a/docs/ko/mcp.md +++ b/docs/ko/mcp.md @@ -4,36 +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. +> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 표준 방식으로 연결해 주듯이, MCP는 AI 모델을 서로 다른 데이터 소스와 도구에 표준 방식으로 연결해 줍니다. -Agents Python SDK는 여러 MCP 트랜스포트를 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 직접 구축해 파일시스템, HTTP, 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. +Agents Python SDK는 여러 MCP 트랜스포트를 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 직접 구축하여 파일 시스템, HTTP, 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. ## MCP 통합 선택 -에이전트에 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 +## 1. 호스티드 MCP 서버 도구 -호스티드 툴은 전체 도구 왕복 호출을 OpenAI 인프라에서 처리합니다. 코드가 도구를 나열하고 호출하는 대신, -[`HostedMCPTool`][agents.tool.HostedMCPTool]이 서버 라벨(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은 원격 서버의 도구를 나열하고, 추가적인 Python 프로세스 콜백 없이 이를 호출합니다. 호스티드 툴은 현재 Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델과 함께 작동합니다. +Hosted tools 는 전체 도구 왕복을 OpenAI 인프라로 위임합니다. 코드에서 도구를 나열하고 호출하는 대신, +[`HostedMCPTool`][agents.tool.HostedMCPTool] 이 서버 라벨(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은 원격 서버의 도구를 나열하고, Python 프로세스로의 추가 콜백 없이 도구를 호출합니다. Hosted tools 는 현재 Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 동작합니다. ### 기본 호스티드 MCP 도구 -에이전트의 `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,12 +59,11 @@ async def main() -> None: asyncio.run(main()) ``` -호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers`에 추가할 필요가 없습니다. +호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers` 에 추가할 필요가 없습니다. -### 스트리밍 호스티드 MCP 결과 +### 호스티드 MCP 결과 스트리밍 -호스티드 툴은 함수 도구와 동일한 방식으로 스트리밍을 지원합니다. `Runner.run_streamed`에 `stream=True`를 전달해 -모델이 아직 작업 중일 때 점진적인 MCP 출력을 소비하세요: +Hosted tools 는 함수 도구와 정확히 동일한 방식으로 스트리밍 결과를 지원합니다. 모델이 계속 실행되는 동안 증분 MCP 출력을 소비하려면 `Runner.run_streamed` 에 `stream=True` 를 전달하세요: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -78,8 +75,7 @@ print(result.final_output) ### 선택적 승인 플로우 -서버가 민감한 작업을 수행할 수 있는 경우 각 도구 실행 전에 사람 또는 프로그램적 승인을 요구할 수 있습니다. `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 @@ -107,12 +103,11 @@ agent = Agent( ) ``` -콜백은 동기 또는 비동기로 구현할 수 있으며, 모델이 실행을 계속하기 위해 승인 데이터가 필요할 때마다 호출됩니다. +콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행하기 위해 승인 데이터가 필요할 때마다 호출됩니다. ### 커넥터 기반 호스티드 서버 -호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. -Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다. +호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url` 을 지정하는 대신 `connector_id` 와 액세스 토큰을 제공하세요. Responses API가 인증을 처리하고, 호스티드 서버가 커넥터의 도구를 노출합니다. ```python import os @@ -128,13 +123,13 @@ 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 서버 네트워크 연결을 직접 관리하려면 -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 사용하세요. Streamable HTTP 서버는 트랜스포트를 직접 제어하거나 서버를 자체 인프라 내에서 실행하면서 지연 시간을 낮게 유지하고 싶을 때 이상적입니다. +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 를 사용하세요. Streamable HTTP 서버는 트랜스포트를 제어하거나, 지연 시간을 낮게 유지하면서 자체 인프라 내에서 서버를 실행하고자 할 때 이상적입니다. ```python import asyncio @@ -169,17 +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) 참고) +- `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) 참조) ## 3. HTTP with SSE MCP 서버 -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 @@ -208,8 +203,7 @@ async with MCPServerSse( ## 4. stdio MCP 서버 -로컬 서브프로세스로 실행되는 MCP 서버에는 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 사용하세요. SDK는 -프로세스를 생성하고 파이프를 열린 상태로 유지하며 컨텍스트 매니저가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른 개념 증명이나 서버가 커맨드라인 엔트리 포인트만 노출하는 경우에 유용합니다. +로컬 서브프로세스로 실행되는 MCP 서버의 경우 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 를 사용하세요. SDK가 프로세스를 생성하고 파이프를 유지하며 컨텍스트 매니저가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른 개념 증명에 유용하며, 서버가 커맨드 라인 엔트리 포인트만 노출할 때도 도움이 됩니다. ```python from pathlib import Path @@ -237,11 +231,11 @@ async with MCPServerStdio( ## 도구 필터링 -각 MCP 서버는 에이전트에 필요한 기능만 노출할 수 있도록 도구 필터를 지원합니다. 필터링은 생성 시점이나 실행마다 동적으로 수행할 수 있습니다. +각 MCP 서버는 에이전트에 필요한 함수만 노출할 수 있도록 도구 필터를 지원합니다. 필터링은 생성 시점 또는 실행별로 동적으로 수행할 수 있습니다. ### 정적 도구 필터링 -[`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 @@ -259,12 +253,11 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names`와 `blocked_tool_names`가 모두 제공된 경우 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. +`allowed_tool_names` 와 `blocked_tool_names` 가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. ### 동적 도구 필터링 -더 정교한 로직이 필요하면 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 입력으로 받는 callable을 전달하세요. callable은 -동기 또는 비동기로 구현할 수 있으며, 도구를 노출해야 할 때 `True`를 반환합니다. +보다 정교한 로직이 필요하다면 [`ToolFilterContext`][agents.mcp.ToolFilterContext] 를 받는 호출 가능 객체를 전달하세요. 이 호출 가능 객체는 동기 또는 비동기일 수 있으며, 도구를 노출해야 할 때 `True` 를 반환합니다. ```python from pathlib import Path @@ -288,15 +281,14 @@ async with MCPServerStdio( ... ``` -필터 컨텍스트는 활성 `run_context`, 도구를 요청한 `agent`, 그리고 `server_name`을 제공합니다. +필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, 그리고 `server_name` 을 제공합니다. ## 프롬프트 -MCP 서버는 에이전트 instructions를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 다음 두 가지 -메서드를 노출합니다: +MCP 서버는 에이전트 instructions 를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 메서드를 노출합니다: -- `list_prompts()`는 사용 가능한 프롬프트 템플릿을 열거합니다 -- `get_prompt(name, arguments)`는 선택적 매개변수와 함께 구체적인 프롬프트를 가져옵니다 +- `list_prompts()` 는 사용 가능한 프롬프트 템플릿을 열거합니다 +- `get_prompt(name, arguments)` 는 필요 시 매개변수와 함께 구체적인 프롬프트를 가져옵니다 ```python from agents import Agent @@ -316,20 +308,19 @@ agent = Agent( ## 캐싱 -모든 에이전트 실행은 각 MCP 서버에서 `list_tools()`를 호출합니다. 원격 서버는 눈에 띄는 지연을 초래할 수 있으므로, 모든 MCP -서버 클래스는 `cache_tools_list` 옵션을 제공합니다. 도구 정의가 자주 변경되지 않는다고 확신할 때에만 `True`로 설정하세요. 나중에 새 목록을 강제로 가져오려면 서버 인스턴스에서 `invalidate_tools_cache()`를 호출하세요. +모든 에이전트 실행은 각 MCP 서버에서 `list_tools()` 를 호출합니다. 원격 서버는 눈에 띄는 지연을 초래할 수 있으므로, 모든 MCP 서버 클래스는 `cache_tools_list` 옵션을 노출합니다. 도구 정의가 자주 변경되지 않는다고 확신할 때만 `True` 로 설정하세요. 나중에 새 목록을 강제하려면 서버 인스턴스에서 `invalidate_tools_cache()` 를 호출하세요. ## 트레이싱 -[트레이싱](./tracing.md)은 다음을 포함해 MCP 활동을 자동으로 캡처합니다: +[트레이싱](./tracing.md)은 MCP 활동을 자동으로 캡처합니다. 다음이 포함됩니다: -1. MCP 서버에 대한 도구 목록 호출 -2. 도구 호출의 MCP 관련 정보 +1. 도구를 나열하기 위한 MCP 서버 호출 +2. 도구 호출에 관한 MCP 관련 정보 -![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) +![MCP 트레이싱 스크린샷](../assets/images/mcp-tracing.jpg) ## 추가 자료 -- [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 diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md index f0a78721e..4cce5ede8 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)를 사용하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] +- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] ## OpenAI 모델 -`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)이며, 에이전트 워크플로에서 예측 가능성과 낮은 지연 시간의 균형이 좋습니다. +`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)이며, 에이전트 워크플로에 적합한 예측 가능성과 낮은 지연 시간의 균형을 제공합니다. [`gpt-5`](https://platform.openai.com/docs/models/gpt-5) 같은 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요. ### 기본 OpenAI 모델 -사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +사용자가 사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 일관되게 특정 모델을 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 모델 -이 방식으로 GPT-5의 reasoning 모델([`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano))을 사용할 때, SDK 는 합리적인 `ModelSettings`를 기본으로 적용합니다. 구체적으로 `reasoning.effort`와 `verbosity`를 모두 `"low"`로 설정합니다. 이러한 설정을 직접 구성하려면 `agents.models.get_default_model_settings("gpt-5")`를 호출하세요. +GPT-5 의 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")` 를 호출하세요. -더 낮은 지연 시간이나 특정 요구 사항이 있다면 다른 모델과 설정을 선택할 수 있습니다. 기본 모델의 reasoning effort 를 조정하려면 사용자 지정 `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"` reasoning effort 를 지원하지 않으므로, 이 Agents SDK 의 기본값은 `"low"`입니다. +특히 지연 시간을 줄이기 위해 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 또는 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 모델을 `reasoning.effort="minimal"` 로 사용하면 기본 설정보다 더 빠르게 응답을 반환하는 경우가 많습니다. 다만 Responses API 의 일부 내장 도구(예: 파일 검색 및 이미지 생성)는 `"minimal"` reasoning effort 를 지원하지 않으므로, 본 Agents SDK 의 기본값은 `"low"` 입니다. -#### 비 GPT-5 모델 +#### GPT-5가 아닌 모델 -사용자 지정 `model_settings` 없이 GPT-5가 아닌 모델 이름을 전달하면, SDK 는 모든 모델과 호환되는 일반적인 `ModelSettings`로 되돌립니다. +사용자 지정 `model_settings` 없이 GPT-5가 아닌 모델 이름을 전달하면, SDK 는 모든 모델과 호환되는 일반적인 `ModelSettings` 로 되돌립니다. ## 비 OpenAI 모델 -[LiteLLM 통합](../litellm.md)을 통해 대부분의 비 OpenAI 모델을 사용할 수 있습니다. 먼저 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` 수준에서 적용됩니다. 이를 통해 “이 실행(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]를 전달 +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 @@ -122,10 +122,10 @@ async def main(): print(result.final_output) ``` -1. OpenAI 모델의 이름을 직접 설정 -2. [`Model`][agents.models.interface.Model] 구현을 제공 +1. OpenAI 모델의 이름을 직접 설정합니다 +2. [`Model`][agents.models.interface.Model] 구현을 제공합니다 -에이전트에 사용하는 모델을 더 자세히 구성하려면, temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다. +에이전트에 사용되는 모델을 더 세밀하게 구성하려면, temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings] 를 전달할 수 있습니다. ```python from agents import Agent, ModelSettings @@ -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 +### 트레이싱 클라이언트 오류 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 문서](../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](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`를 보내지 않기 -- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력 필터링 -- structured JSON 출력을 지원하지 않는 제공자는 가끔 잘못된 JSON을 생성할 수 있음을 인지하기 \ No newline at end of file +- 지원하지 않는 제공자에게 해당 `tools` 를 보내지 말 것 +- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링할 것 +- structured JSON 출력을 지원하지 않는 제공자는 때때로 잘못된 JSON 을 생성할 수 있음을 인지할 것 \ No newline at end of file diff --git a/docs/ko/models/litellm.md b/docs/ko/models/litellm.md index 35b0ef00f..eb5e21117 100644 --- a/docs/ko/models/litellm.md +++ b/docs/ko/models/litellm.md @@ -2,33 +2,33 @@ search: exclude: true --- -# LiteLLM 를 통한 모든 모델 사용 +# LiteLLM 를 통한 임의 모델 사용 !!! note - LiteLLM 통합은 베타 단계입니다. 특히 규모가 작은 일부 모델 제공업체에서 문제가 발생할 수 있습니다. 문제가 있으면 [GitHub 이슈](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 에서 어떤 AI 모델이든 사용할 수 있도록 LiteLLM 통합을 추가했습니다. ## 설정 -`litellm`이 사용 가능한지 확인해야 합니다. 선택적 `litellm` 의존성 그룹을 설치해 사용할 수 있습니다: +`litellm` 이 사용 가능해야 합니다. 선택적 `litellm` 종속성 그룹을 설치하면 됩니다: ```bash pip install "openai-agents[litellm]" ``` -설치가 끝나면, 어떤 에이전트에서든 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 사용할 수 있습니다. +설치가 완료되면 어떤 에이전트에서든 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 을 사용할 수 있습니다. ## 예제 -완전히 동작하는 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 프롬프트가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: +다음은 완전한 동작 예제입니다. 실행하면 모델 이름과 API 키를 입력하라는 프롬프트가 표시됩니다. 예를 들어 다음과 같이 입력할 수 있습니다: -- `openai/gpt-4.1` 는 모델, OpenAI API 키는 본인 키 -- `anthropic/claude-3-5-sonnet-20240620` 는 모델, Anthropic API 키는 본인 키 -- 등 +- 모델에는 `openai/gpt-4.1`, 그리고 OpenAI API 키 +- 모델에는 `anthropic/claude-3-5-sonnet-20240620`, 그리고 Anthropic API 키 +- 등등 -LiteLLM 에서 지원하는 전체 모델 목록은 [litellm providers docs](https://docs.litellm.ai/docs/providers)를 참조하세요. +LiteLLM 에서 지원하는 전체 모델 목록은 [litellm providers 문서](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 0fc83311e..1e7d398ac 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 기반 오케스트레이션 -에이전트는 instructions, tools, 핸드오프로 장비된 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`와 같은 파이썬 기본 컴포넌트를 통해 여러 에이전트를 병렬로 실행합니다. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용합니다. +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 점검 가능한 적절한 형식의 데이터를 생성하기. 예를 들어, 에이전트에게 작업을 몇 가지 카테고리로 분류하게 하고, 그 카테고리에 따라 다음 에이전트를 선택할 수 있습니다 +- 하나의 에이전트 출력을 다음 에이전트 입력으로 변환해 여러 에이전트를 체이닝하기. 예를 들어 블로그 글쓰기를 리서치, 아웃라인 작성, 본문 작성, 비판, 개선의 일련의 단계로 분해할 수 있습니다 +- 특정 기준을 통과했다고 평가자가 말할 때까지, 작업을 수행하는 에이전트와 평가·피드백을 제공하는 에이전트를 `while` 루프에서 함께 실행하기 +- 여러 에이전트를 병렬로 실행하기. 예: `asyncio.gather` 같은 파이썬의 기본 컴포넌트를 통해 서로 독립적인 여러 작업을 더 빠르게 처리할 수 있습니다 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 code examples가 있습니다. \ No newline at end of file +[`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 f26647c56..12e00b4b5 100644 --- a/docs/ko/quickstart.md +++ b/docs/ko/quickstart.md @@ -2,11 +2,11 @@ search: exclude: true --- -# 퀵스타트 +# 빠른 시작 -## 프로젝트 및 가상 환경 생성 +## 프로젝트와 가상 환경 생성 -한 번만 하면 됩니다. +이 작업은 한 번만 수행하면 됩니다. ```bash mkdir my_project @@ -30,15 +30,15 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API 키 설정 -없다면 OpenAI API 키를 만들기 위해 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따르세요. +아직 없다면, OpenAI API 키를 생성하려면 [이 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)를 따라 주세요. ```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 @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## 핸드오프 정의 -각 에이전트에서, 에이전트가 자신의 작업을 어떻게 진행할지 결정하기 위해 선택할 수 있는 나가는 핸드오프 옵션 목록을 정의할 수 있습니다. +각 에이전트에서, 해당 에이전트가 자신의 작업을 진전시키기 위해 선택할 수 있는 아웃바운드 핸드오프 옵션 목록을 정의할 수 있습니다. ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## 에이전트 오케스트레이션 실행 -워크플로가 실행되고 분류(triage) 에이전트가 두 전문 에이전트 사이를 올바르게 라우팅하는지 확인해봅시다. +워크플로가 실행되고 트리아지 에이전트가 두 전문 에이전트 사이를 올바르게 라우팅하는지 확인해 봅시다. ```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)로 이동해 에이전트 실행의 트레이스를 확인하세요. ## 다음 단계 -더 복잡한 에이전트형 플로우 만드는 방법: +더 복잡한 에이전트형 플로우를 만드는 방법을 살펴보세요: -- [에이전트](agents.md) 구성 방법 알아보기. -- [에이전트 실행](running_agents.md) 알아보기. -- [도구](tools.md), [가드레일](guardrails.md), [모델](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 3e12d3625..f3635bc19 100644 --- a/docs/ko/realtime/guide.md +++ b/docs/ko/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # 가이드 -이 가이드는 OpenAI Agents SDK의 실시간 기능을 사용하여 음성 기반 AI 에이전트를 구축하는 방법을 자세히 설명합니다. +이 가이드는 OpenAI Agents SDK의 실시간 기능을 사용하여 음성 지원 AI 에이전트를 구축하는 방법을 심층적으로 설명합니다. -!!! warning "Beta feature" -실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 호환성 파괴 변경이 있을 수 있습니다. +!!! warning "베타 기능" +실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 하위 호환이 깨지는 변경이 있을 수 있습니다. ## 개요 -실시간 에이전트는 오디오와 텍스트 입력을 실시간으로 처리하고 실시간 오디오로 응답하는 대화형 흐름을 제공합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 지연이 낮고 인터럽션(중단 처리)을 우아하게 처리하는 자연스러운 음성 대화를 가능하게 합니다. +실시간 에이전트는 대화형 플로우를 가능하게 하며, 오디오와 텍스트 입력을 실시간으로 처리하고 실시간 오디오로 응답합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 낮은 지연으로 자연스러운 음성 대화를 제공하고, 인터럽션(중단 처리)을 우아하게 처리할 수 있습니다. ## 아키텍처 -### 핵심 구성 요소 +### 핵심 구성요소 -실시간 시스템은 다음과 같은 핵심 구성 요소로 이루어져 있습니다: +실시간 시스템은 다음과 같은 핵심 구성요소로 이루어져 있습니다: -- **RealtimeAgent**: instructions, tools, handoffs로 구성된 에이전트 -- **RealtimeRunner**: 구성을 관리합니다. `runner.run()`을 호출하여 세션을 얻을 수 있습니다. -- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 생성하고 대화가 끝날 때까지 유지합니다. +- **RealtimeAgent**: instructions, tools 및 핸드오프로 구성된 에이전트 +- **RealtimeRunner**: 구성을 관리합니다. `runner.run()`을 호출해 세션을 얻을 수 있습니다. +- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 만들고, 대화가 끝날 때까지 유지합니다. - **RealtimeModel**: 기본 모델 인터페이스(일반적으로 OpenAI의 WebSocket 구현) ### 세션 흐름 -일반적인 실시간 세션 흐름은 다음과 같습니다: +일반적인 실시간 세션은 다음 흐름을 따릅니다: -1. **RealtimeAgent 생성**: instructions, tools, handoffs를 설정합니다 -2. **RealtimeRunner 설정**: 에이전트와 구성 옵션을 등록합니다 -3. **세션 시작**: `await runner.run()`을 사용하여 RealtimeSession을 반환받습니다 -4. **오디오 또는 텍스트 전송**: `send_audio()` 또는 `send_message()`로 세션에 보냅니다 -5. **이벤트 수신**: 세션을 이터레이션하여 오디오 출력, 전사, 도구 호출, 핸드오프, 오류 등의 이벤트를 수신합니다 -6. **인터럽션 처리**: 사용자가 에이전트 말 중에 말하면 현재 오디오 생성을 자동으로 중지합니다 +1. instructions, tools 및 핸드오프로 **RealtimeAgent(들)를 생성**합니다. +2. 에이전트와 구성 옵션으로 **RealtimeRunner를 설정**합니다 +3. `await runner.run()`을 사용해 **세션을 시작**하고 RealtimeSession을 반환받습니다. +4. `send_audio()` 또는 `send_message()`를 사용해 **오디오 또는 텍스트 메시지 전송**합니다 +5. 세션을 순회(iterate)하여 **이벤트를 수신**합니다 - 이벤트에는 오디오 출력, 전사, 도구 호출, 핸드오프, 오류가 포함됩니다 +6. 사용자가 에이전트 말 위로 말할 때 **인터럽션 처리**를 수행합니다. 이는 현재 오디오 생성을 자동으로 중지합니다 -세션은 대화 기록을 유지하고 실시간 모델과의 지속적인 연결을 관리합니다. +세션은 대화 기록을 유지하고 실시간 모델과의 지속 연결을 관리합니다. ## 에이전트 구성 -RealtimeAgent는 일반 Agent 클래스와 유사하게 동작하나 몇 가지 차이점이 있습니다. 전체 API 세부 정보는 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 레퍼런스를 참조하세요. +RealtimeAgent는 일반 Agent 클래스와 유사하게 동작하지만 몇 가지 핵심 차이가 있습니다. 전체 API 세부 사항은 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 레퍼런스를 참고하세요. 일반 에이전트와의 주요 차이점: -- 모델 선택은 에이전트 레벨이 아닌 세션 레벨에서 구성합니다 -- structured outputs 미지원(`outputType` 미지원) -- 음성(voice)은 에이전트별로 구성할 수 있지만 첫 번째 에이전트가 말을 시작한 후에는 변경할 수 없습니다 -- tools, handoffs, instructions 등 기타 기능은 동일하게 작동합니다 +- 모델 선택은 에이전트 단위가 아닌 세션 단위로 구성됩니다. +- structured output 지원이 없습니다(`outputType`은 지원되지 않음). +- 음성(voice)은 에이전트별로 구성할 수 있지만 첫 번째 에이전트가 말하기 시작한 후에는 변경할 수 없습니다. +- 그 외 tools, 핸드오프, instructions 등은 동일하게 동작합니다. ## 세션 구성 ### 모델 설정 -세션 구성으로 기본 실시간 모델 동작을 제어할 수 있습니다. 모델 이름(예: `gpt-realtime`), 음성 선택(alloy, echo, fable, onyx, nova, shimmer), 지원 모달리티(텍스트 및/또는 오디오)를 구성할 수 있습니다. 오디오 형식은 입력과 출력 모두에 대해 설정할 수 있으며 기본값은 PCM16입니다. +세션 구성은 기본 실시간 모델의 동작을 제어할 수 있도록 해줍니다. 모델 이름(예: `gpt-realtime`), 음성 선택(alloy, echo, fable, onyx, nova, shimmer), 지원 모달리티(텍스트 및/또는 오디오)를 구성할 수 있습니다. 오디오 포맷은 입력과 출력 모두에 대해 설정할 수 있으며 기본값은 PCM16입니다. ### 오디오 구성 -오디오 설정은 세션이 음성 입력과 출력을 처리하는 방식을 제어합니다. Whisper와 같은 모델을 사용하여 입력 오디오 전사를 구성하고, 언어 기본값을 설정하며, 도메인 특화 용어의 정확도를 높이기 위한 전사 프롬프트를 제공할 수 있습니다. 턴 감지 설정은 에이전트가 언제 응답을 시작하고 멈춰야 하는지 제어하며, 음성 활동 감지 임계값, 무음 지속 시간, 감지된 음성 주변 패딩 옵션을 제공합니다. +오디오 설정은 세션이 음성 입력과 출력을 처리하는 방식을 제어합니다. Whisper와 같은 모델을 사용한 입력 오디오 전사, 언어 설정, 도메인 특화 용어의 정확도를 높이기 위한 전사 프롬프트를 구성할 수 있습니다. 턴 감지 설정은 에이전트가 언제 응답을 시작하고 멈춰야 하는지 제어하며, 음성 활동 감지 임계값, 무음 지속 시간, 감지된 음성 주변 패딩과 같은 옵션을 제공합니다. ## 도구와 함수 ### 도구 추가 -일반 에이전트와 마찬가지로 실시간 에이전트도 대화 중에 실행되는 함수 도구를 지원합니다: +일반 에이전트와 마찬가지로 실시간 에이전트는 대화 중 실행되는 함수 도구를 지원합니다: ```python from agents import function_tool @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### 핸드오프 생성 -핸드오프를 사용하면 특화된 에이전트 간에 대화를 전환할 수 있습니다. +핸드오프는 특화된 에이전트 간에 대화를 전환할 수 있게 해줍니다. ```python from agents.realtime import realtime_handoff @@ -119,20 +119,20 @@ main_agent = RealtimeAgent( ## 이벤트 처리 -세션은 세션 객체를 이터레이션하여 수신할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작 및 종료, 에이전트 핸드오프, 오류가 포함됩니다. 주요 이벤트는 다음과 같습니다: +세션은 세션 객체를 순회하여 수신할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작 및 종료, 에이전트 핸드오프, 오류가 포함됩니다. 처리해야 할 주요 이벤트는 다음과 같습니다: - **audio**: 에이전트 응답의 원문 오디오 데이터 -- **audio_end**: 에이전트 발화 종료 +- **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,25 +152,25 @@ 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` 이벤트를 반드시 수신하세요. -## 모델 직접 접근 +## 모델 직접 액세스 -기본 모델에 접근하여 커스텀 리스너를 추가하거나 고급 작업을 수행할 수 있습니다: +다음과 같이 기본 모델에 액세스하여 커스텀 리스너를 추가하거나 고급 작업을 수행할 수 있습니다: ```python # Add a custom listener to the model session.model.add_listener(my_custom_listener) ``` -이는 연결에 대한 더 낮은 수준의 제어가 필요한 고급 사용 사례를 위해 [`RealtimeModel`][agents.realtime.model.RealtimeModel] 인터페이스에 직접 접근할 수 있게 해줍니다. +이는 연결에 대한 더 낮은 수준의 제어가 필요한 고급 사용 사례를 위해 [`RealtimeModel`][agents.realtime.model.RealtimeModel] 인터페이스에 직접 액세스할 수 있게 해줍니다. ## 코드 예제 -완전한 동작 예시는 UI 구성 요소 포함/미포함 데모가 있는 [examples/realtime 디렉터리](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)를 참고하세요. \ No newline at end of file +완전한 동작 code examples는 [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 1b865684d..cba0c3089 100644 --- a/docs/ko/realtime/quickstart.md +++ b/docs/ko/realtime/quickstart.md @@ -4,16 +4,16 @@ search: --- # 빠른 시작 -Realtime agents는 OpenAI의 Realtime API를 사용하여 AI 에이전트와 음성 대화를 가능하게 합니다. 이 가이드는 첫 번째 realtime 음성 에이전트를 만드는 과정을 안내합니다. +실시간 에이전트를 사용하면 OpenAI의 Realtime API로 AI 에이전트와 음성 대화를 할 수 있습니다. 이 가이드는 첫 번째 실시간 음성 에이전트를 만드는 과정을 안내합니다. !!! warning "베타 기능" -Realtime agents는 베타 단계입니다. 구현이 개선되는 동안 변경 사항이 발생할 수 있습니다. +실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 호환성에 영향을 주는 변경이 있을 수 있습니다. -## 사전 준비 +## 사전 준비 사항 -- Python 3.9 이상 -- OpenAI API 키 -- OpenAI Agents SDK에 대한 기본 지식 +- Python 3.9 이상 +- OpenAI API 키 +- OpenAI Agents SDK에 대한 기본적인 이해 ## 설치 @@ -23,16 +23,16 @@ Realtime agents는 베타 단계입니다. 구현이 개선되는 동안 변경 pip install openai-agents ``` -## 첫 번째 realtime 에이전트 만들기 +## 첫 번째 실시간 에이전트 만들기 -### 1. 필요한 구성 요소 가져오기 +### 1. 필요한 구성요소 임포트 ```python import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. realtime 에이전트 생성 +### 2. 실시간 에이전트 생성 ```python agent = RealtimeAgent( @@ -192,30 +192,30 @@ if __name__ == "__main__": ### 모델 설정 -- `model_name`: 사용 가능한 realtime 모델 중 선택 (예: `gpt-realtime`) -- `voice`: 음성 선택 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: 텍스트 또는 오디오 활성화 (`["text"]` 또는 `["audio"]`) +- `model_name`: 사용 가능한 실시간 모델에서 선택 (예: `gpt-realtime`) +- `voice`: 음성 선택 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) +- `modalities`: 텍스트 또는 오디오 활성화 (`["text"]` 또는 `["audio"]`) ### 오디오 설정 -- `input_audio_format`: 입력 오디오 형식 (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 출력 오디오 형식 -- `input_audio_transcription`: 전사 설정 +- `input_audio_format`: 입력 오디오 형식 (`pcm16`, `g711_ulaw`, `g711_alaw`) +- `output_audio_format`: 출력 오디오 형식 +- `input_audio_transcription`: 음성 인식 구성 ### 턴 감지 -- `type`: 감지 방식 (`server_vad`, `semantic_vad`) -- `threshold`: 음성 활동 임계값 (0.0-1.0) -- `silence_duration_ms`: 턴 종료를 감지할 무음 지속 시간 -- `prefix_padding_ms`: 발화 전 오디오 패딩 +- `type`: 감지 방식 (`server_vad`, `semantic_vad`) +- `threshold`: 음성 활동 임계값 (0.0-1.0) +- `silence_duration_ms`: 턴 종료를 감지할 정적 시간 +- `prefix_padding_ms`: 발화 전 오디오 패딩 ## 다음 단계 -- [realtime agents에 대해 더 알아보기](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 확인 +- 에이전트에 도구 추가 +- 에이전트 간 핸드오프 구현 +- 안전을 위한 가드레일 설정 ## 인증 diff --git a/docs/ko/release.md b/docs/ko/release.md index c71a1c100..4a9d14485 100644 --- a/docs/ko/release.md +++ b/docs/ko/release.md @@ -4,29 +4,29 @@ search: --- # 릴리스 프로세스/변경 로그 -프로젝트는 `0.Y.Z` 형식의 약간 수정된 시맨틱 버전 규칙을 따릅니다. 선행하는 `0`은 SDK가 여전히 빠르게 발전하고 있음을 나타냅니다. 각 구성 요소는 다음과 같이 증가시킵니다: +이 프로젝트는 `0.Y.Z` 형식의 약간 수정된 시맨틱 버전 관리를 따릅니다. 앞의 `0`은 SDK가 여전히 빠르게 발전 중임을 의미합니다. 각 구성 요소의 증분 규칙은 다음과 같습니다: -## 마이너 (`Y`) 버전 +## 마이너(`Y`) 버전 -베타로 표시되지 않은 모든 퍼블릭 인터페이스에 **브레이킹 변경**이 있을 때 마이너 버전 `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.2.0 -이 버전에서는 이전에 인수로 `Agent`를 받던 몇몇 위치가 이제 `AgentBase`를 인수로 받습니다. 예: MCP 서버의 `list_tools()` 호출. 이는 순수하게 타입 관련 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트를 위해서는 `Agent`를 `AgentBase`로 바꿔 타입 오류만 수정하면 됩니다. +이 버전에서는 이전에 `Agent`를 인자(arg)로 받던 몇몇 위치가 이제 `AgentBase`를 인자(arg)로 받습니다. 예: 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`라는 두 개의 새 params가 추가되었습니다. `MCPServer`를 상속하는 모든 클래스에 이 params를 추가해야 합니다. \ No newline at end of file diff --git a/docs/ko/repl.md b/docs/ko/repl.md index bd302a9d5..45bd48ac2 100644 --- a/docs/ko/repl.md +++ b/docs/ko/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/ko/results.md b/docs/ko/results.md index 6f8d74252..67c5f8b3a 100644 --- a/docs/ko/results.md +++ b/docs/ko/results.md @@ -6,51 +6,51 @@ search: `Runner.run` 메서드를 호출하면 다음 중 하나를 받습니다: -- [`RunResult`][agents.result.RunResult] (`run` 또는 `run_sync` 호출 시) -- [`RunResultStreaming`][agents.result.RunResultStreaming] (`run_streamed` 호출 시) +- `run` 또는 `run_sync`를 호출한 경우 [`RunResult`][agents.result.RunResult] +- `run_streamed`를 호출한 경우 [`RunResultStreaming`][agents.result.RunResultStreaming] -이 둘은 모두 [`RunResultBase`][agents.result.RunResultBase] 를 상속하며, 대부분의 유용한 정보가 여기에 있습니다. +이 두 가지는 모두 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, 대부분의 유용한 정보가 여기에 포함됩니다. ## 최종 출력 -[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이는 다음 중 하나입니다: +[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이는 다음 중 하나입니다: -- 마지막 에이전트에 `output_type` 이 정의되어 있지 않으면 `str` -- 에이전트에 출력 타입이 정의되어 있으면 `last_agent.output_type` 타입의 객체 +- 마지막 에이전트에 `output_type`이 정의되어 있지 않은 경우 `str` +- 에이전트에 출력 타입이 정의되어 있는 경우 `last_agent.output_type` 타입의 객체 !!! note - `final_output` 의 타입은 `Any` 입니다. 핸드오프 때문에 이를 정적으로 타입 지정할 수 없습니다. 핸드오프가 발생하면 어떤 에이전트든 마지막 에이전트가 될 수 있으므로, 가능한 출력 타입 집합을 정적으로 알 수 없습니다. + `final_output`의 타입은 `Any`입니다. 핸드오프 때문에 정적으로 타입을 지정할 수 없습니다. 핸드오프가 발생하면 어떤 에이전트든 마지막 에이전트가 될 수 있으므로, 가능한 출력 타입의 집합을 정적으로 알 수 없습니다. -## 다음 턴 입력 +## 다음 턴을 위한 입력 -[`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/ko/running_agents.md b/docs/ko/running_agents.md index 4447fb1dc..bb9053121 100644 --- a/docs/ko/running_agents.md +++ b/docs/ko/running_agents.md @@ -4,11 +4,11 @@ search: --- # 에이전트 실행 -에이전트는 [`Runner`][agents.run.Runner] 클래스를 통해 실행할 수 있습니다. 다음 세 가지 옵션이 있습니다: +[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 선택지는 다음과 같습니다: -1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult]를 반환합니다 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드로, 내부적으로 `.run()`을 실행합니다 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming]을 반환합니다. LLM을 스트리밍 모드로 호출하고, 수신되는 대로 이벤트를 스트리밍합니다 +1. [`Runner.run()`][agents.run.Runner.run]: 비동기 실행이며 [`RunResult`][agents.result.RunResult] 를 반환 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드로 내부적으로 `.run()` 을 실행 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기 실행이며 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환. LLM 을 스트리밍 모드로 호출하고, 수신되는 이벤트를 실시간으로 스트리밍 ```python from agents import Agent, Runner @@ -23,20 +23,20 @@ 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이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 이어 붙인 다음 루프를 다시 실행합니다 -3. 전달된 `max_turns`를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생시킵니다 +1. 현재 에이전트와 현재 입력으로 LLM 을 호출 +2. LLM 이 출력 생성 + 1. LLM 이 `final_output` 을 반환하면 루프를 종료하고 결과 반환 + 2. LLM 이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프 재실행 + 3. LLM 이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프 재실행 +3. 전달된 `max_turns` 를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생 !!! note @@ -44,34 +44,34 @@ async def main(): ## 스트리밍 -스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 수신할 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에 실행에 대한 전체 정보가 포함되며, 생성된 모든 새 출력도 포함됩니다. 스트리밍 이벤트는 `.stream_events()`를 호출하면 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요. +스트리밍을 사용하면 LLM 이 실행되는 동안 스트리밍 이벤트를 추가로 수신할 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming] 에는 실행에 대한 모든 정보와 새로 생성된 출력이 포함됩니다. 스트리밍 이벤트는 `.stream_events()` 로 호출할 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요. ## 실행 구성 -`run_config` 매개변수는 에이전트 실행에 대한 전역 설정을 구성할 수 있도록 해줍니다: +`run_config` 매개변수로 에이전트 실행의 전역 설정을 구성할 수 있습니다: -- [`model`][agents.run.RunConfig.model]: 각 Agent의 `model` 설정과 관계없이 사용할 전역 LLM 모델을 설정합니다 -- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회를 위한 모델 제공자이며 기본값은 OpenAI입니다 -- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예를 들어 전역 `temperature` 또는 `top_p`를 설정할 수 있습니다 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록입니다 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 지정된 것이 없을 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트에 전달되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고하세요 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md)을 비활성화합니다 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM 및 도구 호출의 입력/출력 등 잠재적으로 민감한 데이터가 트레이스에 포함될지 여부를 설정합니다 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행에 대한 트레이싱 워크플로 이름, 트레이스 ID, 트레이스 그룹 ID를 설정합니다. 최소한 `workflow_name` 설정을 권장합니다. 그룹 ID는 여러 실행에 걸쳐 트레이스를 연결할 수 있는 선택적 필드입니다 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터입니다 +- [`model`][agents.run.RunConfig.model]: 각 Agent 의 `model` 설정과 무관하게 사용할 전역 LLM 모델을 설정 +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회를 위한 모델 제공자, 기본값은 OpenAI +- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의. 예를 들어 전역 `temperature` 또는 `top_p` 를 설정 가능 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 대한 전역 입력 필터. 해당 핸드오프에 이미 필터가 없을 때 적용. 입력 필터를 통해 새 에이전트로 전송되는 입력을 편집할 수 있음. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md) 비활성화 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM 및 도구 호출의 입력/출력 등 민감할 수 있는 데이터를 트레이스에 포함할지 여부를 구성 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, 트레이스 ID, 트레이스 그룹 ID 설정. 최소한 `workflow_name` 설정을 권장. 그룹 ID 는 선택 사항으로 여러 실행에 걸쳐 트레이스를 연결 가능 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터 ## 대화/채팅 스레드 -어떤 run 메서드를 호출하더라도 하나 이상의 에이전트가 실행될 수 있으며(따라서 하나 이상의 LLM 호출이 발생), 이는 채팅 대화에서 하나의 논리적 턴을 의미합니다. 예를 들어: +어떤 run 메서드를 호출하든 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출), 이는 채팅 대화에서 하나의 논리적 턴을 의미합니다. 예: -1. 사용자 턴: 사용자가 텍스트를 입력 -2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고 도구를 실행한 뒤 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 추가 도구를 실행한 다음 출력을 생성 +1. 사용자 턴: 사용자가 텍스트 입력 +2. Runner 실행: 첫 번째 에이전트가 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(): @@ -91,9 +91,9 @@ async def main(): # California ``` -### Sessions를 통한 자동 대화 관리 +### Sessions 를 통한 자동 대화 관리 -더 간단한 접근이 필요하다면 [Sessions](sessions.md)를 사용하여 `.to_input_list()`를 수동으로 호출하지 않고도 대화 기록을 자동으로 처리할 수 있습니다: +더 간단한 방법으로는 [Sessions](sessions.md) 를 사용하여 `.to_input_list()` 를 직접 호출하지 않고도 대화 내역을 자동으로 처리할 수 있습니다: ```python from agents import Agent, Runner, SQLiteSession @@ -117,24 +117,24 @@ async def main(): # California ``` -Sessions는 자동으로 다음을 수행합니다: +Sessions 는 자동으로 다음을 수행합니다: -- 각 실행 전에 대화 기록을 가져옴 +- 각 실행 전에 대화 내역을 가져옴 - 각 실행 후 새 메시지를 저장 -- 서로 다른 세션 ID에 대해 별도의 대화를 유지 +- 다른 세션 ID 별로 개별 대화를 유지 자세한 내용은 [Sessions 문서](sessions.md)를 참고하세요. -### 서버 관리형 대화 +### 서버 관리 대화 -`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신 OpenAI 대화 상태 기능에 대화 상태 관리를 서버 측으로 맡길 수도 있습니다. 이를 통해 과거 모든 메시지를 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참고하세요. +`to_input_list()` 또는 `Sessions` 로 로컬에서 처리하는 대신 OpenAI 의 conversation state 기능을 사용해 서버 측에서 대화 상태를 관리할 수도 있습니다. 이를 통해 과거 메시지를 모두 수동으로 재전송하지 않고도 대화 내역을 보존할 수 있습니다. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참고하세요. -OpenAI는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다: +OpenAI 는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다: #### 1. `conversation_id` 사용 -먼저 OpenAI Conversations API를 사용해 대화를 생성한 후 이후 모든 호출에 해당 ID를 재사용합니다: +먼저 OpenAI Conversations API 를 사용해 대화를 생성한 뒤, 이후의 모든 호출에서 해당 ID 를 재사용합니다: ```python from agents import Agent, Runner @@ -166,7 +166,7 @@ async def main(): #### 2. `previous_response_id` 사용 -또 다른 옵션은 **response chaining**으로, 각 턴이 이전 턴의 response ID에 명시적으로 연결되는 방식입니다. +다른 옵션은 **response chaining** 으로, 각 턴이 이전 턴의 response ID 와 명시적으로 연결됩니다. ```python from agents import Agent, Runner @@ -190,18 +190,18 @@ async def main(): ``` -## 장시간 실행 에이전트 및 휴먼인더루프 (HITL) +## 장기 실행 에이전트 및 휴먼인더루프 (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`][]에 있습니다. 개요는 다음과 같습니다: +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 API 오용으로 인해 발생 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 각각 입력 가드레일 또는 출력 가드레일 조건이 충족될 때 발생. 입력 가드레일은 처리 전에 수신 메시지를 검사하고, 출력 가드레일은 전달 전에 에이전트의 최종 응답을 검사함 \ No newline at end of file diff --git a/docs/ko/sessions.md b/docs/ko/sessions.md index 8a47e7551..cfe574a1a 100644 --- a/docs/ko/sessions.md +++ b/docs/ko/sessions.md @@ -4,9 +4,9 @@ search: --- # 세션 -Agents SDK는 기본 제공 세션 메모리를 통해 여러 에이전트 실행에 걸쳐 대화 이력을 자동으로 유지하므로, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요가 없습니다. +Agents SDK 는 여러 에이전트 실행(run) 간에 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요를 없애줍니다. -세션은 특정 세션의 대화 이력을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있도록 합니다. 이는 에이전트가 이전 상호작용을 기억하기를 원하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다. +세션은 특정 세션에 대한 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있도록 합니다. 특히 에이전트가 이전 상호작용을 기억하길 원하는 채팅 애플리케이션이나 멀티턴 대화에 유용합니다. ## 빠른 시작 @@ -51,17 +51,17 @@ print(result.final_output) # "Approximately 39 million" 세션 메모리가 활성화되면: -1. **각 실행 전**: 러너가 세션의 대화 이력을 자동으로 가져와 입력 아이템 앞에 추가합니다 -2. **각 실행 후**: 실행 중 생성된 모든 새 아이템(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 자동으로 세션에 저장됩니다 -3. **컨텍스트 유지**: 동일한 세션으로 이후 실행할 때 전체 대화 이력이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다 +1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 항목 앞에 추가합니다 +2. **각 실행 후**: 실행 중에 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다 +3. **컨텍스트 유지**: 동일한 세션으로 후속 실행을 수행할 때 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지합니다 -이를 통해 `.to_input_list()`를 수동으로 호출하고 실행 사이의 대화 상태를 관리할 필요가 없어집니다. +이는 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리해야 하는 필요를 제거합니다. ## 메모리 작업 ### 기본 작업 -세션은 대화 이력을 관리하기 위한 여러 작업을 지원합니다: +세션은 대화 기록 관리를 위한 여러 작업을 지원합니다: ```python from agents import SQLiteSession @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 수정을 위한 `pop_item` 사용 +### 수정 시 pop_item 사용 -`pop_item` 메서드는 대화에서 마지막 아이템을 되돌리거나 수정하려는 경우에 특히 유용합니다: +`pop_item` 메서드는 대화에서 마지막 항목을 되돌리거나 수정하려는 경우에 특히 유용합니다: ```python from agents import Agent, Runner, SQLiteSession @@ -128,8 +128,8 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API 메모리 -자체 데이터베이스를 관리하지 않고 -[대화 상태](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api)를 지속하려면 [OpenAI Conversations API](https://platform.openai.com/docs/api-reference/conversations/create)를 사용하세요. 이는 대화 이력 저장에 OpenAI 호스팅 인프라를 이미 활용하는 경우에 유용합니다. +[OpenAI Conversations API](https://platform.openai.com/docs/api-reference/conversations/create)를 사용하여 자체 데이터베이스를 관리하지 않고도 +[conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api)를 지속할 수 있습니다. 이는 대화 기록 저장에 OpenAI 호스트하는 인프라에 이미 의존하고 있을 때 유용합니다. ```python from agents import OpenAIConversationsSession @@ -190,9 +190,9 @@ result2 = await Runner.run( ### SQLAlchemy 기반 세션 -보다 고급 사용 사례에서는 SQLAlchemy 기반 세션 백엔드를 사용할 수 있습니다. 이를 통해 SQLAlchemy가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 세션 저장소로 사용할 수 있습니다. +더 고급 사용 사례의 경우, SQLAlchemy 기반 세션 백엔드를 사용할 수 있습니다. 이를 통해 SQLAlchemy 가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 세션 저장소로 사용할 수 있습니다. -**예제 1: `from_url`을 사용한 인메모리 SQLite** +**예시 1: 인메모리 SQLite 와 `from_url` 사용** 개발 및 테스트에 적합한 가장 간단한 시작 방법입니다. @@ -215,9 +215,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**예제 2: 기존 SQLAlchemy 엔진 사용** +**예시 2: 기존 SQLAlchemy 엔진 사용** -프로덕션 애플리케이션에서는 이미 SQLAlchemy `AsyncEngine` 인스턴스를 보유하고 있을 가능성이 큽니다. 이를 세션에 직접 전달할 수 있습니다. +프로덕션 애플리케이션에서는 SQLAlchemy `AsyncEngine` 인스턴스를 이미 보유하고 있을 가능성이 큽니다. 이를 세션에 직접 전달할 수 있습니다. ```python import asyncio @@ -245,10 +245,61 @@ if __name__ == "__main__": asyncio.run(main()) ``` +### 암호화된 세션 + +보관 중인 대화 데이터의 암호화가 필요한 애플리케이션의 경우, `EncryptedSession` 을 사용하여 투명한 암호화와 자동 TTL 기반 만료로 어떤 세션 백엔드든 감쌀 수 있습니다. 이를 위해서는 `encrypt` extra 가 필요합니다: `pip install openai-agents[encrypt]`. + +`EncryptedSession` 은 세션별 키 파생(HKDF)이 적용된 Fernet 암호화를 사용하며, 오래된 메시지의 자동 만료를 지원합니다. 항목이 TTL을 초과하면 조회 시 조용히 건너뜁니다. + +**예시: SQLAlchemy 세션 데이터 암호화** + +```python +import asyncio +from agents import Agent, Runner +from agents.extensions.memory import EncryptedSession, SQLAlchemySession + +async def main(): + # Create underlying session (works with any SessionABC implementation) + underlying_session = SQLAlchemySession.from_url( + session_id="user-123", + url="postgresql+asyncpg://app:secret@db.example.com/agents", + create_tables=True, + ) + + # Wrap with encryption and TTL-based expiration + session = EncryptedSession( + session_id="user-123", + underlying_session=underlying_session, + encryption_key="your-encryption-key", # Use a secure key from your secrets management + ttl=600, # 10 minutes - items older than this are silently skipped + ) + + agent = Agent("Assistant") + result = await Runner.run(agent, "Hello", session=session) + print(result.final_output) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +**주요 기능:** + +- **투명한 암호화**: 저장 전 모든 세션 항목을 자동으로 암호화하고 조회 시 복호화 +- **세션별 키 파생**: 세션 ID 를 salt 로 사용하는 HKDF 로 고유한 암호화 키 파생 +- **TTL 기반 만료**: 구성 가능한 time-to-live(기본값: 10분)에 따라 오래된 메시지를 자동 만료 +- **유연한 키 입력**: Fernet 키 또는 원문 문자열을 암호화 키로 허용 +- **어떤 세션이든 래핑**: SQLite, SQLAlchemy, 또는 사용자 정의 세션 구현과 동작 + +!!! warning "중요한 보안 참고 사항" + + - 암호화 키는 안전하게 저장하세요(예: 환경 변수, 시크릿 매니저) + - 만료된 토큰은 애플리케이션 서버의 시스템 시계를 기준으로 거부됩니다 - 유효한 토큰이 시계 드리프트로 인해 거부되지 않도록 모든 서버가 NTP 로 시간 동기화되어 있는지 확인하세요 + - 기본 세션은 여전히 암호화된 데이터를 저장하므로 데이터베이스 인프라에 대한 제어권을 유지합니다 + ## 사용자 정의 메모리 구현 -[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 생성하여 자체 세션 메모리를 구현할 수 있습니다: +[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다: ```python from agents.memory.session import SessionABC @@ -293,9 +344,9 @@ result = await Runner.run( ## 세션 관리 -### 세션 ID 명명 +### 세션 ID 네이밍 -대화를 체계적으로 구성하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요: +대화를 체계적으로 정리할 수 있도록 의미 있는 세션 ID 를 사용하세요: - 사용자 기반: `"user_12345"` - 스레드 기반: `"thread_abc123"` @@ -303,11 +354,12 @@ result = await Runner.run( ### 메모리 지속성 -- 임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용 -- 영구 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 -- SQLAlchemy가 지원하는 기존 데이터베이스를 사용하는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True")`) 사용 -- OpenAI Conversations API에 이력을 저장하기를 선호하는 경우 OpenAI 호스팅 스토리지(`OpenAIConversationsSession()`) 사용 -- 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 대한 사용자 정의 세션 백엔드 구현 고려 +- 일시적 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용 +- 지속적 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- SQLAlchemy 가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True")`) 사용 +- 기록을 OpenAI Conversations API 에 저장하길 원할 때는 OpenAI 호스트하는 스토리지(`OpenAIConversationsSession()`) 사용 +- 투명한 암호화와 TTL 기반 만료로 어떤 세션이든 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key")`) 사용 +- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 대한 사용자 정의 세션 백엔드 구현을 고려 ### 세션 관리 @@ -333,9 +385,9 @@ result2 = await Runner.run( ) ``` -## 전체 예제 +## 전체 예시 -다음은 세션 메모리가 실제로 작동하는 전체 예제입니다: +다음은 세션 메모리가 실제로 동작하는 전체 예시입니다: ```python import asyncio @@ -404,4 +456,5 @@ if __name__ == "__main__": - [`Session`][agents.memory.Session] - 프로토콜 인터페이스 - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 구현 - [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI Conversations API 구현 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 \ No newline at end of file +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - TTL 이 포함된 암호화된 세션 래퍼 \ No newline at end of file diff --git a/docs/ko/streaming.md b/docs/ko/streaming.md index b4c1c05fd..d8bc808c6 100644 --- a/docs/ko/streaming.md +++ b/docs/ko/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` 등)과 데이터로 구성됩니다. 이 이벤트는 생성되는 즉시 사용자에게 응답 메시지를 스트리밍하려는 경우에 유용합니다. -예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다. +예를 들어, 아래 코드는 LLM이 생성한 텍스트를 토큰 단위로 출력합니다. ```python import asyncio @@ -37,9 +37,9 @@ if __name__ == "__main__": ## 실행 항목 이벤트와 에이전트 이벤트 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 상위 수준의 이벤트입니다. 항목이 완전히 생성되었을 때를 알려줍니다. 이를 통해 각 토큰 대신 "메시지 생성 완료", "도구 실행 완료" 등의 수준에서 진행 상황 업데이트를 전달할 수 있습니다. 마찬가지로, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프로 인한 변경) 업데이트를 제공합니다. +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때를 알려 줍니다. 이를 통해 각 토큰 단위가 아닌 "메시지 생성됨", "도구 실행됨" 수준에서 진행 상황을 전달할 수 있습니다. 이와 유사하게, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과로) 업데이트를 제공합니다. -예를 들어, 다음은 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. +예를 들어, 아래 코드는 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. ```python import asyncio diff --git a/docs/ko/tools.md b/docs/ko/tools.md index 3399ce4c2..72fe4ae86 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 함수를 도구로 사용할 수 있게 합니다 -- 도구로서의 에이전트: 에이전트를 도구처럼 사용하여, 핸드오프 없이 에이전트가 다른 에이전트를 호출할 수 있게 합니다 +- 호스티드 툴: LLM 서버에서 AI 모델과 함께 실행됩니다. OpenAI는 리트리벌, 웹 검색 및 컴퓨터 사용을 호스티드 툴로 제공합니다. +- 함수 호출: 임의의 Python 함수를 도구로 사용할 수 있게 합니다. +- 도구로서의 에이전트: 에이전트를 도구로 사용하여 핸드오프 없이 다른 에이전트를 호출할 수 있습니다. ## 호스티드 툴 -OpenAI 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 사용 시 몇 가지 내장 도구를 제공합니다: +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 함수 이름이 됩니다(또는 직접 이름을 제공할 수 있음) +- 도구 이름은 Python 함수명입니다(또는 직접 이름을 지정할 수 있음) - 도구 설명은 함수의 도크스트링에서 가져옵니다(또는 직접 설명을 제공할 수 있음) -- 함수 입력에 대한 스키마는 함수의 인자에서 자동으로 생성됩니다 -- 각 입력의 설명은 비활성화하지 않는 한 함수의 도크스트링에서 가져옵니다 +- 함수 입력의 스키마는 함수의 인자에서 자동으로 생성됩니다 +- 각 입력에 대한 설명은 비활성화하지 않는 한 함수의 도크스트링에서 가져옵니다 -Python 의 `inspect` 모듈로 함수 시그니처를 추출하고, 도크스트링 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/) 를, 스키마 생성에는 `pydantic` 을 사용합니다. +Python의 `inspect` 모듈로 함수 시그니처를 추출하고, 도크스트링 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/), 스키마 생성에는 `pydantic`을 사용합니다. ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 함수의 인자로 임의의 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기로 작성할 수 있습니다 -2. 도크스트링이 있으면 설명과 인자 설명을 캡처하는 데 사용됩니다 -3. 함수는 선택적으로 `context` 를 받을 수 있습니다(반드시 첫 번째 인자). 툴의 이름, 설명, 사용할 도크스트링 스타일 등 오버라이드를 설정할 수도 있습니다 -4. 데코레이터가 적용된 함수를 도구 목록에 전달할 수 있습니다 +1. 함수의 인자로는 어떤 Python 타입이든 사용할 수 있으며, 함수는 동기 또는 비동기로 작성할 수 있습니다. +2. 도크스트링이 있다면 설명과 인자 설명을 추출하는 데 사용됩니다 +3. 선택적으로 `context`를 받을 수 있습니다(첫 번째 인자여야 함). 도구 이름, 설명, 사용할 도크스트링 스타일 등 다양한 override를 설정할 수 있습니다. +4. 데코레이터가 적용된 함수를 도구 목록에 전달할 수 있습니다. -??? note "결과 펼쳐서 보기" +??? note "Expand to see output" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### 사용자 지정 함수 도구 +### 사용자 정의 함수 도구 -때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 직접 [`FunctionTool`][agents.tool.FunctionTool] 을 생성할 수 있습니다. 다음을 제공해야 합니다: +때때로 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 이 경우 직접 [`FunctionTool`][agents.tool.FunctionTool]을 생성할 수 있습니다. 다음을 제공해야 합니다: - `name` - `description` -- `params_json_schema` (인자에 대한 JSON 스키마) -- `on_invoke_tool` (비동기 함수로, [`ToolContext`][agents.tool_context.ToolContext] 와 인자(JSON 문자열)를 받아 도구의 출력 문자열을 반환해야 함) +- 인자에 대한 JSON 스키마인 `params_json_schema` +- [`ToolContext`][agents.tool_context.ToolContext]와 인자를 JSON 문자열로 받아 도구 출력을 문자열로 반환해야 하는 비동기 함수 `on_invoke_tool` ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 인자 및 도크스트링 자동 파싱 -앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자에 대한 설명을 추출하기 위해 도크스트링을 파싱합니다. 참고 사항은 다음과 같습니다: +앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인자에 대한 설명을 추출하기 위해 도크스트링을 파싱합니다. 참고 사항: -1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 인자의 타입을 이해하기 위해 타입 주석을 사용하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 생성합니다. Python 기본형, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다 -2. 도크스트링 파싱에는 `griffe` 를 사용합니다. 지원되는 도크스트링 형식은 `google`, `sphinx`, `numpy` 입니다. 도크스트링 형식은 자동 감지를 시도하지만 최선의 노력일 뿐이므로, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info` 를 `False` 로 설정하면 도크스트링 파싱을 비활성화할 수 있습니다 +1. 시그니처 파싱은 `inspect` 모듈로 수행됩니다. 타입 힌트를 사용해 인자의 타입을 이해하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 구성합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다. +2. 도크스트링 파싱에는 `griffe`를 사용합니다. 지원되는 도크스트링 형식은 `google`, `sphinx`, `numpy`입니다. 도크스트링 형식은 자동 감지를 시도하지만 완벽하지 않을 수 있으므로 `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 도크스트링 파싱을 비활성화할 수도 있습니다. -스키마 추출을 위한 코드는 [`agents.function_schema`][] 에 있습니다. +스키마 추출 코드는 [`agents.function_schema`][]에 있습니다. ## 도구로서의 에이전트 -일부 워크플로에서는 제어권을 넘기지 않고, 중앙 에이전트가 특화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션 하도록 원할 수 있습니다. 에이전트를 도구로 모델링하여 이를 수행할 수 있습니다. +일부 워크플로에서는 제어를 넘기지 않고, 중앙 에이전트가 특화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션하도록 하고 싶을 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다. ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### 도구-에이전트 커스터마이징 +### 툴-에이전트 커스터마이징 -`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환하기 위한 편의 메서드입니다. 그러나 모든 구성을 지원하지는 않습니다. 예를 들어 `max_turns` 를 설정할 수 없습니다. 고급 사용 사례의 경우, 도구 구현 내에서 `Runner.run` 을 직접 사용하세요: +`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환하기 위한 편의 메서드입니다. 그러나 모든 구성을 지원하지는 않습니다. 예를 들어 `max_turns`를 설정할 수 없습니다. 고급 사용 사례에서는 도구 구현에서 직접 `Runner.run`을 사용하세요: ```python @function_tool @@ -288,15 +288,15 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 사용자 지정 출력 추출 +### 커스텀 출력 추출 -특정 상황에서는 중앙 에이전트에 반환하기 전에 도구-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우에 유용합니다: +특정 경우, 중앙 에이전트에 반환하기 전에 툴-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 상황에서 유용합니다: - 하위 에이전트의 대화 기록에서 특정 정보(예: JSON 페이로드)를 추출 -- 에이전트의 최종 답변을 변환하거나 재포맷(예: Markdown 을 일반 텍스트 또는 CSV 로 변환) -- 에이전트의 응답이 누락되었거나 형식이 올바르지 않을 때 출력을 검증하거나 폴백 값을 제공 +- 에이전트의 최종 답변을 변환하거나 재포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환) +- 에이전트의 응답이 없거나 형식이 잘못된 경우 출력을 검증하거나 대체값 제공 -이는 `as_tool` 메서드에 `custom_output_extractor` 인자를 제공하여 수행할 수 있습니다: +`as_tool` 메서드에 `custom_output_extractor` 인자를 제공하여 이를 수행할 수 있습니다: ```python async def extract_json_payload(run_result: RunResult) -> str: @@ -317,7 +317,7 @@ json_tool = data_agent.as_tool( ### 조건부 도구 활성화 -런타임에 `is_enabled` 매개변수를 사용해 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도, 런타임 조건에 따라 LLM 에게 제공되는 도구를 동적으로 필터링할 수 있습니다. +런타임에 `is_enabled` 매개변수를 사용해 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도, 런타임 조건에 따라 LLM에 제공되는 도구를 동적으로 필터링할 수 있습니다. ```python import asyncio @@ -375,23 +375,23 @@ asyncio.run(main()) `is_enabled` 매개변수는 다음을 허용합니다: - **불리언 값**: `True`(항상 활성) 또는 `False`(항상 비활성) -- **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 -- **비동기 함수**: 복잡한 조건부 로직을 위한 async 함수 +- **호출 가능한 함수**: `(context, agent)`를 받아 불리언을 반환하는 함수 +- **비동기 함수**: 복잡한 조건 로직을 위한 비동기 함수 -비활성화된 도구는 런타임에 LLM 에서 완전히 숨겨지므로 다음과 같은 경우에 유용합니다: +비활성화된 도구는 런타임에 LLM에서 완전히 숨겨지므로 다음과 같은 경우에 유용합니다: - 사용자 권한에 따른 기능 게이팅 - 환경별 도구 가용성(개발 vs 운영) - 서로 다른 도구 구성을 A/B 테스트 - 런타임 상태에 따른 동적 도구 필터링 -## 함수 도구에서의 오류 처리 +## 함수 도구의 오류 처리 -`@function_tool` 로 함수 도구를 생성할 때 `failure_error_function` 을 전달할 수 있습니다. 이는 도구 호출이 실패했을 때 LLM 에 오류 응답을 제공하는 함수입니다. +`@function_tool`로 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 크래시한 경우 LLM에 오류 응답을 제공하는 함수입니다. -- 기본적으로(아무 것도 전달하지 않으면) 오류 발생을 LLM 에 알리는 `default_tool_error_function` 을 실행합니다 -- 사용자 정의 오류 함수를 전달하면 해당 함수가 실행되고, 그 응답이 LLM 에 전송됩니다 -- 명시적으로 `None` 을 전달하면, 도구 호출 오류가 다시 발생하여 사용자가 처리해야 합니다. 모델이 잘못된 JSON 을 생성한 경우 `ModelBehaviorError`, 코드가 크래시한 경우 `UserError` 등이 될 수 있습니다 +- 기본적으로(아무것도 전달하지 않으면) 오류가 발생했음을 LLM에 알리는 `default_tool_error_function`이 실행됩니다. +- 자체 오류 함수를 전달하면 해당 함수가 대신 실행되어 그 응답이 LLM으로 전송됩니다. +- 명시적으로 `None`을 전달하면 도구 호출 오류가 다시 발생(re-raise)하여 직접 처리해야 합니다. 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`, 코드가 크래시한 경우 `UserError` 등이 될 수 있습니다. ```python from agents import function_tool, RunContextWrapper @@ -414,4 +414,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 47fc4a5af..959e7f181 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) 정책 하의 조직에서는 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 -- **트레이스**는 "워크플로"의 단일 엔드투엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - - `workflow_name`: 논리적 워크플로 또는 앱 이름. 예: "Code generation" 또는 "Customer service" - - `trace_id`: 트레이스 고유 ID. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>` 여야 합니다 - - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 발생한 여러 트레이스를 연결하는 데 사용. 예: 채팅 스레드 ID - - `disabled`: True 인 경우 트레이스가 기록되지 않음 +- **트레이스(Traces)** 는 "워크플로"의 단일 엔드 투 엔드 동작을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: + - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service" + - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은 `trace_<32_alphanumeric>` 여야 합니다. + - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다. + - `disabled`: True인 경우 트레이스가 기록되지 않습니다. - `metadata`: 트레이스에 대한 선택적 메타데이터 -- **스팬**은 시작과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 포함됩니다: +- **스팬(Spans)** 은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 포함됩니다: - `started_at` 및 `ended_at` 타임스탬프 - - `trace_id`: 스팬이 속한 트레이스를 나타냄 - - `parent_id`: 이 스팬의 부모 스팬을 가리킴(있는 경우) - - `span_data`: 스팬에 대한 정보. 예를 들어, `AgentSpanData` 는 에이전트에 대한 정보를, `GenerationSpanData` 는 LLM 생성에 대한 정보를 포함 + - 소속 트레이스를 나타내는 `trace_id` + - 이 스팬의 부모 스팬을 가리키는 `parent_id`(있는 경우) + - 스팬에 대한 정보인 `span_data`. 예를 들어 `AgentSpanData`는 에이전트 정보를, `GenerationSpanData`는 LLM 생성 정보를 포함합니다. ## 기본 트레이싱 기본적으로 SDK는 다음을 트레이싱합니다: -- 전체 `Runner.{run, run_sync, run_streamed}()` 가 `trace()` 로 감싸짐 -- 에이전트가 실행될 때마다 `agent_span()` 으로 감싸짐 -- LLM 생성은 `generation_span()` 으로 감싸짐 -- 함수 도구 호출은 각각 `function_span()` 으로 감싸짐 -- 가드레일은 `guardrail_span()` 으로 감싸짐 -- 핸드오프는 `handoff_span()` 으로 감싸짐 -- 오디오 입력(음성 → 텍스트)은 `transcription_span()` 으로 감싸짐 -- 오디오 출력(텍스트 → 음성)은 `speech_span()` 으로 감싸짐 -- 관련 오디오 스팬은 `speech_group_span()` 하위로 연결될 수 있음 +- 전체 `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,46 +64,46 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` 에 대한 두 번의 호출이 `with trace()` 로 감싸져 있으므로, 개별 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다 +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] 를 생성 -- [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 로 `TraceProvider` 를 구성하여 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] 에 전송하고, Exporter 가 OpenAI 백엔드로 스팬과 트레이스를 배치로 내보냄 +- 초기화 시, 트레이스를 생성하는 역할의 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider] 를 생성합니다. +- [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 로 `TraceProvider` 를 구성하여 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] 에 전송하고, 해당 Exporter가 OpenAI 백엔드로 스팬과 트레이스를 배치로 내보냅니다. -기본 설정을 커스터마이즈하여 대체 또는 추가 백엔드로 전송하거나 Exporter 동작을 수정하려면 다음 두 가지 옵션이 있습니다: +기본 설정을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 전송하거나 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 API 키를 OpenAI가 아닌 모델과 함께 사용하여 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. +OpenAI의 API 키를 비 OpenAI 모델과 함께 사용하여 트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. ```python import os @@ -125,7 +125,7 @@ agent = Agent( ``` ## 참고 -- Openai Traces 대시보드에서 무료 트레이스를 확인하세요 +- OpenAI Traces 대시보드에서 무료 트레이스를 확인하세요. ## 외부 트레이싱 프로세서 목록 diff --git a/docs/ko/usage.md b/docs/ko/usage.md index 320c1cf4f..687a06ab9 100644 --- a/docs/ko/usage.md +++ b/docs/ko/usage.md @@ -4,21 +4,21 @@ search: --- # 사용량 -Agents SDK는 모든 실행에 대한 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 접근하여 비용 모니터링, 한도 적용, 분석 기록에 사용할 수 있습니다. +Agents SDK 는 각 실행(run)마다 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이 정보에 접근하여 비용을 모니터링하고, 제한을 적용하거나, 분석을 기록할 수 있습니다. -## 추적되는 항목 +## 추적 항목 - **requests**: 수행된 LLM API 호출 수 -- **input_tokens**: 전송된 입력 토큰 합계 -- **output_tokens**: 수신된 출력 토큰 합계 +- **input_tokens**: 전송된 입력 토큰 총합 +- **output_tokens**: 수신된 출력 토큰 총합 - **total_tokens**: 입력 + 출력 -- **세부정보**: +- **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` ## 실행에서 사용량 접근 -`Runner.run(...)` 이후 `result.context_wrapper.usage`를 통해 사용량에 접근합니다. +`Runner.run(...)` 이후, `result.context_wrapper.usage` 를 통해 사용량에 접근합니다. ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -30,11 +30,11 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -사용량은 실행 동안의 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다. +사용량은 실행 중의 모든 모델 호출(도구 호출과 핸드오프 포함)에 걸쳐 집계됩니다. ### LiteLLM 모델에서 사용량 활성화 -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 @@ -52,7 +52,7 @@ print(result.context_wrapper.usage.total_tokens) ## 세션에서 사용량 접근 -`Session`(예: `SQLiteSession`)을 사용할 때, `Runner.run(...)`에 대한 각 호출은 해당 실행의 사용량을 반환합니다. 세션은 컨텍스트 유지를 위해 대화 기록을 보관하지만, 각 실행의 사용량은 독립적입니다. +`Session`(예: `SQLiteSession`) 을 사용할 때, `Runner.run(...)` 의 각 호출은 해당 실행에 대한 사용량을 반환합니다. 세션은 컨텍스트를 위한 대화 내역을 유지하지만, 각 실행의 사용량은 독립적입니다. ```python session = SQLiteSession("my_conversation") @@ -64,11 +64,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -세션은 실행 간 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출이 반환하는 사용량 지표는 해당 실행만을 나타냅니다. 세션에서는 이전 메시지가 각 실행의 입력으로 재투입될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 미칩니다. +세션은 실행 사이의 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출이 반환하는 사용량 지표는 해당 실행에 한정됩니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 제공될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다. -## 훅에서 사용량 활용 +## 훅에서의 사용량 활용 -`RunHooks`를 사용하는 경우, 각 훅에 전달되는 `context` 객체에는 `usage`가 포함됩니다. 이를 통해 주요 라이프사이클 지점에서 사용량을 로그로 남길 수 있습니다. +`RunHooks` 를 사용하는 경우, 각 훅에 전달되는 `context` 객체에 `usage` 가 포함됩니다. 이를 통해 수명주기의 핵심 시점에 사용량을 기록할 수 있습니다. ```python class MyHooks(RunHooks): @@ -77,10 +77,10 @@ class MyHooks(RunHooks): print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") ``` -## API 레퍼런스 +## API 참조 -자세한 API 문서는 다음을 참고하세요: +자세한 API 문서는 다음을 참조하세요: -- [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량에 접근 -- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 라이프사이클에 훅 연결 \ No newline at end of file +- [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근 +- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 수명주기에 훅 연결 \ No newline at end of file diff --git a/docs/ko/visualization.md b/docs/ko/visualization.md index 3876a70b8..1233fbe40 100644 --- a/docs/ko/visualization.md +++ b/docs/ko/visualization.md @@ -4,11 +4,11 @@ search: --- # 에이전트 시각화 -에이전트 시각화는 **Graphviz**를 사용해 에이전트와 그 관계를 구조화된 그래픽으로 표현합니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다. +에이전트 시각화는 **Graphviz** 를 사용해 에이전트와 그 관계를 구조화된 그래프로 생성할 수 있게 합니다. 이는 애플리케이션에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다. ## 설치 -선택적 `viz` 종속성 그룹을 설치합니다: +선택적 `viz` 종속성 그룹을 설치하세요: ```bash pip install "openai-agents[viz]" @@ -16,14 +16,14 @@ pip install "openai-agents[viz]" ## 그래프 생성 -`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 방향 그래프를 만듭니다: +`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같이 구성된 방향 그래프를 만듭니다: -- **에이전트**는 노란색 상자로 표시됨 -- **MCP 서버**는 회색 상자로 표시됨 -- **도구**는 초록색 타원으로 표시됨 -- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향 간선 +- **에이전트** 는 노란색 상자로 표시됨 +- **MCP 서버** 는 회색 상자로 표시됨 +- **도구** 는 초록색 타원으로 표시됨 +- **핸드오프** 는 한 에이전트에서 다른 에이전트로 향하는 방향 간선으로 표시됨 -### 사용 예 +### 사용 예제 ```python import os @@ -69,7 +69,7 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -이는 **triage agent**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프를 생성합니다 +이는 **triage agent** 의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 표현한 그래프를 생성합니다. ## 시각화 이해 @@ -77,32 +77,33 @@ draw_graph(triage_agent) 생성된 그래프에는 다음이 포함됩니다: - 진입점을 나타내는 **시작 노드** (`__start__`) -- 노란색 채우기의 **직사각형**으로 표시된 에이전트 -- 초록색 채우기의 **타원**으로 표시된 도구 -- 회색 채우기의 **직사각형**으로 표시된 MCP 서버 -- 상호작용을 나타내는 방향 간선: - - 에이전트 간 핸드오프를 위한 **실선 화살표** - - 도구 호출을 위한 **점선 화살표** - - MCP 서버 호출을 위한 **파선 화살표** -- 실행이 종료되는 위치를 나타내는 **종료 노드** (`__end__`) +- 노란색 채우기의 **사각형** 으로 표시된 에이전트 +- 초록색 채우기의 **타원** 으로 표시된 도구 +- 회색 채우기의 **사각형** 으로 표시된 MCP 서버 +- 상호작용을 나타내는 방향 간선 + - 에이전트 간 핸드오프에는 **실선 화살표** + - 도구 호출에는 **점선 화살표** + - MCP 서버 호출에는 **파선 화살표** +- 실행 종료 지점을 나타내는 **끝 노드** (`__end__`) -**참고:** MCP 서버 렌더링은 최근 버전의 -`agents` 패키지에서 지원됩니다 (**v0.2.8**에서 확인됨). 시각화에서 MCP 상자가 보이지 않으면 최신 릴리스로 업그레이드하세요. +**Note:** MCP servers are rendered in recent versions of the +`agents` package (verified in **v0.2.8**). If you don’t see MCP boxes +in your visualization, upgrade to the latest release. -## 그래프 커스터마이징 +## 그래프 사용자 지정 ### 그래프 표시 -기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에 표시하려면 다음을 작성하세요: +기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에서 표시하려면 다음과 같이 작성하세요: ```python draw_graph(triage_agent).view() ``` ### 그래프 저장 -기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일 이름을 지정하세요: +기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일 이름을 지정하세요: ```python draw_graph(triage_agent, filename="agent_graph") ``` -이렇게 하면 작업 디렉터리에 `agent_graph.png`가 생성됩니다. \ 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 25ca0ebb7..2c4268e1f 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 @@ -37,25 +37,25 @@ graph LR 파이프라인을 만들 때 다음을 설정할 수 있습니다: 1. 매번 새로운 오디오가 전사될 때 실행되는 코드인 [`workflow`][agents.voice.workflow.VoiceWorkflowBase] -2. 사용하는 [`speech-to-text`][agents.voice.model.STTModel] 및 [`text-to-speech`][agents.voice.model.TTSModel] 모델 +2. 사용되는 [`speech-to-text`][agents.voice.model.STTModel] 및 [`text-to-speech`][agents.voice.model.TTSModel] 모델 3. 다음과 같은 항목을 구성할 수 있는 [`config`][agents.voice.pipeline_config.VoicePipelineConfig] - - 모델 제공자: 모델 이름을 실제 모델에 매핑 - - 트레이싱: 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 트레이스 ID 등 - - TTS 및 STT 모델의 설정: 프롬프트, 언어, 사용하는 데이터 타입 등 + - 모델 이름을 모델로 매핑할 수 있는 모델 프로바이더 + - 트레이싱: 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 추적 ID 등 + - 프롬프트, 언어, 사용되는 데이터 타입 등 TTS 및 STT 모델 설정 ## 파이프라인 실행 -파이프라인은 [`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드를 통해 실행할 수 있으며, 오디오 입력을 두 가지 형태로 전달할 수 있습니다: +[`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]을 사용합니다. 감지되는 대로 오디오 청크를 푸시할 수 있으며, 음성 파이프라인은 "활동 감지(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/ko/voice/quickstart.md b/docs/ko/voice/quickstart.md index 5d19123ad..426695232 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. 음성을 텍스트로 변환하는 음성 인식 모델을 실행합니다 +2. 결과를 생성하기 위해, 보통 에이전트형 워크플로인 코드를 실행합니다 +3. 결과 텍스트를 다시 음성으로 변환하는 음성 합성 모델을 실행합니다 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## 에이전트 -먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 에이전트 두 개와 핸드오프, 그리고 도구 하나를 사용합니다. +먼저 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙할 것입니다. 여기서는 여러 에이전트와 핸드오프, 그리고 도구를 사용합니다. ```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/ko/voice/tracing.md b/docs/ko/voice/tracing.md index e6bde49b0..ccca68f1b 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]: 오디오 전사본 등 민감할 수 있는 데이터를 트레이스에 포함할지 제어합니다. 이는 음성 파이프라인에만 적용되며, 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