From 2048db7a1a37aad442f4b43f10c39b14f8ea3d6e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 14 Oct 2025 02:43:38 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/agents.md | 64 +++++----- docs/ja/config.md | 24 ++-- docs/ja/context.md | 44 +++---- docs/ja/examples.md | 64 +++++----- docs/ja/guardrails.md | 30 ++--- docs/ja/handoffs.md | 38 +++--- docs/ja/index.md | 36 +++--- docs/ja/mcp.md | 79 ++++++------ docs/ja/models/index.md | 84 ++++++------- docs/ja/models/litellm.md | 20 +-- docs/ja/multi_agent.md | 34 +++--- docs/ja/quickstart.md | 30 ++--- docs/ja/realtime/guide.md | 76 ++++++------ docs/ja/realtime/quickstart.md | 52 ++++---- docs/ja/release.md | 16 +-- docs/ja/repl.md | 6 +- docs/ja/results.md | 40 +++--- docs/ja/running_agents.md | 94 +++++++------- docs/ja/sessions.md | 83 ++++++------- docs/ja/streaming.md | 16 +-- docs/ja/tools.md | 90 +++++++------- docs/ja/tracing.md | 80 ++++++------ docs/ja/usage.md | 26 ++-- docs/ja/visualization.md | 30 ++--- docs/ja/voice/pipeline.md | 26 ++-- docs/ja/voice/quickstart.md | 16 +-- docs/ja/voice/tracing.md | 16 +-- docs/ko/agents.md | 52 ++++---- docs/ko/config.md | 20 +-- docs/ko/context.md | 38 +++--- docs/ko/examples.md | 50 ++++---- docs/ko/guardrails.md | 26 ++-- docs/ko/handoffs.md | 42 +++---- docs/ko/index.md | 34 +++--- docs/ko/mcp.md | 95 ++++++++------- docs/ko/models/index.md | 76 ++++++------ docs/ko/models/litellm.md | 24 ++-- docs/ko/multi_agent.md | 42 +++---- docs/ko/quickstart.md | 34 +++--- docs/ko/realtime/guide.md | 66 +++++----- docs/ko/realtime/quickstart.md | 24 ++-- docs/ko/release.md | 20 +-- docs/ko/repl.md | 7 +- docs/ko/results.md | 44 +++---- docs/ko/running_agents.md | 92 +++++++------- docs/ko/sessions.md | 68 +++++------ docs/ko/streaming.md | 12 +- docs/ko/tools.md | 104 ++++++++-------- docs/ko/tracing.md | 84 ++++++------- docs/ko/usage.md | 24 ++-- docs/ko/visualization.md | 48 ++++---- docs/ko/voice/pipeline.md | 24 ++-- docs/ko/voice/quickstart.md | 16 +-- docs/ko/voice/tracing.md | 14 +-- docs/zh/agents.md | 72 +++++------ docs/zh/config.md | 38 +++--- docs/zh/context.md | 46 +++---- docs/zh/examples.md | 88 +++++++------- docs/zh/guardrails.md | 54 ++++----- docs/zh/handoffs.md | 50 ++++---- docs/zh/index.md | 38 +++--- docs/zh/mcp.md | 120 +++++++++--------- docs/zh/models/index.md | 90 +++++++------- docs/zh/models/litellm.md | 26 ++-- docs/zh/multi_agent.md | 46 +++---- docs/zh/quickstart.md | 40 +++--- docs/zh/realtime/guide.md | 92 +++++++------- docs/zh/realtime/quickstart.md | 58 ++++----- docs/zh/release.md | 24 ++-- docs/zh/repl.md | 7 +- docs/zh/results.md | 46 +++---- docs/zh/running_agents.md | 138 +++++++++++---------- docs/zh/sessions.md | 215 ++++++++++++++++++++------------- docs/zh/streaming.md | 36 +++--- docs/zh/tools.md | 112 ++++++++--------- docs/zh/tracing.md | 108 ++++++++--------- docs/zh/usage.md | 46 +++---- docs/zh/visualization.md | 54 ++++----- docs/zh/voice/pipeline.md | 34 +++--- docs/zh/voice/quickstart.md | 24 ++-- docs/zh/voice/tracing.md | 18 +-- 81 files changed, 2083 insertions(+), 2031 deletions(-) diff --git a/docs/ja/agents.md b/docs/ja/agents.md index adca0e74a..b6e2ade3b 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,16 +4,16 @@ search: --- # エージェント -エージェントはアプリの中核となる構成要素です。エージェントは、指示とツールで構成された大規模言語モデル（ LLM ）です。 +エージェントはアプリの中核となる基本コンポーネントです。エージェントは、instructions とツールで構成された大規模言語モデル ( LLM ) です。 -## 基本構成 +## 基本設定 エージェントで最も一般的に設定するプロパティは次のとおりです。 - `name`: エージェントを識別する必須の文字列です。 -- `instructions`: developer メッセージまたは system prompt とも呼ばれます。 -- `model`: どの LLM を使用するかを指定し、任意で `model_settings` により temperature、top_p などのモデル調整パラメーターを設定します。 -- `tools`: エージェントがタスクの達成に使用できるツールです。 +- `instructions`: developer message または system prompt とも呼ばれます。 +- `model`: 使用する LLM、および temperature、top_p などのモデル調整パラメーターを設定するためのオプションの `model_settings`。 +- `tools`: エージェントがタスクを達成するために使用できるツールです。 ```python from agents import Agent, ModelSettings, function_tool @@ -33,7 +33,7 @@ agent = Agent( ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールで、あなたが作成して `Runner.run()` に渡すオブジェクトです。これはすべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係や状態の寄せ集めとして機能します。コンテキストには任意の Python オブジェクトを指定できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入の手段です。あなたが作成して `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、リスト、TypedDict など）をサポートします。 +デフォルトでは、エージェントはプレーンテキスト ( つまり `str` ) を出力します。特定の型の出力を生成したい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型をサポートします。例: dataclasses、lists、TypedDict など。 ```python from pydantic import BaseModel @@ -73,20 +73,20 @@ agent = Agent( !!! note - `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 + `output_type` を渡すと、モデルは通常のプレーンテキスト応答ではなく、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようになります。 -## マルチエージェント システムの設計パターン +## マルチエージェントシステムの設計パターン -マルチエージェント システムを設計する方法は数多くありますが、一般的に幅広く適用できる 2 つのパターンがよく見られます。 +マルチエージェントシステムの設計にはさまざまな方法がありますが、一般的に幅広く適用できるパターンは次の 2 つです。 -1. マネージャー（エージェントをツールとして）: 中央のマネージャー/オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を維持します。 -2. ハンドオフ: 対等なエージェントが、会話を引き継ぐ専門エージェントに制御を引き渡します。これは分散型です。 +1. マネージャー ( エージェントをツールとして ): 中央のマネージャー/オーケストレーターが、ツールとして公開された専門のサブエージェントを呼び出し、会話の制御を保持します。 +2. ハンドオフ: ピアのエージェントが制御を専門のエージェントに引き継ぎ、そのエージェントが会話を引き継ぎます。これは分散型です。 -詳細は、[実践的なエージェント構築ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)をご覧ください。 +詳しくは [エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) をご覧ください。 -### マネージャー（エージェントをツールとして） +### マネージャー (エージェントをツールとして) -`customer_facing_agent` はすべてのユーザーとのやり取りを担当し、ツールとして公開された専門のサブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) のドキュメントを参照してください。 +`customer_facing_agent` はすべてのユーザー対応を処理し、ツールとして公開された専門のサブエージェントを呼び出します。詳しくは [ツール](tools.md#agents-as-tools) ドキュメントをご覧ください。 ```python from agents import Agent @@ -115,7 +115,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントが会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに特化して優れた成果を出す、モジュール式の専門エージェントが可能になります。詳細は [ハンドオフ](handoffs.md) のドキュメントをご覧ください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一のタスクに秀でたモジュール式の専門エージェントが可能になります。詳しくは [ハンドオフ](handoffs.md) ドキュメントをご覧ください。 ```python from agents import Agent @@ -136,7 +136,7 @@ triage_agent = Agent( ## 動的 instructions -多くの場合、エージェント作成時に instructions を指定できますが、関数を介して動的な instructions を提供することもできます。関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも使用できます。 +多くの場合、エージェントの作成時に指示を提供できますが、関数を介して動的に 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 にツールの使用を要求します（どのツールを使うかは賢く判断します）。 +1. `auto`: LLM がツールを使用するかどうかを判断できます。 +2. `required`: LLM にツールの使用を必須にします ( ただし、どのツールかは賢く判断します )。 3. `none`: LLM にツールを使用しないことを要求します。 -4. 特定の文字列（例: `my_tool`）を設定すると、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 @@ -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 c91a68512..6ca948545 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 は環境変数または上記で設定したデフォルトキーを用いて `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,9 +50,9 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## デバッグロギング +## デバッグログ -SDK にはハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これにより警告とエラーは `stdout` に送信されますが、その他のログは抑制されます。 +SDK には、ハンドラーが設定されていない 2 つの Python ロガーがあります。デフォルトでは、これは警告とエラーが `stdout` に送信され、それ以外のログは抑制されることを意味します。 詳細なログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。 @@ -62,7 +62,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -また、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging ガイド](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 7ae3b41ba..d8f9e8783 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,30 +4,30 @@ search: --- # コンテキスト管理 -コンテキストという用語は多義的です。考慮すべき主なコンテキストには次の 2 つのクラスがあります。 +コンテキストという語は多義的です。考慮すべき主なコンテキストは次の 2 つです。 -1. コードからローカルに利用可能なコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 -2. LLM に利用可能なコンテキスト: 応答生成時に LLM が目にするデータです。 +1. コードからローカルに利用できるコンテキスト: ツール関数の実行時、`on_handoff` のようなコールバック、ライフサイクルフックなどで必要になるデータや依存関係です。 +2. LLM に利用できるコンテキスト: 応答生成時に LLM が参照できるデータです。 ## ローカルコンテキスト これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです。 -1. 任意の Python オブジェクトを作成します。一般的なパターンとして dataclass や Pydantic オブジェクトを使います。 -2. そのオブジェクトを各種の実行メソッドに渡します（例: `Runner.run(..., **context=whatever**)`）。 -3. すべてのツール呼び出し、ライフサイクルフックなどには `RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` でアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的には dataclass や Pydantic オブジェクトを使います。 +2. そのオブジェクトを各種の実行メソッド（例: `Runner.run(..., **context=whatever**)`）に渡します。 +3. すべてのツール呼び出しやライフサイクルフックなどには、`RunContextWrapper[T]` というラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型で、`wrapper.context` からアクセスできます。 -**最も重要** な注意点: あるエージェント実行において、すべてのエージェント、ツール関数、ライフサイクルなどは同じ型のコンテキストを使用する必要があります。 +**最も重要** な点: あるエージェント実行に関わるすべてのエージェント、ツール関数、ライフサイクルなどは、同一のコンテキストの型を使用しなければなりません。 -コンテキストは次のような用途に使えます: +コンテキストは次の用途に使えます。 -- 実行のためのコンテキストデータ（例: ユーザー名/uid などユーザーに関する情報） -- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） -- ヘルパー関数 +- 実行のためのコンテキストデータ（例: ユーザー名 / uid やユーザーに関するその他の情報） +- 依存関係（例: ロガーオブジェクト、データフェッチャーなど） +- ヘルパー関数 -!!! danger "Note" +!!! 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` 関数にコンテキストを渡します。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使っていますが、任意の型を使えます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取り、実装がコンテキストから読み取っています。 +3. エージェントにジェネリックの `UserInfo` を指定し、型チェッカーがエラーを検出できるようにします（例えば、異なるコンテキスト型を受け取るツールを渡そうとした場合など）。 +4. コンテキストは `run` 関数に渡されます。 5. エージェントはツールを正しく呼び出し、年齢を取得します。 ## エージェント/LLM のコンテキスト -LLM が呼び出されるとき、LLM が参照できるデータは会話履歴のものだけです。つまり、LLM に新しいデータを利用させたい場合は、その履歴で利用可能になるような方法で提供する必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、LLM が参照できるデータは会話履歴にあるもの **のみ** です。つまり、LLM に新しいデータを利用させたい場合は、その履歴で参照可能になるように提供しなければなりません。方法はいくつかあります。 -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 +1. Agent の `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは固定文字列でも、コンテキストを受け取って文字列を出力する動的関数でも構いません。常に有用な情報（例: ユーザー名や現在の日付）に適した手法です。 +2. `Runner.run` を呼び出すときの `input` に追加します。これは `instructions` と似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) においてより下位のメッセージにできます。 +3. 関数ツールとして公開します。これはオンデマンドのコンテキストに有用で、LLM が必要だと判断したときにツールを呼び出してデータを取得できます。 +4. リトリーバル (retrieval) や Web 検索を使用します。これらは、ファイルやデータベースから関連データを取得（リトリーバル）したり、Web から取得（Web 検索）したりできる特別なツールです。関連するコンテキストデータに基づいて応答をグラウンディングするのに有用です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 47f5e163f..b4eaf8c17 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,84 +4,84 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションにある、 SDK の多様なサンプル実装をご確認ください。これらの code examples は、さまざまなパターンや機能を示す複数の カテゴリー に整理されています。 +[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、SDK のさまざまなサンプル実装をご覧ください。異なるパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーの例では、一般的な エージェント の設計パターンを示します。例えば、 + このカテゴリーの code examples は、次のような一般的なエージェント設計パターンを示します - - 決定論的ワークフロー + - 決定的なワークフロー - ツールとしての エージェント - エージェント の並列実行 - - 条件付きのツール使用 - - 入力/出力 ガードレール - - LLM を審査員として利用 + - 条件付きツール使用 + - 入力/出力のガードレール + - 判定者としての LLM - ルーティング - - ストリーミング ガードレール + - ストリーミングのガードレール - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - このカテゴリーの例では、次のような SDK の基礎的な機能を紹介します。 + これらの code examples は、次のような SDK の基礎機能を紹介します - - Hello World の code examples（Default model、 GPT-5、 open-weight model） + - Hello World の code examples（デフォルトモデル、 GPT-5、オープンウェイト モデル） - エージェント のライフサイクル管理 - 動的な システムプロンプト - - ストリーミング出力（テキスト、アイテム、関数呼び出し引数） + - ストリーミング出力（テキスト、アイテム、関数呼び出しの引数） - プロンプトテンプレート - - ファイル処理（ローカル/リモート、画像/PDF） + - ファイル処理（ローカルとリモート、画像と PDF） - 利用状況の追跡 - - 非厳格な出力型 - - 以前のレスポンス ID の使用 + - 非厳密な出力タイプ + - 以前のレスポンス ID の利用 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** 航空会社向けのカスタマーサービス システムの例。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融データ分析のための エージェント とツールで、構造化されたリサーチ ワークフローを示す金融リサーチ エージェント。 + 金融データ分析のために、エージェント とツールで構造化されたリサーチワークフローを示す金融リサーチ エージェント。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - メッセージのフィルタリングを用いた エージェント の ハンドオフ の実用的な例。 + メッセージのフィルタリングを伴うエージェント のハンドオフの実用例をご覧ください。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - ホスト型 MCP (Model Context Protocol) コネクタと承認フローの使い方を示す例。 + hosted MCP (Model Context Protocol) のコネクタと承認の使い方を示す code examples。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - MCP (Model Context Protocol) を用いた エージェント の構築方法。以下を含みます: + MCP (Model Context Protocol) でエージェント を構築する方法を学びます。内容: - ファイルシステムの例 - Git の例 - MCP プロンプト サーバーの例 - - SSE (Server-Sent Events) の例 + - SSE (Server-Sent Events) の例 - ストリーム可能な HTTP の例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - エージェント 向けのさまざまなメモリ実装の例。以下を含みます: + エージェント 向けのさまざまなメモリ実装の例。内容: - - SQLite セッション ストレージ - - 高度な SQLite セッション ストレージ - - Redis セッション ストレージ - - SQLAlchemy セッション ストレージ - - 暗号化セッション ストレージ - - OpenAI セッション ストレージ + - SQLite セッションストレージ + - 高度な SQLite セッションストレージ + - Redis セッションストレージ + - SQLAlchemy セッションストレージ + - 暗号化セッションストレージ + - OpenAI セッションストレージ - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - カスタム プロバイダーや LiteLLM 連携を含む、非 OpenAI モデルを SDK で使う方法。 + カスタムプロバイダーや LiteLLM 連携を含む、OpenAI 以外のモデルを SDK で使用する方法を探ります。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使ってリアルタイムな体験を構築する方法の例。以下を含みます: + SDK を使ってリアルタイム体験を構築する方法を示す code examples。内容: - Web アプリケーション - - コマンドライン インターフェイス + - コマンドラインインターフェース - Twilio 連携 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 推論コンテンツと structured outputs を扱う方法を示す例。 + 推論コンテンツと 適切な形式のデータ を扱う方法を示す code examples。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 複雑なマルチ エージェント リサーチ ワークフローを示す、シンプルな ディープリサーチ クローン。 + 複雑なマルチエージェントのリサーチワークフローを示す、シンプルな ディープリサーチ のクローン。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 次のような OpenAI がホストするツール の実装方法: + 次のような OpenAI がホストするツール の実装方法を学びます: - Web 検索 とフィルター付き Web 検索 - ファイル検索 @@ -90,4 +90,4 @@ search: - 画像生成 - **[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 58127e4a4..2421dea32 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,44 +4,44 @@ search: --- # ガードレール -ガードレールはエージェントと並行して実行され、ユーザー入力のチェックと検証を行います。例えば、非常に賢い（つまり遅く/高価な）モデルでカスタマーリクエストを支援するエージェントがあるとします。悪意のあるユーザーがモデルに数学の宿題を手伝わせるよう求めることは避けたいはずです。そのため、速く/安価なモデルでガードレールを実行できます。ガードレールが不正使用を検出すると、即座にエラーを発生させ、高価なモデルの実行を停止して時間とコストを節約できます。 +ガードレールはエージェントと _並行して_ 実行され、ユーザー入力のチェックやバリデーションを行います。たとえば、顧客からのリクエスト対応に非常に賢い（つまり低速・高コストな）モデルを使うエージェントがあるとします。悪意のあるユーザーがそのモデルに数学の宿題を手伝わせるよう依頼することは避けたいはずです。そこで、高速・低コストなモデルでガードレールを実行できます。ガードレールが悪用を検知した場合は即座にエラーを送出し、高コストなモデルの実行を停止して時間と費用を節約できます。 -ガードレールには次の 2 種類があります。 +ガードレールには 2 種類あります。 -1. 入力ガードレールは初期のユーザー入力に対して実行されます -2. 出力ガードレールは最終的なエージェントの出力に対して実行されます +1. 入力ガードレールは最初のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます ## 入力ガードレール -入力ガードレールは 3 つの手順で動作します。 +入力ガードレールは 3 つのステップで実行されます。 -1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。 -2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生し、ユーザーへの適切な応答や例外処理が可能になります。 +1. まず、ガードレールはエージェントに渡されたのと同じ入力を受け取ります。 +2. 次に、ガードレール関数が実行され、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それを [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップします +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かを確認します。true の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出され、適切に ユーザー に応答するか、例外を処理できます。 !!! Note - 入力ガードレールはユーザー入力に対して実行されることを想定しているため、エージェントのガードレールは、そのエージェントが最初のエージェントの場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡されないのかと疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関連する傾向があるためです。エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。 + 入力ガードレールは ユーザー 入力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが「最初の」エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティがエージェント側にあり、`Runner.run` に渡さないのかと疑問に思うかもしれません。これは、ガードレールが実際のエージェントに密接に関係する傾向があるためです。エージェントごとに異なるガードレールを実行することになるので、コードを共置することで可読性が向上します。 ## 出力ガードレール -出力ガードレールは 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 diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 63eede9c0..a53e1e465 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,19 +4,19 @@ search: --- # ハンドオフ -ハンドオフは、あるエージェントが別のエージェントにタスクを委譲できるようにする仕組みです。これは、異なるエージェントがそれぞれ異なる分野を専門としているシナリオで特に有用です。例えば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱うエージェントがいるかもしれません。 +ハンドオフを使うと、エージェントが別のエージェントにタスクを委譲できます。これは、異なるエージェントがそれぞれ異なる分野に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクを個別に処理するエージェントがいるかもしれません。 -ハンドオフは LLM に対してはツールとして表現されます。たとえば、`Refund Agent` というエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 +ハンドオフは LLM に対してツールとして表現されます。たとえば、`Refund Agent` というエージェントへのハンドオフがある場合、ツール名は `transfer_to_refund_agent` になります。 ## ハンドオフの作成 -すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、これは `Agent` を直接渡すか、またはハンドオフをカスタマイズする `Handoff` オブジェクトを渡すことができます。 +すべてのエージェントは [`handoffs`][agents.agent.Agent.handoffs] パラメーターを持ち、`Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、引き渡し先のエージェントに加えて、任意のオーバーライドや入力フィルターを指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、任意のオーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -以下は、シンプルなハンドオフの作成方法です。 +次のように、シンプルなハンドオフを作成できます。 ```python from agents import Agent, handoff @@ -28,19 +28,19 @@ refund_agent = Agent(name="Refund agent") triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)]) ``` -1. `billing_agent` のようにエージェントを直接使うことも、`handoff()` 関数を使うこともできます。 +1. エージェントを直接使う（`billing_agent` のように）ことも、`handoff()` 関数を使うこともできます。 ### `handoff()` 関数によるハンドオフのカスタマイズ -[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズが可能です。 +[`handoff()`][agents.handoffs.handoff] 関数では、さまざまなカスタマイズが可能です。 -- `agent`: ハンドオフの引き渡し先となるエージェントです。 -- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に解決されます。これをオーバーライドできます。 -- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 -- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されたことが分かった時点でデータ取得を開始するなどに役立ちます。この関数はエージェントコンテキストを受け取り、オプションで LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 -- `input_type`: ハンドオフが想定する入力の型（任意）。 -- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうか。ブール値、またはブール値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 +- `agent`: ハンドオフ先のエージェントです。 +- `tool_name_override`: 既定では `Handoff.default_tool_name()` が使用され、`transfer_to_` に解決されます。これを上書きできます。 +- `tool_description_override`: `Handoff.default_tool_description()` による既定のツール説明を上書きします。 +- `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフの実行が分かった時点でデータ取得を開始するなどに便利です。この関数はエージェント コンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御します。 +- `input_type`: ハンドオフが想定する入力の型（任意）。 +- `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は以下を参照してください。 +- `is_enabled`: ハンドオフが有効かどうか。真偽値、または真偽値を返す関数を指定でき、実行時に動的に有効/無効を切り替えられます。 ```python from agents import Agent, handoff, RunContextWrapper @@ -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 cff1eb5bb..3322c8afe 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 はごく少数の基本コンポーネントで構成されます。 -- **エージェント**: 指示とツールを備えた LLM -- **ハンドオフ**: 特定のタスクで他のエージェントに委譲できる機能 -- **ガードレール**: エージェントの入力と出力を検証する機能 -- **セッション**: 複数のエージェント実行間で会話履歴を自動的に維持 +- **エージェント** 、instructions と tools を備えた 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 ed0056cdd..dcc1b4ac1 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,36 +4,32 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションがツールやコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: +[Model context protocol](https://modelcontextprotocol.io/introduction)（MCP）は、アプリケーションがツールとコンテキストを言語モデルに公開する方法を標準化します。公式ドキュメントより: -> MCP は、アプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンなプロトコルです。MCP を AI -> アプリケーション向けの USB-C ポートのようなものだと考えてください。USB-C が、さまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は -> AI モデルを多様なデータソースやツールに接続する標準化された方法を提供します。 +> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB‑C ポートのようなものだと考えてください。USB‑C がさまざまな周辺機器やアクセサリにデバイスを接続する標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続する標準化された方法を提供します。 -Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用することも、自作してファイルシステム、HTTP、あるいはコネクタに裏打ちされたツールを エージェント に公開することもできます。 +Agents Python SDK は複数の MCP トランスポートに対応します。これにより、既存の MCP サーバーを再利用したり、独自に構築して、ファイルシステム、HTTP、あるいはコネクタで支えられたツールを エージェント に公開できます。 ## Choosing an MCP integration -MCP サーバーを エージェント に接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションをまとめたものです。 +エージェント に MCP サーバーを組み込む前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決めます。以下のマトリクスは、Python SDK がサポートするオプションの概要です。 -| 必要なこと | 推奨オプション | +| What you need | Recommended option | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| 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 モデルで動作します。 +ホスト型ツールは、ツールの往復処理全体を OpenAI のインフラに移します。あなたのコードがツールを列挙・呼び出すのではなく、[`HostedMCPTool`][agents.tool.HostedMCPTool] が サーバー ラベル（および任意のコネクタ メタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、あなたの Python プロセスへの追加コールバックなしにそれらを呼び出します。ホスト型ツールは現在、Responses API のホスト型 MCP 連携をサポートする OpenAI モデルで動作します。 ### Basic hosted MCP tool -エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して hosted ツールを作成します。`tool_config` -の dict は、REST API に送信する JSON を反映します: +エージェント の `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加してホスト型ツールを作成します。`tool_config` の dict は、REST API に送る JSON と同じ形式です: ```python import asyncio @@ -61,11 +57,11 @@ async def main() -> None: asyncio.run(main()) ``` -Hosted サーバーはそのツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 +ホストされたサーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 ### Streaming hosted MCP results -Hosted ツールは、関数ツールとまったく同じ方法で ストリーミング 結果をサポートします。モデルがまだ処理中の間に増分的な MCP 出力を消費するには、`Runner.run_streamed` に `stream=True` を渡します: +ホスト型ツールは、関数ツールとまったく同じ方法で ストリーミング される結果をサポートします。`Runner.run_streamed` に `stream=True` を渡して、モデルが処理を続けている間に MCP の増分出力を消費します: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -77,8 +73,7 @@ print(result.final_output) ### Optional approval flows -サーバーが機微な操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を要求できます。`tool_config` の -`require_approval` を単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict で設定します。判断を Python 内で行うには、`on_approval_request` コールバックを指定します。 +サーバーが機密性の高い操作を実行できる場合、各ツール実行の前に人間またはプログラムによる承認を要求できます。`tool_config` の `require_approval` を、単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの dict マッピングで設定します。Python 内で判断するには、`on_approval_request` コールバックを指定します。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -106,12 +101,11 @@ agent = Agent( ) ``` -このコールバックは同期または非同期のいずれでもよく、モデルが処理を続けるために承認データを必要とするたびに呼び出されます。 +コールバックは同期または非同期のいずれでもよく、モデルが実行を続けるために承認データを必要とするときに呼び出されます。 ### Connector-backed hosted servers -Hosted MCP は OpenAI connectors もサポートします。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。 -Responses API が認証を処理し、hosted サーバーがコネクタのツールを公開します。 +ホスト型 MCP は OpenAI コネクタにも対応します。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホストされたサーバーはコネクタのツールを公開します。 ```python import os @@ -127,13 +121,12 @@ HostedMCPTool( ) ``` -ストリーミング、承認、コネクタを含む完全な hosted ツールのサンプルは、 +ストリーミング、承認、コネクタを含む完全に動作するホスト型ツールのサンプルは [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 ## 2. Streamable HTTP MCP servers -ネットワーク接続を自分で管理したい場合は、 -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable な HTTP サーバーは、トランスポートを自分で制御したい場合や、待ち時間を低く抑えつつ自社インフラ内でサーバーを実行したい場合に最適です。 +ネットワーク接続を自分で管理したい場合は、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御したい場合や、レイテンシを低く保ちながら自分のインフラ内でサーバーを稼働させたい場合に最適です。 ```python import asyncio @@ -168,17 +161,16 @@ async def main() -> None: asyncio.run(main()) ``` -コンストラクタは次の追加オプションを受け付けます: +コンストラクターは追加のオプションを受け付けます: - `client_session_timeout_seconds` は HTTP の読み取りタイムアウトを制御します。 - `use_structured_content` は、テキスト出力よりも `tool_result.structured_content` を優先するかどうかを切り替えます。 -- `max_retry_attempts` と `retry_backoff_seconds_base` は、`list_tools()` と `call_tool()` の自動リトライを追加します。 -- `tool_filter` により、公開するツールのサブセットだけを露出できます（[Tool filtering](#tool-filtering) を参照）。 +- `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 @@ -207,7 +199,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 @@ -235,11 +227,11 @@ async with MCPServerStdio( ## Tool filtering -各 MCP サーバーはツールフィルタをサポートしており、エージェント に必要な関数だけを公開できます。フィルタリングは構築時にも、実行ごとに動的にも行えます。 +各 MCP サーバーはツールフィルターをサポートしており、エージェント が必要とする関数のみを公開できます。フィルタリングは、構築時にも、実行ごとに動的にも行えます。 ### Static tool filtering -簡単な許可/ブロックリストを設定するには、[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用します: +[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用して、単純な許可／ブロックリストを設定します: ```python from pathlib import Path @@ -257,11 +249,11 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後に残りの集合からブロック対象のツールを削除します。 +`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後残った集合からブロック対象のツールを除外します。 ### Dynamic tool filtering -より入念なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る callable を渡します。callable は同期または非同期のいずれでもよく、ツールを公開すべき場合に `True` を返します。 +より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。呼び出し可能オブジェクトは同期でも非同期でもよく、ツールを公開すべき場合に `True` を返します。 ```python from pathlib import Path @@ -285,15 +277,14 @@ async with MCPServerStdio( ... ``` -フィルタコンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 +フィルターコンテキストは、アクティブな `run_context`、ツールを要求する `agent`、および `server_name` を公開します。 ## Prompts -MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 -つのメソッドを公開します: +MCP サーバーは、エージェント の instructions を動的に生成する Prompts も提供できます。Prompts をサポートするサーバーは次の 2 つのメソッドを公開します: - `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。 -- `get_prompt(name, arguments)` は、任意のパラメーターとともに具体的なプロンプトを取得します。 +- `get_prompt(name, arguments)` は、必要に応じて パラメーター 付きの具体的なプロンプトを取得します。 ```python from agents import Agent @@ -313,11 +304,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 のアクティビティを自動的に捕捉します。含まれるもの: +[Tracing](./tracing.md) は MCP のアクティビティを自動的に収集します。含まれる内容: 1. ツールを列挙するための MCP サーバーへの呼び出し。 2. ツール呼び出しに関する MCP 関連情報。 @@ -326,6 +317,6 @@ agent = Agent( ## 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) – 承認とコネクタを含む完全なホスト型 MCP デモ。 \ No newline at end of file diff --git a/docs/ja/models/index.md b/docs/ja/models/index.md index d9d0ba9ba..66c117d72 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,20 +4,20 @@ search: --- # モデル -Agents SDK には 2 種類の OpenAI モデルのサポートが標準搭載されています。 +Agents SDK には、OpenAI モデルのサポートが 2 つの形で用意されています。 -- **推奨**: [`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) など他のモデルに切り替えたい場合は、次のセクションの手順に従ってください。 ### デフォルトの 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,52 +44,52 @@ my_agent = Agent( ) ``` -特にレイテンシを下げたい場合は、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` で使用すると、デフォルト設定より高速に応答を返すことが多いです。ただし Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の reasoning effort をサポートしていないため、本 Agents SDK ではデフォルトを `"low"` にしています。 +特に低レイテンシを狙う場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) を `reasoning.effort="minimal"` で使用すると、デフォルト設定より高速に応答が返ることがよくあります。ただし、Responses API の一部の組み込みツール（たとえば ファイル検索 と 画像生成）は `"minimal"` の reasoning effort をサポートしていません。そのため、この Agents SDK ではデフォルトを `"low"` にしています。 -#### 非 GPT-5 モデル +#### GPT-5 以外のモデル -カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK は任意のモデルと互換性のある汎用的な `ModelSettings` にフォールバックします。 +カスタムの `model_settings` なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な `ModelSettings` にフォールバックします。 -## 非 OpenAI モデル +## OpenAI 以外のモデル -[LiteLLM 連携](./litellm.md) を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、litellm の依存関係グループをインストールします。 +[LiteLLM 連携](./litellm.md) を通じて、ほとんどの OpenAI 以外のモデルを使用できます。まず、litellm の依存関係グループをインストールします。 ```bash pip install "openai-agents[litellm]" ``` -その後、`litellm/` プレフィックスを付けて [対応モデル](https://docs.litellm.ai/docs/providers) を使用します。 +次に、`litellm/` プレフィックスを付けて、[サポートされているモデル](https://docs.litellm.ai/docs/providers) を使用します。 ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 非 OpenAI モデルを使う他の方法 +### OpenAI 以外のモデルを使う他の方法 -他の LLM プロバイダーを 3 つの方法で統合できます（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 +他の LLM プロバイダーはさらに 3 つの方法で統合できます（code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）。 -1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合に該当します。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 -2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルの仕組みです。これにより、「この実行のすべての エージェント に対してカスタムのモデルプロバイダーを使う」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 -3. [`Agent.model`][agents.agent.Agent.model] では、特定の Agent インスタンスでモデルを指定できます。これにより、異なる エージェント に異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。ほとんどの利用可能なモデルを簡単に使うには、[LiteLLM 連携](./litellm.md) が便利です。 +1. [`set_default_openai_client`][agents.set_default_openai_client] は、LLM クライアントとして `AsyncOpenAI` のインスタンスをグローバルに使用したい場合に便利です。これは LLM プロバイダーが OpenAI 互換の API エンドポイントを持ち、`base_url` と `api_key` を設定できるケース向けです。設定可能なサンプルは [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルで指定します。これにより、「この実行内のすべてのエージェントにカスタムのモデルプロバイダーを使う」と指定できます。設定可能なサンプルは [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。 +3. [`Agent.model`][agents.agent.Agent.model] は、特定の Agent インスタンスでモデルを指定できるようにします。これにより、エージェントごとに異なるプロバイダーを組み合わせて使用できます。設定可能なサンプルは [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。利用可能なモデルの多くを簡単に使う方法としては、[LiteLLM 連携](./litellm.md) 経由があります。 -`platform.openai.com` の API キーがない場合は、`set_tracing_disabled()` で トレーシング を無効化するか、[別のトレーシング プロセッサー](../tracing.md) を設定することをおすすめします。 +`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することをおすすめします。 !!! note - これらの例では、Responses API をまだサポートしていないプロバイダーが多いため、Chat Completions API/モデルを使用しています。もしあなたの LLM プロバイダーがサポートしている場合は、Responses の使用をおすすめします。 + これらの code examples では Chat Completions API/モデルを使用しています。これは、ほとんどの LLM プロバイダーがまだ Responses API をサポートしていないためです。もしお使いの LLM プロバイダーがサポートしている場合は、Responses の使用をおすすめします。 ## モデルの組み合わせ -単一のワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。たとえば、振り分けには小型で高速なモデルを、複雑なタスクには大型で高機能なモデルを使う、といった形です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定のモデルを選択できます。 +単一のワークフロー内で、エージェントごとに異なるモデルを使いたいことがあります。たとえば、トリアージには小さく高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使う、といった使い分けです。[`Agent`][agents.Agent] を構成する際、次のいずれかで特定のモデルを選択できます。 1. モデル名を渡す。 -2. 任意のモデル名 + それを Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 -3. [`Model`][agents.models.interface.Model] の実装を直接渡す。 +2. 任意のモデル名と、それを Model インスタンスにマップできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 +3. [`Model`][agents.models.interface.Model] 実装を直接渡す。 !!!note - 本 SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしますが、両者はサポートする機能やツールが異なるため、各ワークフローでは単一のモデル形状の使用を推奨します。ワークフローでモデル形状を混在させる必要がある場合は、使用している機能が両方で利用可能であることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形に対応していますが、各ワークフローでは 1 つのモデル形状のみを使うことを推奨します。両者はサポートする機能やツールのセットが異なるためです。ワークフロー上でモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。 ```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 などの任意のモデル構成 パラメーター を指定できます。 +エージェントで使用するモデルをさらに細かく構成したい場合は、`temperature` などのオプションのモデル構成パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -また、OpenAI の Responses API を使用する際には、他にもいくつかの任意 パラメーター（例: `user`、`service_tier` など）があります(https://platform.openai.com/docs/api-reference/responses/create)。トップレベルで利用できない場合は、`extra_args` を使ってそれらを渡せます。 +また、OpenAI の Responses API を使用する場合、[他にもいくつかのオプションのパラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで指定できない場合は、`extra_args` を使って渡すこともできます。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 他の LLM プロバイダー使用時の一般的な問題 +## 他の LLM プロバイダー利用時の一般的な問題 -### トレーシング クライアントのエラー 401 +### トレーシングクライアントのエラー 401 -トレーシング に関連するエラーが発生する場合、トレースは OpenAI サーバー にアップロードされるため、OpenAI の API キーがないことが原因です。解決策は次の 3 つです。 +トレーシング関連のエラーが出る場合、トレースは OpenAI サーバーにアップロードされるために OpenAI の API キーが必要ですが、それが無いことが原因です。解決方法は次の 3 つです。 -1. トレーシング を完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. トレーシング 用に OpenAI のキーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものが必要です。 -3. 非 OpenAI のトレース プロセッサーを使用する。[トレーシング ドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +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 などの問題が発生することがあります。解決するには、次のいずれかを行います。 +SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだサポートしていません。その結果、404 などの問題が発生することがあります。解決策は次の 2 つです。 -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出します。これは環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用します。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。code examples は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。 -### Structured outputs サポート +### structured outputs のサポート -一部のモデルプロバイダーは [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 スキーマ出力をサポートしているプロバイダーに依存することをおすすめします。そうでない場合、不正な形式の JSON によりアプリが頻繁に壊れてしまう可能性があります。 -## プロバイダー間でのモデル混在 +## プロバイダー間でのモデル併用 -モデルプロバイダー間の機能差に注意しないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしますが、多くの他のプロバイダーはそれらをサポートしていません。次の制限に注意してください。 +モデルプロバイダーごとの機能差に注意しないと、エラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしていますが、多くの他プロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 - サポートしていない `tools` を理解しないプロバイダーに送らない - テキストのみのモデルを呼び出す前に、マルチモーダル入力をフィルタリングする -- 構造化された JSON 出力をサポートしないプロバイダーは、無効な JSON を生成する場合がある点に注意する \ No newline at end of file +- structured JSON 出力をサポートしないプロバイダーでは、無効な JSON が出力されることがある点に注意する \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index 7201476b5..3c41af085 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]" @@ -20,15 +20,15 @@ pip install "openai-agents[litellm]" 完了したら、任意のエージェントで [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用できます。 -## 例 +## コード例 -これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば、次のように入力できます: +これは完全に動作する例です。実行すると、モデル名と API キーの入力を求められます。例えば次のように入力できます。 - `openai/gpt-4.1` をモデルに、OpenAI の API キー - `anthropic/claude-3-5-sonnet-20240620` をモデルに、Anthropic の API キー - など -LiteLLM でサポートされているモデルの完全な一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 +LiteLLM でサポートされているモデルの一覧は、[litellm providers docs](https://docs.litellm.ai/docs/providers) を参照してください。 ```python from __future__ import annotations @@ -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 544421d75..b1606c004 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 複数のエージェントのオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で動き、次に何をするかをどのように決めるのか。エージェントをオーケストレーションする方法は主に 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントがどの順序で実行され、次に何をするかをどのように判断するかということです。エージェントをオーケストレーションする方法は主に 2 つあります。 -1. LLM に意思決定を任せる: LLM の知性を使って計画・推論し、それに基づいて取るべき手順を決めます。 +1. LLM に意思決定させる: LLM の知能を使って計画・推論し、その結果に基づいて取るべきステップを決定します。 2. コードでオーケストレーションする: コードでエージェントの流れを決定します。 -これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせて使えます。各パターンには、それぞれのトレードオフがあります（以下参照）。 ## LLM によるオーケストレーション -エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられたとき、LLM はタスクへの取り組み方を自律的に計画し、ツールを使ってアクションやデータ取得を行い、ハンドオフでサブエージェントにタスクを委任できます。例えば、リサーチ用エージェントには次のようなツールを装備できます。 +エージェントは、instructions、tools、ハンドオフを備えた LLM です。これは、オープンエンドなタスクが与えられたときに、LLM が自律的にタスクへの取り組み方を計画し、ツールを使ってアクションを実行してデータを取得し、ハンドオフでサブエージェントにタスクを委譲できることを意味します。例えば、リサーチエージェントには次のようなツールを備えられます。 - 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) に多数の例があります。 \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数の code examples があります。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index f178c8171..e01e2693c 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -30,7 +30,7 @@ pip install openai-agents # or `uv add openai-agents`, etc ### OpenAI API キーの設定 -まだない場合は、[これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 +お持ちでない場合は、OpenAI API キーを作成するために [これらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従ってください。 ```bash export OPENAI_API_KEY=sk-... @@ -38,7 +38,7 @@ export OPENAI_API_KEY=sk-... ## 最初のエージェントの作成 -エージェントは instructions、名前、任意の設定（`model_config` など）で定義します。 +エージェントは instructions、名前、オプションの設定（`model_config` など）で定義します。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## さらにいくつかのエージェントの追加 +## 追加のエージェントの作成 -追加のエージェントも同様に定義できます。`handoff_descriptions` はハンドオフのルーティングを決定するための追加コンテキストを提供します。 +追加のエージェントも同様に定義できます。`handoff_descriptions` はハンドオフのルーティングを判断するための追加コンテキストを提供します。 ```python from agents import Agent @@ -71,7 +71,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -各エージェントで、タスクを進める方法を決めるために選択できる送出側のハンドオフ候補の一覧を定義できます。 +各エージェントで、タスクを前進させる方法を決定するために選択可能な、送信側ハンドオフの在庫を定義できます。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## エージェントオーケストレーションの実行 -ワークフローが実行され、トリアージ エージェントが 2 つの専門エージェント間で正しくルーティングすることを確認しましょう。 +ワークフローが実行され、トリアージ エージェントが 2 つの専門エージェント間を正しくルーティングすることを確認しましょう。 ```python from agents import Runner @@ -95,7 +95,7 @@ async def main(): ## ガードレールの追加 -入力または出力に対して実行するカスタム ガードレールを定義できます。 +入力または出力に対して実行されるカスタム ガードレールを定義できます。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 全体の統合 +## 統合 -ハンドオフと入力ガードレールを使って、すべてをまとめてワークフロー全体を実行しましょう。 +すべてをまとめて、ハンドオフと入力ガードレールを使ってワークフロー全体を実行しましょう。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## トレースの表示 +## トレーシングの表示 -エージェントの実行で何が起きたかを確認するには、OpenAI Dashboard の Trace viewer に移動して、エージェント実行のトレースを表示します。 +エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードの Trace ビューアー](https://platform.openai.com/traces) に移動して、エージェント実行のトレースを表示します。 ## 次のステップ -より複雑なエージェント フローの構築方法: +より複雑なエージェント フローの構築方法を学びましょう。 -- 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 +- [エージェント](agents.md) の設定について学ぶ。 +- [エージェントの実行](running_agents.md) について学ぶ。 +- [ツール](tools.md)、[ガードレール](guardrails.md)、および [モデル](models/index.md) について学ぶ。 \ No newline at end of file diff --git a/docs/ja/realtime/guide.md b/docs/ja/realtime/guide.md index 25180af06..dbf5bb5ac 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,59 +4,59 @@ search: --- # ガイド -このガイドでは、OpenAI Agents SDK のリアルタイム機能を用いて音声対応の AI エージェントを構築する方法を詳しく説明します。 +このガイドでは、 OpenAI Agents SDK のリアルタイム機能を使って音声対応の AI エージェントを構築する方法を詳しく説明します。 !!! warning "ベータ機能" -リアルタイム エージェントはベータ版です。実装の改善に伴い破壊的変更が入る可能性があります。 +リアルタイム エージェントはベータ版です。実装の改善に伴い、破壊的変更が入る場合があります。 ## 概要 -リアルタイム エージェントは、会話フローを可能にし、音声とテキストの入力をリアルタイムで処理し、リアルタイム音声で応答します。OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話と、割り込みへの優雅な対応を実現します。 +リアルタイム エージェントは会話フローを可能にし、音声とテキストの入力をリアルタイムで処理し、リアルタイム音声で応答します。 OpenAI の Realtime API との永続的な接続を維持し、低レイテンシで自然な音声対話や、割り込みへのスムーズな対応を実現します。 ## アーキテクチャ ### コアコンポーネント -リアルタイム システムは、次の主要なコンポーネントで構成されます。 +リアルタイム システムはいくつかの重要なコンポーネントで構成されます。 -- **RealtimeAgent**: `instructions`、`tools`、`handoffs` を設定したエージェントです。 +- **RealtimeAgent**: instructions、tools、ハンドオフで構成されたエージェント。 - **RealtimeRunner**: 設定を管理します。`runner.run()` を呼び出してセッションを取得できます。 -- **RealtimeSession**: 単一の対話セッションです。通常、ユーザーが会話を開始するたびに 1 つ作成し、会話が終了するまで維持します。 -- **RealtimeModel**: 基盤となるモデル インターフェース（通常は OpenAI の WebSocket 実装） +- **RealtimeSession**: 単一の対話セッション。通常、 ユーザー が会話を開始するたびに作成し、会話が終了するまで維持します。 +- **RealtimeModel**: 基盤となるモデルインターフェース（通常は OpenAI の WebSocket 実装） ### セッションフロー 一般的なリアルタイム セッションは次のフローに従います。 -1. **RealtimeAgent を作成** し、`instructions`、`tools`、`handoffs` を設定します。 -2. **RealtimeRunner をセットアップ** し、エージェントと設定オプションを渡します。 -3. `await runner.run()` を使って **セッションを開始** し、RealtimeSession を受け取ります。 -4. `send_audio()` または `send_message()` を使用して **音声またはテキスト メッセージを送信** します。 -5. セッションをイテレートして **イベントをリッスン** します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 -6. ユーザーがエージェントの発話に被せて話したときに発生する **割り込みに対応** します。これにより現在の音声生成は自動的に停止します。 +1. **RealtimeAgent を作成** し、instructions、tools、ハンドオフを設定します。 +2. **RealtimeRunner をセットアップ** し、エージェントと設定オプションを指定します。 +3. `await runner.run()` を使って **セッションを開始** し、RealtimeSession を取得します。 +4. `send_audio()` または `send_message()` を使って **音声またはテキスト メッセージを送信** します。 +5. セッションを反復処理して **イベントをリッスン** します。イベントには音声出力、書き起こし、ツール呼び出し、ハンドオフ、エラーが含まれます。 +6. ユーザー がエージェントの発話にかぶせて話した場合に **割り込みを処理** します。これにより現在の音声生成が自動的に停止します。 セッションは会話履歴を保持し、リアルタイム モデルとの永続接続を管理します。 ## エージェント設定 -RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な相違点があります。完全な API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] の API リファレンスをご覧ください。 +RealtimeAgent は通常の Agent クラスと同様に動作しますが、いくつか重要な違いがあります。 API の詳細は、[`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] のリファレンスをご覧ください。 通常のエージェントとの主な違い: -- モデルの選択はエージェント レベルではなく、セッション レベルで設定します。 -- structured output のサポートはありません（`outputType` はサポートされません）。 -- 音声はエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 -- ツール、ハンドオフ、instructions など、その他の機能は同様に動作します。 +- モデル選択はエージェント レベルではなくセッション レベルで設定します。 +- structured outputs はサポートされません（`outputType` はサポートされません）。 +- ボイスはエージェントごとに設定できますが、最初のエージェントが話し始めた後は変更できません。 +- tools、ハンドオフ、instructions などの他の機能は同様に機能します。 ## セッション設定 ### モデル設定 -セッション設定では、基盤となるリアルタイム モデルの動作を制御できます。モデル名（例: `gpt-realtime`）、音声の選択（alloy、echo、fable、onyx、nova、shimmer）、サポートするモダリティ（テキストおよび/または音声）を設定できます。音声のフォーマットは入力・出力の両方で設定でき、デフォルトは PCM16 です。 +セッション設定では、基盤となるリアルタイム モデルの動作を制御できます。モデル名（`gpt-realtime` など）、ボイスの選択（alloy、echo、fable、onyx、nova、shimmer）、サポートするモダリティ（テキストおよび/または音声）を構成できます。音声フォーマットは入力と出力の両方で設定でき、デフォルトは PCM16 です。 ### 音声設定 -音声設定では、セッションが音声の入出力をどのように扱うかを制御します。Whisper などのモデルを使用した入力音声の文字起こし、言語設定、ドメイン特有の用語に対する精度を高めるための書き起こしプロンプトを指定できます。ターン検出の設定により、音声活動検出の閾値、無音時間、検出された音声の前後パディングなどを通じて、エージェントがいつ応答を開始・終了すべきかを制御できます。 +音声設定は、セッションが音声入力と出力をどのように処理するかを制御します。Whisper などのモデルを使用した入力音声の書き起こしを設定し、言語設定や、専門用語の精度を高めるための書き起こしプロンプトを指定できます。ターン検出の設定により、ボイスアクティビティのしきい値、無音時間、検出された発話前後のパディングなどのオプションで、エージェントがいつ応答を開始・停止すべきかを制御します。 ## ツールと関数 @@ -90,7 +90,7 @@ agent = RealtimeAgent( ### ハンドオフの作成 -ハンドオフにより、会話を専門化されたエージェント間で移譲できます。 +ハンドオフにより、専門化されたエージェント間で会話を引き継ぐことができます。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## イベント処理 -セッションはストリーミングでイベントを配信し、セッション オブジェクトをイテレートしてリッスンできます。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。特に次のイベントをハンドルしてください。 +セッションは、セッションオブジェクトを反復処理することでリッスン可能なイベントをストリーム配信します。イベントには、音声出力チャンク、書き起こし結果、ツール実行の開始と終了、エージェントのハンドオフ、エラーが含まれます。主に処理すべきイベントは次のとおりです。 -- **audio**: エージェントの応答からの raw な音声データ -- **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] を参照してください。 ## ガードレール -リアルタイム エージェントでサポートされるのは出力 ガードレール のみです。これらのガードレールはデバウンスされ、リアルタイム生成中のパフォーマンス問題を避けるために（毎語ではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、設定可能です。 +リアルタイム エージェントでサポートされるのは出力 ガードレール のみです。パフォーマンス問題を避けるため、これらの ガードレール はデバウンスされ、（単語ごとではなく）定期的に実行されます。デフォルトのデバウンス長は 100 文字ですが、構成可能です。 -ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` を通じて提供できます。両方のソースからのガードレールは併せて実行されます。 +ガードレールは `RealtimeAgent` に直接アタッチするか、セッションの `run_config` で指定できます。両方の経路からの ガードレール は一緒に実行されます。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,15 +152,15 @@ agent = RealtimeAgent( ) ``` -ガードレールがトリガーされると、`guardrail_tripped` イベントを生成し、エージェントの現在の応答を割り込むことがあります。デバウンス動作により、安全性とリアルタイム性能要件のバランスを取ります。テキスト エージェントとは異なり、リアルタイム エージェントはガードレールに引っかかっても例外をスローしません。 +ガードレール がトリガーされると、`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` イベントを必ずリッスンしてください。 -## 直接的なモデルアクセス +## 直接モデルアクセス 基盤となるモデルにアクセスして、カスタム リスナーを追加したり高度な操作を実行したりできます。 @@ -169,8 +169,8 @@ agent = RealtimeAgent( session.model.add_listener(my_custom_listener) ``` -これにより、接続を低レベルで制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 +これにより、接続をより低レベルに制御する必要がある高度なユースケース向けに、[`RealtimeModel`][agents.realtime.model.RealtimeModel] インターフェースへ直接アクセスできます。 -## コード例 +## 例 -完全に動作するサンプルは、UI コンポーネントあり/なしのデモを含む [examples/realtime ディレクトリ](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) をご覧ください。 \ No newline at end of file +完全な動作する code examples は、UI コンポーネントの有無それぞれのデモを含む [examples/realtime directory](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 86e1e46eb..ca160257c 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,40 +192,40 @@ if __name__ == "__main__": ### モデル設定 -- `model_name`: 利用可能なリアルタイムモデルから選択します (例: `gpt-realtime`) -- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`) +- `model_name`: 利用可能なリアルタイム モデルから選択（例: `gpt-realtime`） +- `voice`: ボイスの選択（`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`） +- `modalities`: テキストまたは音声を有効化（`["text"]` または `["audio"]`） -### 音声設定 +### オーディオ設定 -- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 出力音声の形式 -- `input_audio_transcription`: 文字起こしの設定 +- `input_audio_format`: 入力音声のフォーマット（`pcm16`, `g711_ulaw`, `g711_alaw`） +- `output_audio_format`: 出力音声のフォーマット +- `input_audio_transcription`: 文字起こしの設定 ### ターン検出 -- `type`: 検出方法 (`server_vad`, `semantic_vad`) -- `threshold`: 音声活動のしきい値 (0.0–1.0) -- `silence_duration_ms`: ターン終了を検出する無音時間 -- `prefix_padding_ms`: 発話前の音声パディング +- `type`: 検出方式（`server_vad`, `semantic_vad`） +- `threshold`: 音声活動のしきい値（0.0–1.0） +- `silence_duration_ms`: ターン終了を検出する無音時間 +- `prefix_padding_ms`: 発話前の音声パディング ## 次のステップ -- [リアルタイム エージェントの詳細を見る](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダ内の動作するサンプルコードを確認 -- エージェントにツールを追加 -- エージェント間のハンドオフを実装 -- 安全性のためのガードレールを設定 +- [リアルタイム エージェントの詳細](guide.md) +- 動作する sample code は [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダにあります +- エージェントにツールを追加する +- エージェント間のハンドオフを実装する +- 安全性のためのガードレールを設定する ## 認証 -環境に OpenAI API キーが設定されていることを確認してください: +環境に OpenAI API キーが設定されていることを確認してください。 ```bash export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション作成時に直接渡します: +または、セッション作成時に直接渡します。 ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/ja/release.md b/docs/ja/release.md index 1c2ba837f..282d7574b 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` バージョンに固定することをおすすめします。 +破壊的変更を避けたい場合は、プロジェクトで `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] に新しいパラメーターが 2 つ追加されました: `run_context` と `agent`。`MCPServer` を継承するすべてのクラスに、これらのパラメーターを追加する必要があります。 \ 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 2f88466c6..9aa85b499 100644 --- a/docs/ja/repl.md +++ b/docs/ja/repl.md @@ -4,7 +4,7 @@ search: --- # REPL ユーティリティ -この SDK は、ターミナルでエージェントの動作を素早く対話的にテストできる `run_demo_loop` を提供します。 +この SDK は、ターミナル上でエージェントの挙動をすばやく対話的にテストできる `run_demo_loop` を提供します。 ```python import asyncio @@ -18,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 4a87b3c70..c688e789d 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,53 +4,53 @@ search: --- # 結果 -`Runner.run` メソッドを呼び出すと、次のいずれかが返ります。 +`Runner.run` メソッドを呼び出すと、次のいずれかが得られます: -- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） +- [`RunResult`][agents.result.RunResult]（`run` または `run_sync` を呼び出した場合） +- [`RunResultStreaming`][agents.result.RunResultStreaming]（`run_streamed` を呼び出した場合） -どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はそこに含まれます。 +どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、ほとんどの有用な情報はここに含まれます。 ## 最終出力 -[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。次のいずれかです。 +[`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです: -- 最後のエージェントに `output_type` が定義されていない場合は `str` -- エージェントに出力タイプが定義されている場合は `last_agent.output_type` 型のオブジェクト +- 最後のエージェントに `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 が生成した 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 e3cc6c51f..e6f124899 100644 --- a/docs/ja/running_agents.md +++ b/docs/ja/running_agents.md @@ -4,11 +4,11 @@ search: --- # エージェントの実行 -エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。オプションは 3 つあります。 +エージェントは [`Runner`][agents.run.Runner] クラスで実行できます。選択肢は 3 つあります。 -1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。 +1. [`Runner.run()`][agents.run.Runner.run]: 非同期で実行され、[`RunResult`][agents.result.RunResult] を返します。 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 同期メソッドで、内部的には `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントを順次ストリーミングします。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 非同期で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM を ストリーミング モードで呼び出し、受信したイベントを逐次 ストリーミング します。 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -詳細は [結果ガイド](results.md) を参照してください。 +詳しくは [execution results ガイド](results.md) を参照してください。 -## エージェントループ +## エージェントのループ -`Runner` の run メソッドを使うとき、開始エージェントと入力を渡します。入力は文字列（ ユーザー メッセージと見なされます）または入力アイテムのリスト（ OpenAI Responses API のアイテム）です。 +`Runner` の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ ユーザー メッセージとみなされます）または入力アイテムのリスト（OpenAI Responses API のアイテム）です。 -ランナーは次のループを実行します。 +その後、Runner は以下のループを実行します。 1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。 2. LLM が出力を生成します。 - 1. LLM が `final_output` を返した場合、ループを終了し結果を返します。 - 2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。 - 3. LLM がツール呼び出しを生成した場合、それらを実行し、結果を追加して、ループを再実行します。 + 1. LLM が `final_output` を返した場合、ループは終了し、結果を返します。 + 2. LLM が ハンドオフ を行った場合、現在のエージェントと入力を更新し、ループを再実行します。 + 3. LLM が ツール呼び出し を行った場合、それらを実行して結果を追記し、ループを再実行します。 3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を送出します。 !!! note - LLM の出力が「最終出力」と見なされる条件は、望ましい型のテキスト出力を生成し、かつツール呼び出しがない場合です。 + LLM の出力が「最終出力」と見なされるルールは、求められた型のテキスト出力を生成し、かつツール呼び出しがないことです。 ## ストリーミング -ストリーミングを使うと、LLM の実行中にストリーミングイベントを受け取れます。ストリーム完了後、[`RunResultStreaming`][agents.result.RunResultStreaming] に、生成されたすべての新しい出力を含む実行全体の情報が含まれます。ストリーミングイベントは `.stream_events()` を呼び出すことで取得できます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 +ストリーミング を使うと、LLM の実行中に ストリーミング イベントも受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] に実行全体の情報（新しく生成されたすべての出力を含む）が含まれます。ストリーミング イベントは `.stream_events()` を呼び出して取得できます。詳しくは [ストリーミング ガイド](streaming.md) を参照してください。 ## 実行設定 -`run_config` パラメーターでは、エージェント実行のグローバル設定を構成できます。 +`run_config` パラメーターで、エージェント実行のグローバル設定を行えます。 -- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関係なく、使用するグローバルな LLM モデルを設定できます。 -- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を解決するためのモデルプロバイダーで、デフォルトは OpenAI です。 -- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力 ガードレール のリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既にフィルターがない場合に適用するグローバル入力フィルターです。入力フィルターでは、新しいエージェントに送信する入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかどうかを設定します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けるのに使えます。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 +- [`model`][agents.run.RunConfig.model]: 各 Agent の `model` に関わらず、使用するグローバルな LLM モデルを設定します。 +- [`model_provider`][agents.run.RunConfig.model_provider]: モデル名のルックアップに使うモデルプロバイダーで、デフォルトは OpenAI です。 +- [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。例えば、グローバルな `temperature` や `top_p` を設定できます。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力/出力 ガードレール のリストです。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: すべての ハンドオフ に適用するグローバル入力フィルターです（ハンドオフ 側で既に設定されていない場合）。入力フィルターにより、新しいエージェントに送る入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効化します。 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入出力など、機微なデータをトレースに含めるかを設定します。 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング ワークフロー名、トレース ID、トレース グループ ID を設定します。少なくとも `workflow_name` の設定を推奨します。グループ ID は任意で、複数の実行にまたがるトレースを関連付けられます。 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。 ## 会話/チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェント（したがって 1 回以上の LLM 呼び出し）が実行される場合がありますが、チャット会話における 1 回の論理的なターンを表します。例: +いずれの run メソッドを呼び出しても、1 つ以上のエージェントが実行される（つまり 1 回以上の LLM 呼び出しが行われる）可能性がありますが、これはチャット会話の単一の論理ターンを表します。例: -1. ユーザー ターン: ユーザー がテキストを入力 -2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフ、2 番目のエージェントがさらにツールを実行し、その後出力を生成。 +1. ユーザー のターン: ユーザー がテキストを入力 +2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 つ目のエージェントへ ハンドオフ、2 つ目のエージェントがさらにツールを実行し、その後出力を生成 -エージェント実行の最後に、 ユーザー に何を表示するかを選べます。たとえば、エージェントが生成したすべての新しいアイテムを見せる、または最終出力のみを見せることが可能です。いずれにせよ、 ユーザー が追質問をするかもしれません。その場合は、再度 run メソッドを呼び出します。 +エージェントの実行の最後に、 ユーザー に何を表示するかを選べます。例えば、エージェントが生成した新しいアイテムをすべて表示するか、最終出力のみを表示します。いずれの場合も、 ユーザー が後続の質問をするかもしれず、その場合は再度 run メソッドを呼び出せます。 ### 手動の会話管理 -次のターンの入力を取得するために、[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使って会話履歴を手動で管理できます。 +[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドで、次のターンの入力を取得し、会話履歴を手動で管理できます。 ```python async def main(): @@ -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 の会話状態機能に サーバー 側での状態管理を任せることもできます。これにより、過去のメッセージをすべて手動で再送信せずに会話履歴を保持できます。詳しくは [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/) 連携を使うと、ヒューマン・イン・ザ・ループのタスクを含む永続的で長時間実行のワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) を参照し、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) を参照してください。 +Agents SDK の [Temporal](https://temporal.io/) 連携を使うと、human-in-the-loop（人間参加型）タスクを含む、耐久性のある長時間実行のワークフローを実行できます。Temporal と Agents SDK が連携して長時間タスクを完了するデモは[この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8)で、ドキュメントは[こちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)をご覧ください。 ## 例外 -SDK は特定のケースで例外を送出します。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。 +SDK は特定の状況で例外を送出します。全リストは [`agents.exceptions`][] にあります。概要は以下のとおりです。 -- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。他の特定の例外はすべてこの一般的な型から派生します。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` メソッドに渡した `max_turns` 制限を超えたときに送出されます。指定されたやり取り回数内にエージェントがタスクを完了できなかったことを示します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（ LLM ）が予期しない、または無効な出力を生成した場合に発生します。これには次が含まれます。 - - 不正な JSON: 特定の `output_type` が定義されている場合に特に、ツール呼び出しや直接の出力で不正な JSON 構造を返す場合。 - - 予期しないツール関連の失敗: モデルが期待される方法でツールを使用できない場合。 -- [`UserError`][agents.exceptions.UserError]: SDK を使用するコードを書くあなた（ユーザー）が SDK の使用中に誤りを犯した場合に送出されます。これは通常、誤ったコード実装、無効な設定、または SDK の API の誤用に起因します。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: それぞれ入力 ガードレール または出力 ガードレール の条件が満たされたときに送出されます。入力 ガードレール は処理前に受信メッセージをチェックし、出力 ガードレール はエージェントの最終応答を配信前にチェックします。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で送出されるすべての例外の基底クラスです。その他の特定の例外はここから派生します。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えた場合に送出されます。指定された対話ターン数内にタスクを完了できなかったことを示します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。例: + - 不正な JSON: 特定の `output_type` が定義されている場合などに、モデルがツール呼び出しや直接出力で不正な JSON 構造を返す。 + - 予期しないツール関連の失敗: モデルが期待どおりにツールを使用できない場合 +- [`UserError`][agents.exceptions.UserError]: SDK を使用するあなた（この SDK を使ってコードを書く人）が誤った使い方をした場合に送出されます。誤ったコード実装、無効な設定、SDK の 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 542b70e74..fe82dc9cc 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,11 +51,11 @@ print(result.final_output) # "Approximately 39 million" セッションメモリが有効な場合: -1. **各実行の前**: ランナーがそのセッションの会話履歴を自動取得し、入力アイテムの先頭に付加します。 -2. **各実行の後**: 実行中に生成されたすべての新しいアイテム (ユーザー入力、アシスタントの応答、ツール呼び出しなど) は自動的にセッションへ保存されます。 -3. **コンテキストの維持**: 同じセッションでの後続の実行には完全な会話履歴が含まれ、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの先頭に付加します。 +2. **各実行の後**: 実行中に生成された新しいすべてのアイテム (ユーザー入力、アシスタントの応答、ツール呼び出しなど) は自動的にセッションに保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の各実行には会話履歴全体が含まれるため、エージェントはコンテキストを維持できます。 -これにより、実行間で `.to_input_list()` を手動で呼び出して会話状態を管理する必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出して実行間の会話状態を管理する必要がなくなります。 ## メモリ操作 @@ -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,7 +128,8 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API メモリ -自前のデータベースを管理せずに [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 がホストするインフラストラクチャにすでに依存している場合に便利です。 +自前のデータベースを管理せずに +[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 @@ -187,13 +188,13 @@ result2 = await Runner.run( ) ``` -### SQLAlchemy ベースのセッション +### SQLAlchemy 対応セッション -より高度なユースケースでは、SQLAlchemy ベースのセッションバックエンドを使用できます。これにより、セッションの保存先として SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) を使用できます。 +より高度なユースケース向けに、SQLAlchemy 駆動のセッションバックエンドを使用できます。これにより、SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) をセッションストレージに使用できます。 -**例 1: `from_url` を使ったインメモリ SQLite の利用** +**例 1: `from_url` を使用したメモリ内 SQLite** -開発やテストに最適な、最も簡単な始め方です。 +これは最も簡単な開始方法で、開発およびテストに最適です。 ```python import asyncio @@ -216,7 +217,7 @@ if __name__ == "__main__": **例 2: 既存の SQLAlchemy エンジンの使用** -本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを保有している可能性が高いです。これをセッションに直接渡せます。 +本番アプリケーションでは、すでに SQLAlchemy の `AsyncEngine` インスタンスを持っている可能性があります。これをセッションに直接渡せます。 ```python import asyncio @@ -244,11 +245,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -### 暗号化されたセッション +### 暗号化セッション -保存時に会話データの暗号化が必要なアプリケーションでは、`EncryptedSession` を使用して任意のセッションバックエンドを透過的な暗号化と自動 TTL ベースの有効期限でラップできます。これは `encrypt` 追加機能が必要です: `pip install openai-agents[encrypt]`。 +保存時に会話データの暗号化が必要なアプリケーションでは、`EncryptedSession` を使用して任意のセッションバックエンドを透過的な暗号化と自動の TTL ベース有効期限でラップできます。これは `encrypt` エクストラが必要です: `pip install openai-agents[encrypt]`。 -`EncryptedSession` は、セッションごとの鍵導出 (HKDF) を用いた Fernet 暗号化を使用し、古いメッセージの自動期限切れをサポートします。アイテムが TTL を超えた場合、取得時に黙ってスキップされます。 +`EncryptedSession` は、セッションごとのキー導出 (HKDF) を用いた Fernet 暗号化を使用し、古いメッセージの自動有効期限切れをサポートします。アイテムが TTL を超えた場合、取得時に暗黙的にスキップされます。 **例: SQLAlchemy セッションデータの暗号化** @@ -283,17 +284,17 @@ if __name__ == "__main__": **主な特長:** -- **透過的な暗号化**: 保存前にすべてのセッションアイテムを自動的に暗号化し、取得時に復号します -- **セッションごとの鍵導出**: セッション ID をソルトとした HKDF を使用して一意の暗号鍵を導出します -- **TTL ベースの期限管理**: 設定可能な有効期限 (デフォルト: 10 分) に基づいて古いメッセージを自動的に失効させます -- **柔軟な鍵入力**: Fernet キーまたは生の文字列のいずれかを暗号鍵として受け付けます -- **あらゆるセッションをラップ**: SQLite、SQLAlchemy、またはカスタムセッション実装で動作します +- **透過的な暗号化**: 保存前にすべてのセッションアイテムを自動的に暗号化し、取得時に復号 +- **セッションごとのキー導出**: セッション ID をソルトとして用いた HKDF により一意の暗号鍵を導出 +- **TTL ベースの有効期限**: 設定可能な有効期間に基づいて古いメッセージを自動的に期限切れに (デフォルト: 10 分) +- **柔軟な鍵入力**: Fernet キーまたは生の文字列のいずれも暗号鍵として受け付け +- **任意のセッションをラップ**: SQLite、SQLAlchemy、またはカスタムセッション実装で動作 !!! warning "重要なセキュリティに関する注意" - - 暗号鍵は安全に保管してください (例: 環境変数、シークレットマネージャー) - - 期限切れトークンはアプリケーションサーバーのシステムクロックに基づいて拒否されます。クロックドリフトにより有効なトークンが拒否されないよう、すべてのサーバーが NTP で時刻同期されていることを確認してください - - 基盤となるセッションは引き続き暗号化済みデータを保存するため、データベースインフラの管理は引き続き行えます + - 暗号鍵は安全に保管してください (例: 環境変数、シークレットマネージャー) + - 期限切れトークンはアプリケーション サーバーのシステムクロックに基づいて拒否されます。クロックスキューにより有効なトークンが拒否されるのを避けるため、すべてのサーバーが NTP で時刻同期されていることを確認してください + - 基盤となるセッションは引き続き暗号化データを保存するため、データベースインフラストラクチャを制御できます ## カスタムメモリ実装 @@ -345,20 +346,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()`) を使用します -- 透過的な暗号化と TTL ベースの期限切れを付与するには暗号化セッション (`EncryptedSession(session_id, underlying_session, encryption_key)`) で任意のセッションをラップします -- さらに高度なユースケースでは、他の本番システム (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 など) 向けにカスタムセッションバックエンドの実装を検討 ### セッション管理 @@ -450,10 +451,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 ベースの実装 -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - TTL 付き暗号化セッションラッパー \ 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 cc4ca7fb3..921ef02d1 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,15 +4,15 @@ search: --- # ストリーミング -ストリーミングを使うと、進行中の エージェント の実行に関する更新を購読できます。これはエンドユーザーに進捗や部分的なレスポンスを表示するのに役立ちます。 +ストリーミングは、エージェントの実行が進行するにつれて更新を購読できるようにします。これは、エンドユーザーに進捗更新や部分的な応答を表示するのに役立ちます。 -ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼ぶと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 +ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が得られます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。 -## raw レスポンスイベント +## raw response イベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントにはタイプ（`response.created`、`response.output_text.delta` など）とデータがあります。生成され次第、ユーザーにレスポンスメッセージをストリーミングしたい場合に有用です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw なイベントです。OpenAI Responses API 形式であり、各イベントは種類（`response.created`、`response.output_text.delta` など）とデータを持ちます。これらのイベントは、生成され次第、応答メッセージをユーザーにストリーミングしたい場合に便利です。 -たとえば、次のコードは LLM が生成したテキストをトークンごとに出力します。 +たとえば、次の例では LLM が生成したテキストをトークンごとに出力します。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 実行アイテムイベントと エージェント イベント +## 実行アイテム イベントと エージェント イベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新をプッシュできます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在の エージェント が変更されたとき（例: ハンドオフ の結果）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを知らせます。これにより、各トークンではなく「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を送信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果）に更新を提供します。 -たとえば、次のコードは raw イベントを無視し、ユーザーに更新をストリーミングします。 +たとえば、次の例では raw イベントを無視して、ユーザーに更新をストリーミングします。 ```python import asyncio diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 9d272ef81..708235c47 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,23 +4,23 @@ search: --- # ツール -ツールは エージェント がアクションを実行できるようにします。たとえばデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの操作などです。Agents SDK には 3 つのクラスのツールがあります: +ツールは エージェント に行動を取らせます。例えば、データの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの使用などです。Agents SDK には 3 つのツールクラスがあります。 -- ホスト型ツール: これらは AI モデルと同じ LLM サーバー上で動作します。OpenAI は Retrieval、Web 検索、コンピュータ操作 をホスト型ツールとして提供しています。 +- Hosted tools: これらは AI モデルと同じ LLM サーバー 上で動作します。OpenAI は retrieval、Web 検索、コンピュータ操作 を Hosted tools として提供しています。 - Function calling: 任意の Python 関数をツールとして利用できます。 -- ツールとしての エージェント: エージェント をツールとして使えるため、ハンドオフ せずに他の エージェント を呼び出せます。 +- Agents as tools: エージェント をツールとして利用でき、ハンドオフ せずに他の エージェント を呼び出せます。 -## ホスト型ツール +## Hosted tools -OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 利用時にいくつかの組み込みツールを提供しています: +[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合、OpenAI はいくつかの組み込みツールを提供しています。 -- [`WebSearchTool`][agents.tool.WebSearchTool]: エージェント が Web を検索できるようにします。 -- [`FileSearchTool`][agents.tool.FileSearchTool]: OpenAI の ベクトルストア から情報を取得できます。 -- [`ComputerTool`][agents.tool.ComputerTool]: コンピュータ操作 の自動化を可能にします。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]: LLM がサンドボックス環境でコードを実行できます。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool]: リモートの MCP サーバーのツールをモデルに公開します。 -- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]: プロンプトから画像を生成します。 -- [`LocalShellTool`][agents.tool.LocalShellTool]: マシン上でシェルコマンドを実行します。 +- [`WebSearchTool`][agents.tool.WebSearchTool] は エージェント に Web を検索させます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] は OpenAI ベクトルストア から情報を取得できます。 +- [`ComputerTool`][agents.tool.ComputerTool] は コンピュータ操作 の自動化を可能にします。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は LLM がサンドボックス環境でコードを実行できるようにします。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] はリモートの MCP サーバー のツールをモデルに公開します。 +- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] はプロンプトから画像を生成します。 +- [`LocalShellTool`][agents.tool.LocalShellTool] はあなたのマシン上でシェルコマンドを実行します。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -43,14 +43,14 @@ async def main(): ## 関数ツール -任意の Python 関数をツールとして利用できます。Agents SDK がツールを自動的にセットアップします: +任意の Python 関数をツールとして使用できます。Agents SDK はツールの設定を自動で行います。 -- ツール名は Python 関数名になります（または任意の名前を指定できます） -- ツールの説明は関数の docstring から取得します（または説明を指定できます） +- ツール名は Python 関数名になります（任意で名前を指定可能） +- ツールの説明は関数の docstring から取得します（任意で説明を指定可能） - 関数入力のスキーマは関数の引数から自動生成されます -- 各入力の説明は、無効化しない限り関数の docstring から取得します +- 各入力の説明は、無効化しない限り、関数の 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,10 +102,10 @@ for tool in agent.tools: ``` -1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期どちらでも構いません。 -2. docstring が存在する場合、説明や引数の説明の取得に使用します。 -3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名や説明、docstring スタイルなどのオーバーライドも設定できます。 -4. デコレートされた関数をツールのリストに渡せます。 +1. 関数の引数には任意の Python 型を使用でき、関数は同期・非同期のどちらでも構いません。 +2. docstring があれば、説明や引数の説明に使用します。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、docstring スタイルなども上書き設定できます。 +4. デコレータを付与した関数をツールのリストに渡せます。 ??? note "Expand to see output" @@ -179,12 +179,12 @@ for tool in agent.tools: ### カスタム関数ツール -Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を提供する必要があります: +Python 関数をツールとして使いたくない場合もあります。その場合は、直接 [`FunctionTool`][agents.tool.FunctionTool] を作成できます。次を指定する必要があります。 - `name` - `description` - `params_json_schema`（引数の JSON スキーマ） -- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツール出力の文字列を返す非同期関数） +- `on_invoke_tool`（[`ToolContext`][agents.tool_context.ToolContext] と引数の JSON 文字列を受け取り、ツールの出力を文字列で返す非同期関数） ```python from typing import Any @@ -219,16 +219,16 @@ tool = FunctionTool( ### 引数と docstring の自動解析 -前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足事項は以下のとおりです: +前述の通り、ツールのスキーマを抽出するために関数シグネチャを自動解析し、ツールおよび各引数の説明を抽出するために docstring を解析します。補足事項は以下の通りです。 -1. シグネチャの解析は `inspect` モジュールで行います。型アノテーションを用いて引数の型を理解し、全体のスキーマを表現するために動的に Pydantic モデルを構築します。Python の基本型、Pydantic モデル、TypedDict などほとんどの型をサポートします。 -2. docstring の解析には `griffe` を使用します。サポートする docstring 形式は `google`、`sphinx`、`numpy` です。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 ペイロード）を抽出する。 -- エージェント の最終回答を変換・再整形する（例: 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 @@ -372,26 +372,26 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` パラメーターは次を受け付けます: +`is_enabled` パラメーター は次を受け付けます。 -- **Boolean 値**: `True`（常に有効）または `False`（常に無効） -- **呼び出し可能な関数**: `(context, agent)` を受け取り boolean を返す関数 +- **ブール値**: `True`（常に有効）または `False`（常に無効） +- **呼び出し可能な関数**: `(context, agent)` を受け取りブール値を返す関数 - **非同期関数**: 複雑な条件ロジック向けの async 関数 -無効化されたツールは実行時に LLM から完全に隠されるため、次の用途に有用です: +無効化されたツールは実行時に LLM から完全に隠されるため、以下に有用です。 - ユーザー 権限に基づく機能ゲーティング -- 環境別のツール可用性（dev と prod） +- 環境別のツール提供（開発 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` などになり得ます。 +- 既定では（何も渡さない場合）、`default_tool_error_function` が実行され、エラーが発生したことを LLM に伝えます。 +- 独自のエラー関数を渡した場合はそれが実行され、そのレスポンスが LLM に送信されます。 +- 明示的に `None` を渡した場合、ツール呼び出しのエラーは再スローされ、あなたが処理する必要があります。モデルが不正な 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/ja/tracing.md b/docs/ja/tracing.md index 64b24f5b2..2e29d35fb 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,52 +4,52 @@ search: --- # トレーシング -Agents SDK にはトレーシングが組み込まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントまで記録します。[Traces ダッシュボード](https://platform.openai.com/traces)を使うと、開発中や本番環境でワークフローのデバッグ、可視化、監視ができます。 +Agents SDK には組み込みのトレーシングが含まれており、エージェントの実行中に発生するイベントの包括的な記録を収集します。LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタム イベントまで対象です。[Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効化する方法は 2 つあります: + トレーシングはデフォルトで有効です。トレーシングを無効にする方法は 2 つあります。 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングをグローバルに無効化できます - 2. 1 回の実行に対してのみ無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します + 2. 1 回の実行に対してトレーシングを無効化するには、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定します -***OpenAI の API を使用し Zero Data Retention (ZDR) ポリシーの下で運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシーで運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は「ワークフロー」の単一のエンドツーエンドの操作を表します。スパンで構成されます。トレースには次のプロパティがあります: +- **トレース (Traces)** は「ワークフロー」のエンドツーエンドの単一操作を表します。スパンで構成されます。トレースには次のプロパティがあります。 - `workflow_name`: 論理的なワークフローまたはアプリです。例: "Code generation" や "Customer service" - - `trace_id`: トレースの一意の ID。指定しなければ自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 省略可能なグループ ID。同じ会話からの複数のトレースをリンクするために使用します。たとえば、チャットスレッド ID を使えます。 - - `disabled`: True の場合、このトレースは記録されません。 + - `trace_id`: トレースの一意の ID。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 任意のグループ ID。同じ会話からの複数のトレースをリンクするために使用します。たとえばチャット スレッドの ID を使用できます。 + - `disabled`: True の場合、トレースは記録されません。 - `metadata`: トレースの任意のメタデータ。 -- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: +- **スパン (Spans)** は開始時刻と終了時刻のある操作を表します。スパンには次があります。 - `started_at` と `ended_at` のタイムスタンプ - - 所属するトレースを表す `trace_id` - - 親スパン (ある場合) を指す `parent_id` - - スパンに関する情報を含む `span_data`。例えば、`AgentSpanData` はエージェントに関する情報を、`GenerationSpanData` は LLM 生成に関する情報を含みます。 + - `trace_id`（所属するトレースを示します） + - `parent_id`（このスパンの親スパンを指します。ある場合） + - `span_data`（スパンに関する情報）。たとえば、`AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報などが含まれます。 ## デフォルトのトレーシング -デフォルトでは、SDK は次をトレースします: +デフォルトでは、SDK は次をトレースします。 -- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます +- 全体の `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()` の配下に置かれる場合があります +- 音声入力（音声認識）は `transcription_span()` でラップされます +- 音声出力（音声合成）は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親子付けされる場合があります デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できますし、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成することもできます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の宛先に送信できます (置き換えとして、または二次的な宛先として)。 +さらに、[カスタム トレース プロセッサー](#custom-tracing-processors) を設定して、他の送信先にトレースをプッシュできます（置き換えとして、またはセカンダリの送信先として）。 ## 高レベルのトレース -複数回の `run()` 呼び出しを 1 つのトレースにまとめたいことがあります。その場合は、コード全体を `trace()` でラップします。 +複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合は、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -68,42 +68,42 @@ async def main(): ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: +[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります。 -1. 推奨: トレースをコンテキストマネージャとして使用します。つまり `with trace(...) as my_trace` のようにします。適切なタイミングで自動的に開始・終了されます。 +1. 推奨: コンテキスト マネージャーとしてトレースを使用します（例: `with trace(...) as my_trace`）。適切なタイミングでトレースを自動的に開始・終了します。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これは、自動的に並行処理で機能することを意味します。トレースを手動で開始/終了する場合、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。つまり、並行処理でも自動的に機能します。トレースを手動で開始・終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -各種の [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が利用可能です。 +さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタム スパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数が利用できます。 -スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される最も近い現在のスパンの配下にネストされます。 +スパンは自動的に現在のトレースの一部となり、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡される最も近い現在のスパンの下に入れ子になります。 ## 機微なデータ -一部のスパンは、機微なデータを取得する場合があります。 +一部のスパンは機微なデータを収集する可能性があります。 -`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機微なデータが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を、`function_span()` は関数呼び出しの入力/出力を保存します。機微なデータが含まれる場合があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそれらのデータの取得を無効化できます。 -同様に、音声スパンにはデフォルトで入力および出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成して、この音声データの取得を無効化できます。 +同様に、Audio スパンには既定で入力および出力音声の 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` には [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を構成し、バッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] にトレース/スパンを送信します。`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 モデルでも OpenAI API キーを使用して、OpenAI Traces ダッシュボードで無料のトレーシングを有効化できます。 ```python import os @@ -124,16 +124,16 @@ agent = Agent( ) ``` -## 注意事項 -- 無料のトレースは OpenAI の Traces ダッシュボードで確認できます。 +## 注記 +- 無料のトレースは OpenAI Traces ダッシュボードで確認できます。 -## 外部トレーシングプロセッサー一覧 +## 外部トレーシング プロセッサー一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (自己ホスト/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks ホスト)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 3956e00f0..1bf7bb070 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 @@ -16,9 +16,9 @@ Agents SDK は、すべての実行におけるトークンの使用状況を自 - `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 @@ -50,9 +50,9 @@ result = await Runner.run(agent, "What's the weather in Tokyo?") print(result.context_wrapper.usage.total_tokens) ``` -## セッションでの使用状況の取得 +## セッションでの使用状況へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その実行に固有の使用状況を返します。セッションはコンテキストのための会話履歴を保持しますが、各実行の使用状況は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` への各呼び出しは、その特定の実行の使用状況を返します。セッションはコンテキストのために会話履歴を保持しますが、各実行の使用状況は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -64,9 +64,9 @@ 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` が含まれます。これにより、重要なライフサイクルのタイミングで使用状況を記録できます。 @@ -81,6 +81,6 @@ class MyHooks(RunHooks): 詳細な 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 5a71d9cdb..15ed8448a 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 サーバー** は灰色のボックス。 +- **ツール** は緑の楕円。 +- **ハンドオフ** はエージェント間の有向エッジ。 ### 使用例 @@ -67,19 +67,19 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![エージェント グラフ](../assets/images/graph.png) +![エージェントグラフ](../assets/images/graph.png) -これは、 **トリアージ エージェント** とそのサブエージェントおよびツールへの接続の構造を視覚的に表すグラフを生成します。 +これは、 **トリアージ エージェント** と、そのサブエージェントやツールとの接続の構造を視覚的に表すグラフを生成します。 ## 可視化の理解 -生成されるグラフには以下が含まれます: +生成されたグラフには次が含まれます: -- エントリーポイントを示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた長方形で表現される **エージェント**。 -- 緑色で塗りつぶされた楕円で表現される **ツール**。 -- グレーで塗りつぶされた長方形で表現される **MCP サーバー**。 +- 入口を示す **開始ノード** (`__start__`)。 +- 黄色で塗りつぶされた **長方形** として表されるエージェント。 +- 緑で塗りつぶされた **楕円** として表されるツール。 +- 灰色で塗りつぶされた **長方形** として表される MCP サーバー。 - 相互作用を示す有向エッジ: - エージェント間のハンドオフには **実線の矢印**。 - ツール呼び出しには **点線の矢印**。 @@ -91,14 +91,14 @@ draw_graph(triage_agent) ## グラフのカスタマイズ ### グラフの表示 -デフォルトでは、`draw_graph` はグラフをインライン表示します。別ウィンドウでグラフを表示するには、次のように記述します: +既定では、`draw_graph` はグラフをインライン表示します。グラフを別ウィンドウで表示するには、次のように記述します: ```python draw_graph(triage_agent).view() ``` ### グラフの保存 -デフォルトでは、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: +既定では、`draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します: ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 1679e52d7..c01672a15 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェント主導のワークフローを音声アプリに変換しやすくするクラスです。実行するワークフローを渡すと、入力音声の文字起こし、音声の終了検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声化までをパイプラインが処理します。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントのワークフローを音声アプリにするのを容易にするクラスです。実行したいワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検知、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声化までを担当します。 ```mermaid graph LR @@ -34,28 +34,28 @@ graph LR ## パイプラインの設定 -パイプラインの作成時に、次の項目を設定できます。 +パイプラインを作成する際、次の項目を設定できます。 -1. 毎回新しい音声が書き起こされるたびに実行されるコードである [`workflow`][agents.voice.workflow.VoiceWorkflowBase] -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] と [`text-to-speech`][agents.voice.model.TTSModel] のモデル -3. 次のような設定を行える [`config`][agents.voice.pipeline_config.VoicePipelineConfig] +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 モデルの設定 + - トレーシング（トレーシングを無効にするか、音声ファイルのアップロード可否、ワークフロー名、trace ID など） + - TTS および STT モデルの設定（プロンプト、言語、使用するデータ型など） ## パイプラインの実行 -パイプラインは、音声入力を 2 つの形式で渡せる [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行できます。 +パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力を次の 2 つの形式で渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声書き起こしがあり、その結果だけを生成したい場合に使用します。これは、話者の発話終了を検知する必要がないケース、たとえば事前録音の音声や、ユーザーの発話終了が明確なプッシュトゥトーク アプリで有用です。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検知する必要がある場合に使用します。検知された音声チャンクを逐次プッシュでき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスによって、適切なタイミングでエージェントのワークフローを自動実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は完全な音声トランスクリプトがある場合に使用し、その結果だけを生成したいときに適しています。話者の発話終了を検知する必要がない状況、例として事前録音の音声や、ユーザーの発話終了が明確なプッシュトゥトークのアプリなどで有用です。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーの発話終了を検知する必要がある場合に使用します。検出された音声チャンクを順次プッシュでき、パイプラインは「アクティビティ検出」と呼ばれる処理を通じて、適切なタイミングでエージェントのワークフローを自動的に実行します。 ## 結果 -音声パイプラインの実行結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントを随時ストリーミングできるオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、次を含みます。 +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは発生するイベントを順次ストリーミングするためのオブジェクトです。いくつかの種類の [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] があり、以下が含まれます。 1. 音声チャンクを含む [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio] -2. ターンの開始や終了などのライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] +2. ターンの開始や終了といったライフサイクルイベントを通知する [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 3. エラーイベントである [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError] ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 割り込み -現在、Agents SDK は [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み対応をサポートしていません。代わりに、検出された各ターンごとにワークフローの個別の実行をトリガーします。アプリ内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントをリッスンしてください。`turn_started` は新しいターンが書き起こされ処理が開始したことを示し、`turn_ended` は該当ターンの音声がすべて送出された後に発火します。これらのイベントを用いて、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべて送出し終えた後にミュート解除できます。 \ No newline at end of file +Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み処理をサポートしていません。代わりに、検出された各ターンごとにワークフローの個別実行をトリガーします。アプリケーション内で割り込みを扱いたい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] のイベントを監視してください。`turn_started` は新しいターンが文字起こしされ処理が開始されたことを示し、`turn_ended` は該当ターンの音声がすべてディスパッチされた後にトリガーされます。これらのイベントを用いて、モデルがターンを開始した際に話者のマイクをミュートし、ターンに関連する音声をすべてフラッシュした後にミュート解除する、といった制御が可能です。 \ No newline at end of file diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md index 84ffa3aff..830014bd5 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -OpenAI Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境を設定してください。そのうえで、SDK からオプションの音声依存関係をインストールします。 +Agents SDK の基本的な[クイックスタート手順](../quickstart.md)に従い、仮想環境をセットアップしてください。次に、SDK から音声用のオプション依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -14,10 +14,10 @@ pip install 'openai-agents[voice]' ## 概念 -主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 段階のプロセスです。 +主な概念は、[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。 1. 音声をテキストに変換するために音声認識モデルを実行します。 -2. 通常はエージェント的なワークフローとなるあなたのコードを実行して結果を生成します。 +2. 通常はエージェント的なワークフローであるあなたのコードを実行し、結果を生成します。 3. 結果のテキストを音声に戻すために音声合成モデルを実行します。 ```mermaid @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定します。これは、この SDK でエージェントを作成したことがある方には馴染みがあるはずです。ここでは、複数のエージェント、ハンドオフ、そしてツールを用意します。 +まず、いくつかのエージェントをセットアップします。これは、この SDK でエージェントを作成したことがあれば馴染みがあるはずです。ここでは複数のエージェント、ハンドオフ、そしてツールを用意します。 ```python import asyncio @@ -92,14 +92,14 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使い、シンプルな音声パイプラインを設定します。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用して、シンプルな音声パイプラインを設定します。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent)) ``` -## パイプラインの実行 +## パイプライン実行 ```python import numpy as np @@ -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 2364fdb28..2875b7caf 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]: 音声の書き起こしなど、機微な可能性のあるデータをトレースに含めるかどうかを制御します。これは音声パイプライン専用であり、ワークフロー内部で行われる処理には適用されません。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースのワークフロー名です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための `group_id` です。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加メタデータです。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかを制御します。デフォルトでは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 音声書き起こしなど、機微な可能性のあるデータをトレースに含めるかを制御します。これは音声パイプライン専用で、あなたの Workflow 内部で起こることには適用されません。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかを制御します。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース ワークフローの名前。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 複数のトレースを関連付けるための、このトレースの `group_id` です。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレースに含める追加メタデータ。 \ No newline at end of file diff --git a/docs/ko/agents.md b/docs/ko/agents.md index ffb4d8201..7ad46bfc2 100644 --- a/docs/ko/agents.md +++ b/docs/ko/agents.md @@ -4,15 +4,15 @@ search: --- # 에이전트 -에이전트는 앱의 핵심 기본 구성 요소입니다. 에이전트는 instructions와 도구로 구성된 대규모 언어 모델(LLM)입니다. +에이전트는 앱의 핵심 빌딩 블록입니다. 에이전트는 instructions와 tools로 구성된 대규모 언어 모델(LLM)입니다. ## 기본 구성 -에이전트에서 가장 자주 설정하는 속성은 다음과 같습니다: +에이전트에서 가장 흔히 설정하는 속성은 다음과 같습니다: - `name`: 에이전트를 식별하는 필수 문자열 -- `instructions`: 개발자 메시지 또는 시스템 프롬프트로도 알려짐 -- `model`: 사용할 LLM 및 temperature, top_p 등의 모델 튜닝 매개변수를 설정하는 선택적 `model_settings` +- `instructions`: 개발자 메시지 또는 시스템 프롬프트라고도 함 +- `model`: 사용할 LLM 및 temperature, top_p 등 모델 튜닝 매개변수를 설정하는 선택적 `model_settings` - `tools`: 에이전트가 작업을 수행하기 위해 사용할 수 있는 도구 ```python @@ -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/)로 래핑할 수 있는 모든 타입(데이터클래스, 리스트, 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 @@ -77,16 +77,16 @@ agent = Agent( ## 멀티 에이전트 시스템 설계 패턴 -멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 두 가지 폭넓게 적용 가능한 패턴이 있습니다: +멀티 에이전트 시스템을 설계하는 방법은 다양하지만, 일반적으로 두 가지 폭넓게 적용 가능한 패턴이 있습니다: -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( @@ -181,9 +181,9 @@ robot_agent = pirate_agent.clone( 도구 목록을 제공한다고 해서 LLM이 항상 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다: 1. `auto`: LLM이 도구 사용 여부를 스스로 결정 -2. `required`: LLM이 반드시 도구를 사용해야 함(어떤 도구를 사용할지는 지능적으로 결정 가능) -3. `none`: LLM이 도구를 사용하지 _않도록_ 요구 -4. 특정 문자열 설정(예: `my_tool`): LLM이 해당 특정 도구를 사용하도록 요구 +2. `required`: LLM이 도구를 반드시 사용해야 함(단, 어떤 도구를 사용할지는 지능적으로 결정) +3. `none`: LLM이 도구를 사용하지 않아야 함 +4. 특정 문자열 설정(예: `my_tool`): 해당 특정 도구를 반드시 사용하도록 요구 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -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 06c540c92..a3e51b53f 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는 환경 변수 또는 위에서 설정한 기본 키를 사용해 `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 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. 트레이싱에 사용되는 API 키를 별도로 설정하려면 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용하세요. +트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. 트레이싱에 사용할 API 키를 명시적으로 설정하려면 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용하세요. ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -[`set_tracing_disabled()`][agents.set_tracing_disabled] 함수를 사용해 트레이싱을 완전히 비활성화할 수도 있습니다. +[`set_tracing_disabled()`][agents.set_tracing_disabled] 함수를 사용하여 트레이싱을 완전히 비활성화할 수도 있습니다. ```python from agents import set_tracing_disabled @@ -52,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 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. +또는 핸들러, 필터, 포매터 등을 추가하여 로그를 커스터마이즈할 수 있습니다. 자세한 내용은 [Python logging guide](https://docs.python.org/3/howto/logging.html)를 참고하세요. ```python import logging @@ -83,15 +83,15 @@ 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/ko/context.md b/docs/ko/context.md index 0654fa655..9f32fc579 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. 원하는 파이썬 객체를 만듭니다. 보편적인 패턴은 dataclass 또는 Pydantic 객체를 사용하는 것입니다 +1. 원하는 Python 객체를 만듭니다. 일반적으로 dataclass 또는 Pydantic 객체를 사용합니다 2. 해당 객체를 다양한 실행 메서드에 전달합니다(예: `Runner.run(..., **context=whatever**)`) -3. 모든 도구 호출, 라이프사이클 훅 등에는 `RunContextWrapper[T]` 래퍼 객체가 전달되며, 여기서 `T`는 컨텍스트 객체 타입을 나타내며 `wrapper.context`로 접근할 수 있습니다 +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` 함수에 컨텍스트가 전달됩니다 +1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass 를 사용했지만, 어떤 타입이든 사용할 수 있습니다 +2. 이것은 도구입니다. `RunContextWrapper[UserInfo]` 를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다 +3. 에이전트에 제네릭 `UserInfo` 를 표시하여, 타입 체커가 오류를 잡을 수 있게 합니다(예: 다른 컨텍스트 타입을 받는 도구를 전달하려고 할 때) +4. 컨텍스트는 `run` 함수에 전달됩니다 5. 에이전트는 도구를 올바르게 호출하고 나이를 가져옵니다 ## 에이전트/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. 파일 검색 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져올 수 있는 특별한 도구(파일 검색), 또는 웹에서 가져오는 도구(웹 검색)입니다. 이는 응답을 관련 컨텍스트 데이터에 "그라운딩"하는 데 유용합니다 \ No newline at end of file +1. 에이전트 `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. 함수 도구를 통해 노출합니다. 이는 필요 시(on-demand) 컨텍스트에 유용합니다. LLM 이 데이터가 필요할 때를 스스로 판단하고, 해당 데이터를 가져오기 위해 도구를 호출할 수 있습니다 +4. 파일 검색 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져오거나(파일 검색), 웹에서 가져오는(웹 검색) 특수 도구입니다. 관련 컨텍스트 데이터로 응답을 "그라운딩"하는 데 유용합니다 \ No newline at end of file diff --git a/docs/ko/examples.md b/docs/ko/examples.md index b4e48fbe0..d76949e60 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -4,58 +4,58 @@ 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의 다양한 샘플 구현을 확인하세요. 예제는 다양한 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다. ## 카테고리 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 이 카테고리의 코드 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 + 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 - - 결정적 워크플로우 + - 결정적 워크플로 - 도구로서의 에이전트 - 에이전트 병렬 실행 - 조건부 도구 사용 - 입력/출력 가드레일 - - LLM as a judge + - 판단자로서의 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 examples (Default model, GPT-5, open-weight model) - 에이전트 라이프사이클 관리 - 동적 시스템 프롬프트 - - 스트리밍 출력(텍스트, 아이템, 함수 호출 인자) + - 스트리밍 출력 (텍스트, 항목, 함수 호출 인자) - 프롬프트 템플릿 - - 파일 처리(로컬 및 원격, 이미지 및 PDF) + - 파일 처리 (로컬 및 원격, 이미지와 PDF) - 사용량 추적 - 비엄격 출력 타입 - 이전 응답 ID 사용 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 항공사 고객 서비스 시스템 예제 + 항공사를 위한 고객 서비스 시스템 예제 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 금융 데이터 분석을 위한 에이전트와 도구로 구조화된 리서치 워크플로우를 보여주는 금융 리서치 에이전트 + 금융 데이터 분석을 위한 에이전트와 도구를 사용해 구조화된 리서치 워크플로를 보여주는 금융 리서치 에이전트 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 메시지 필터링이 포함된 에이전트 핸드오프의 실용적인 코드 예제 + 메시지 필터링을 통한 에이전트 핸드오프의 실용적인 예제를 확인하세요 - **[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,23 +65,23 @@ 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 통합 - **[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 호스트하는 도구 를 구현하는 방법을 학습하세요 - 웹 검색 및 필터가 있는 웹 검색 - 파일 검색 @@ -90,4 +90,4 @@ search: - 이미지 생성 - **[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 54d4f9af6..f46aff3a8 100644 --- a/docs/ko/guardrails.md +++ b/docs/ko/guardrails.md @@ -4,11 +4,11 @@ search: --- # 가드레일 -가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력에 대한 점검과 검증을 수행합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(그만큼 느리고 비싼) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것을 원치 않을 것입니다. 이때 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜, 비용이 많이 드는 모델의 실행을 중단하고 시간과 비용을 절약합니다. +가드레일은 에이전트와 _병렬로_ 실행되어 사용자 입력에 대한 점검과 검증을 수행합니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고/비싼) 모델을 사용하는 에이전트를 가정해 보겠습니다. 악의적인 사용자가 수학 숙제를 도와 달라고 모델에 요청하는 것을 원하지 않을 것입니다. 따라서 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜, 비용이 큰 모델의 실행을 중단하고 시간/비용을 절약합니다. 가드레일에는 두 가지 종류가 있습니다: -1. 입력 가드레일은 최초 사용자 입력에서 실행됨 +1. 입력 가드레일은 초기 사용자 입력에서 실행됨 2. 출력 가드레일은 최종 에이전트 출력에서 실행됨 ## 입력 가드레일 @@ -17,11 +17,11 @@ search: 1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이를 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑합니다 -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하며, 이에 따라 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true인 경우 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외를 발생시켜, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *처음* 에이전트일 때만 실행됩니다. `guardrails` 속성이 왜 에이전트에 있고 `Runner.run`에 전달되지 않는지 궁금할 수 있습니다. 가드레일은 실제 에이전트와 밀접하게 연관되는 경향이 있기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행할 것이므로, 코드를 함께 두면 가독성에 도움이 됩니다. + 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. `guardrails` 속성이 `Runner.run`에 전달되는 대신 에이전트에 있는 이유가 궁금할 수 있습니다. 이는 가드레일이 실제 에이전트와 연관되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하므로 코드를 함께 배치하는 것이 가독성에 유리합니다. ## 출력 가드레일 @@ -29,11 +29,11 @@ search: 1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이를 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑합니다 -3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하며, 이에 따라 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. +3. 마지막으로 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true인 경우 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외를 발생시켜, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 밀접하게 연관되기 때문에 코드를 함께 두면 가독성에 도움이 됩니다. + 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로, 가드레일은 실제 에이전트와 연관되는 경향이 있으므로 코드를 함께 배치하는 것이 가독성에 유리합니다. ## 트립와이어 @@ -41,7 +41,7 @@ search: ## 가드레일 구현 -입력을 받아 [`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 cdf254011..99c8a23ea 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] 함수를 사용해 핸드오프를 생성할 수 있습니다. 이 함수로 핸드오프 대상 에이전트를 지정하고, 선택적으로 override 와 입력 필터를 설정할 수 있습니다. +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()` 함수를 통한 핸드오프 커스터마이즈 -[`handoff()`][agents.handoffs.handoff] 함수로 다양한 항목을 커스터마이즈할 수 있습니다. +[`handoff()`][agents.handoffs.handoff] 함수는 다양한 커스터마이즈를 제공합니다. -- `agent`: 핸드오프 대상 에이전트 -- `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`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수가 될 수 있어 런타임에 동적으로 핸드오프를 활성/비활성화할 수 있습니다. +- `agent`: 작업을 넘길 대상 에이전트 +- `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, 이는 `transfer_to_`으로 결정됩니다. 이를 오버라이드할 수 있습니다 +- `tool_description_override`: `Handoff.default_tool_description()`의 기본 도구 설명을 오버라이드 +- `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출됨을 아는 즉시 데이터 페칭을 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 전달받고, 선택적으로 LLM 이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어합니다 +- `input_type`: 핸드오프가 기대하는 입력의 타입(선택 사항) +- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 아래를 참조하세요 +- `is_enabled`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수일 수 있어, 런타임에 핸드오프를 동적으로 활성/비활성화할 수 있습니다 ```python from agents import Agent, handoff, RunContextWrapper @@ -60,7 +60,7 @@ handoff_obj = handoff( ## 핸드오프 입력 -특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하길 원할 수 있습니다. 예를 들어, "에스컬레이션 에이전트" 로의 핸드오프를 상상해 보세요. 기록을 위해 사유를 제공받고 싶을 수 있습니다. +특정 상황에서는 LLM 이 핸드오프를 호출할 때 일부 데이터를 제공하길 원할 수 있습니다. 예를 들어, "Escalation agent"로의 핸드오프를 상상해 보세요. 로깅을 위해 사유를 제공받고 싶을 수 있습니다. ```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 에이전트` 가 호출될 때 히스토리에서 모든 도구를 자동으로 제거합니다. +1. 이는 `FAQ agent`가 호출될 때 히스토리에서 모든 도구를 자동으로 제거합니다. -## 추천 프롬프트 +## 권장 프롬프트 -LLM 이 핸드오프를 올바르게 이해하도록 하려면, 에이전트에 핸드오프에 대한 정보를 포함하는 것을 권장합니다. [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] 의 권장 접두사를 사용하거나, [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] 를 호출하여 권장 데이터를 자동으로 프롬프트에 추가할 수 있습니다. +LLM 이 핸드오프를 올바르게 이해하도록 하기 위해, 에이전트에 핸드오프에 대한 정보를 포함하는 것을 권장합니다. [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][]의 권장 프리픽스를 사용하거나, [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][]를 호출해 프롬프트에 권장 데이터를 자동으로 추가할 수 있습니다. ```python from agents import Agent diff --git a/docs/ko/index.md b/docs/ko/index.md index 567526c0f..acbd4ea7a 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 -- **핸드오프**: 특정 작업에 대해 다른 에이전트에게 위임할 수 있게 함 -- **가드레일**: 에이전트 입력과 출력의 검증을 가능하게 함 -- **세션**: 에이전트 실행 간 대화 기록을 자동으로 유지 관리함 +- **에이전트**: instructions 와 tools 를 갖춘 LLM +- **핸드오프**: 특정 작업에 대해 에이전트가 다른 에이전트에 위임할 수 있게 함 +- **가드레일**: 에이전트 입력과 출력을 검증 가능하게 함 +- **세션**: 에이전트 실행 전반에 걸쳐 대화 내역을 자동으로 유지 관리 -파이썬과 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 사이의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버그하며, 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수 있게 해주는 내장 **트레이싱**이 포함되어 있습니다. +파이썬과 결합하면, 이 기본 구성 요소만으로도 도구와 에이전트 간 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 이 SDK에는 에이전트 플로우를 시각화하고 디버그할 수 있는 **트레이싱**이 내장되어 있어 평가하고, 심지어 애플리케이션에 맞춰 모델을 파인튜닝할 수도 있습니다. ## Agents SDK 사용 이유 -SDK는 두 가지 설계 원칙을 따릅니다: +이 SDK 의 설계 원칙은 다음 두 가지입니다: -1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있도록 기본 구성 요소는 최소화합니다. -2. 기본 설정으로도 훌륭하게 동작하지만, 동작 방식을 정확히 커스터마이즈할 수 있습니다. +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있도록 기본 구성 요소는 최소화 +2. 기본 설정만으로도 훌륭히 동작하지만, 동작 방식을 정확히 원하는 대로 커스터마이즈 가능 -SDK의 주요 기능은 다음과 같습니다: +SDK 의 주요 기능은 다음과 같습니다: -- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 처리하는 내장 에이전트 루프 -- 파이썬 우선: 새로운 추상화를 배우지 않고도 파이썬의 내장 언어 기능으로 에이전트를 오케스트레이션하고 체이닝 -- 핸드오프: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능 -- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 실행하고, 점검 실패 시 조기에 중단 -- 세션: 에이전트 실행 간 대화 기록을 자동 관리하여 수동 상태 관리 제거 -- 함수 도구: 어떤 파이썬 함수든 도구로 전환하고, 자동 스키마 생성과 Pydantic 기반 검증 제공 -- 트레이싱: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 증류 도구를 활용할 수 있는 내장 트레이싱 +- Agent loop: 도구 호출, 결과를 LLM 에 전달, LLM 이 완료될 때까지 반복을 처리하는 루프가 내장 +- 파이썬 우선: 새로운 추상화를 배울 필요 없이, 언어의 기본 기능만으로 에이전트를 오케스트레이션하고 체이닝 +- 핸드오프: 여러 에이전트 간 조정과 위임을 가능하게 하는 강력한 기능 +- 가드레일: 에이전트와 병렬로 입력 검증과 점검을 실행하며, 점검이 실패하면 조기 중단 +- 세션: 에이전트 실행 간 대화 내역을 자동으로 관리하여 수동 상태 관리 제거 +- 함수 도구: 어떤 Python 함수든 자동 스키마 생성과 Pydantic 기반 검증으로 도구로 전환 +- 트레이싱: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI 제품군의 평가, 파인튜닝 및 지식 증류 도구를 활용할 수 있게 해주는 기능 내장 ## 설치 diff --git a/docs/ko/mcp.md b/docs/ko/mcp.md index ba6d60469..6a7838d67 100644 --- a/docs/ko/mcp.md +++ b/docs/ko/mcp.md @@ -4,34 +4,35 @@ search: --- # Model context protocol (MCP) -[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP)은 애플리케이션이 도구와 컨텍스트를 언어 모델에 노출하는 방식을 표준화합니다. 공식 문서에서 인용합니다: +[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP)은 애플리케이션이 도구와 컨텍스트를 언어 모델에 노출하는 방식을 표준화합니다. 공식 문서에서: -> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각해 보세요. USB‑C가 다양한 주변기기와 액세서리에 기기를 표준 방식으로 연결해 주듯이, MCP는 AI 모델을 서로 다른 데이터 소스와 도구에 표준 방식으로 연결해 줍니다. +> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각해 보세요. +> USB‑C가 다양한 주변기기와 액세서리에 장치를 표준 방식으로 연결하듯이, MCP는 AI 모델을 다양한 데이터 소스와 도구에 표준 방식으로 연결합니다. -Agents Python SDK는 여러 MCP 트랜스포트를 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 직접 구축하여 파일 시스템, HTTP, 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. +Agents Python SDK는 여러 MCP 전송 방식을 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 자체 서버를 구축하여 파일 시스템, HTTP, 또는 커넥터 기반 도구를 에이전트에 노출할 수 있습니다. ## 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] | +| 로컬 또는 원격으로 실행 중인 Streamable HTTP 서버에 연결하기 | **Streamable HTTP MCP 서버** via [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| Server-Sent Events 를 구현한 서버와 통신하기 | **HTTP with SSE MCP 서버** via [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| 로컬 프로세스를 실행하고 stdin/stdout 으로 통신하기 | **stdio MCP 서버** via [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -아래 섹션에서는 각 옵션, 설정 방법, 그리고 어떤 상황에서 특정 트랜스포트를 선호해야 하는지 안내합니다. +아래 섹션에서는 각 옵션을 살펴보고, 구성 방법과 언제 어떤 전송 방식을 선호해야 하는지 설명합니다. ## 1. 호스티드 MCP 서버 도구 -Hosted tools 는 전체 도구 왕복을 OpenAI 인프라로 위임합니다. 코드에서 도구를 나열하고 호출하는 대신, -[`HostedMCPTool`][agents.tool.HostedMCPTool] 이 서버 라벨(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은 원격 서버의 도구를 나열하고, Python 프로세스로의 추가 콜백 없이 도구를 호출합니다. Hosted tools 는 현재 Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 동작합니다. +호스티드 툴은 전체 도구 왕복 처리를 OpenAI 인프라로 이전합니다. 코드에서 도구를 나열하고 호출하는 대신, +[`HostedMCPTool`][agents.tool.HostedMCPTool]이 서버 레이블(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은 원격 서버의 도구를 나열하고 Python 프로세스로의 추가 콜백 없이 이를 호출합니다. 호스티드 툴은 현재 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 @@ -59,11 +60,11 @@ async def main() -> None: asyncio.run(main()) ``` -호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers` 에 추가할 필요가 없습니다. +호스티드 서버는 도구를 자동으로 노출합니다. `mcp_servers`에 추가할 필요가 없습니다. -### 호스티드 MCP 결과 스트리밍 +### 스트리밍 호스티드 MCP 결과 -Hosted tools 는 함수 도구와 정확히 동일한 방식으로 스트리밍 결과를 지원합니다. 모델이 계속 실행되는 동안 증분 MCP 출력을 소비하려면 `Runner.run_streamed` 에 `stream=True` 를 전달하세요: +호스티드 툴은 함수 도구와 정확히 동일한 방식으로 스트리밍 결과를 지원합니다. 모델이 아직 작업 중일 때 점진적인 MCP 출력을 소비하려면 `Runner.run_streamed`에 `stream=True`를 전달하세요: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -75,7 +76,8 @@ 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 @@ -103,11 +105,12 @@ agent = Agent( ) ``` -콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행하기 위해 승인 데이터가 필요할 때마다 호출됩니다. +콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행하는 데 필요한 승인 데이터가 필요할 때마다 호출됩니다. ### 커넥터 기반 호스티드 서버 -호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url` 을 지정하는 대신 `connector_id` 와 액세스 토큰을 제공하세요. Responses API가 인증을 처리하고, 호스티드 서버가 커넥터의 도구를 노출합니다. +호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. +Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다. ```python import os @@ -123,13 +126,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 @@ -164,17 +167,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 @@ -203,7 +206,8 @@ 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 @@ -231,11 +235,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 @@ -253,11 +257,12 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names` 와 `blocked_tool_names` 가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. +`allowed_tool_names`와 `blocked_tool_names`가 모두 제공된 경우 SDK는 허용 목록을 먼저 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. ### 동적 도구 필터링 -보다 정교한 로직이 필요하다면 [`ToolFilterContext`][agents.mcp.ToolFilterContext] 를 받는 호출 가능 객체를 전달하세요. 이 호출 가능 객체는 동기 또는 비동기일 수 있으며, 도구를 노출해야 할 때 `True` 를 반환합니다. +더 정교한 로직이 필요한 경우 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 callable을 전달하세요. 이 callable은 +동기 또는 비동기일 수 있으며, 도구를 노출해야 할 때 `True`를 반환합니다. ```python from pathlib import Path @@ -281,14 +286,15 @@ 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 @@ -308,19 +314,20 @@ 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 트레이싱 스크린샷](../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 4cce5ede8..5fe8ed6f3 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,20 +4,20 @@ search: --- # 모델 -Agents SDK 는 두 가지 방식으로 OpenAI 모델을 기본 지원합니다: +Agents SDK 는 OpenAI 모델을 두 가지 방식으로 바로 지원합니다: - **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API 를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] - [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API 를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] ## OpenAI 모델 -`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)이며, 에이전트 워크플로에 적합한 예측 가능성과 낮은 지연 시간의 균형을 제공합니다. +`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)로, 에이전틱 워크플로에 대한 예측 가능성과 낮은 지연 시간의 균형이 우수합니다. -[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) 같은 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요. +[`gpt-5`](https://platform.openai.com/docs/models/gpt-5) 등의 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요. ### 기본 OpenAI 모델 -사용자가 사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 일관되게 특정 모델을 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -26,9 +26,9 @@ python3 my_awesome_agent.py #### GPT-5 모델 -GPT-5 의 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 모델 -대부분의 다른 비 OpenAI 모델은 [LiteLLM 통합](./litellm.md)을 통해 사용할 수 있습니다. 먼저 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가지가 있습니다(예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) 참고): +다른 LLM 공급자를 다음의 3가지 방법으로 더 연동할 수 있습니다(예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있음): -1. [`set_default_openai_client`][agents.set_default_openai_client] 는 전역적으로 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 사용하려는 경우에 유용합니다. 이는 LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고, `base_url` 과 `api_key` 를 설정할 수 있는 경우입니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) 를 참고하세요. -2. [`ModelProvider`][agents.models.interface.ModelProvider] 는 `Runner.run` 수준에서 적용됩니다. 이를 통해 “이 실행(run)에서 모든 에이전트에 사용자 지정 모델 제공자를 사용”하도록 설정할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) 를 참고하세요. -3. [`Agent.model`][agents.agent.Agent.model] 을 사용하면 특정 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/model 을 사용합니다. LLM 공급자가 Responses 를 지원한다면 Responses 사용을 권장합니다. ## 모델 혼합 및 매칭 -하나의 워크플로에서 에이전트마다 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류(트리아지)에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다: +하나의 워크플로 내에서 에이전트마다 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 초기 분류에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다: 1. 모델 이름을 전달 -2. 모델 이름 + 해당 이름을 Model 인스턴스에 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 를 전달 +2. 임의의 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달 3. [`Model`][agents.models.interface.Model] 구현을 직접 제공 !!!note - SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 두 가지 모델 형태를 모두 지원하지만, 두 형태가 지원하는 기능과 도구 세트가 다르므로 워크플로마다 단일 모델 형태를 사용할 것을 권장합니다. 워크플로에 서로 다른 모델 형태의 혼합이 필요하다면, 사용하는 모든 기능이 양쪽에서 모두 제공되는지 확인하세요. + 우리 SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 두 형태 모두를 지원하지만, 두 형태는 지원하는 기능과 도구 세트가 다르므로 워크플로마다 단일 모델 형태를 사용할 것을 권장합니다. 워크플로가 모델 형태의 혼합을 요구하는 경우, 사용하는 모든 기능이 두 형태 모두에서 사용 가능한지 확인하세요. ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -125,7 +125,7 @@ async def main(): 1. OpenAI 모델의 이름을 직접 설정합니다 2. [`Model`][agents.models.interface.Model] 구현을 제공합니다 -에이전트에 사용되는 모델을 더 세밀하게 구성하려면, 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 공급자 사용 시 일반적인 문제 ### 트레이싱 클라이언트 오류 401 -트레이싱 관련 오류가 발생한다면, 이는 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 다음 중 하나입니다: +트레이싱 관련 오류가 발생한다면, 이는 trace 가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 다음 세 가지입니다: -1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] -2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며, 반드시 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다 -3. 비 OpenAI 트레이스 프로세서를 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 를 참고하세요 +1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled] +2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며, 반드시 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다 +3. 비 OpenAI trace 프로세서를 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 를 참조하세요 ### Responses API 지원 -SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 이로 인해 404 등의 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다: +SDK 는 기본적으로 Responses API 를 사용하지만, 대부분의 다른 LLM 공급자는 아직 이를 지원하지 않습니다. 그 결과 404 같은 문제가 발생할 수 있습니다. 해결하려면 다음 두 가지 옵션이 있습니다: -1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 를 호출하세요. 이는 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우에 동작합니다 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 을 사용하세요. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) 에 있습니다 +1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 를 호출하세요. 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우에 동작합니다 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 을 사용하세요. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다 -### Structured outputs 지원 +### structured outputs 지원 -일부 모델 제공자는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 를 지원하지 않습니다. 이로 인해 다음과 유사한 오류가 발생할 수 있습니다: +일부 모델 공급자는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 를 지원하지 않습니다. 이로 인해 다음과 유사한 오류가 발생할 수 있습니다: ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -이는 일부 모델 제공자의 한계입니다. 그들은 JSON 출력을 지원하지만, 출력에 사용할 `json_schema` 를 지정할 수는 없습니다. 이에 대한 해결책을 마련 중이지만, 가능하면 JSON schema 출력을 지원하는 제공자를 사용하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 깨질 수 있습니다. +이는 일부 모델 공급자의 한계입니다. JSON 출력을 지원하지만, 출력에 사용할 `json_schema` 를 지정하도록 허용하지 않습니다. 이에 대한 해결책을 마련하고 있지만, JSON schema 출력을 지원하는 공급자에 의존할 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 실패할 수 있습니다. -## 제공자 간 모델 혼합 +## 공급자 간 모델 혼합 -모델 제공자 간 기능 차이에 유의하지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 다른 많은 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유념하세요: +모델 공급자 간 기능 차이를 인지하지 못하면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 많은 다른 공급자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요: -- 지원하지 않는 제공자에게 해당 `tools` 를 보내지 말 것 -- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링할 것 -- 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 eb5e21117..64640cb18 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 issues](https://github.com/openai/openai-agents-python/issues)를 통해 문제를 보고해 주시면 신속히 수정하겠습니다. -[LiteLLM](https://docs.litellm.ai/docs/) 은 단일 인터페이스로 100개 이상의 모델을 사용할 수 있게 해주는 라이브러리입니다. Agents SDK 에서 어떤 AI 모델이든 사용할 수 있도록 LiteLLM 통합을 추가했습니다. +[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 문서](https://docs.litellm.ai/docs/providers)를 참조하세요. +LiteLLM에서 지원하는 전체 모델 목록은 [litellm providers docs](https://docs.litellm.ai/docs/providers)를 참조하세요. ```python from __future__ import annotations @@ -78,7 +78,7 @@ if __name__ == "__main__": ## 사용량 데이터 추적 -LiteLLM 응답이 Agents SDK 사용량 메트릭에 집계되도록 하려면, 에이전트를 생성할 때 `ModelSettings(include_usage=True)` 를 전달하세요. +LiteLLM 응답이 Agents SDK 사용량 지표에 채워지도록 하려면, 에이전트를 생성할 때 `ModelSettings(include_usage=True)`를 전달하세요. ```python from agents import Agent, ModelSettings @@ -91,4 +91,4 @@ agent = Agent( ) ``` -`include_usage=True` 를 사용하면, LiteLLM 요청은 기본 제공 OpenAI 모델과 마찬가지로 `result.context_wrapper.usage` 를 통해 토큰 및 요청 수를 보고합니다. \ No newline at end of file +`include_usage=True`를 사용하면, LiteLLM 요청은 기본 제공 OpenAI 모델과 마찬가지로 `result.context_wrapper.usage`를 통해 토큰 및 요청 수를 보고합니다. \ No newline at end of file diff --git a/docs/ko/multi_agent.md b/docs/ko/multi_agent.md index 1e7d398ac..4bd39604d 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 기반 오케스트레이션이 강력하긴 하지만, 코드 기반 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정적이고 예측 가능하게 만듭니다. 일반적인 패턴은 다음과 같습니다: -- [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)에는 여러 코드 예제가 있습니다. \ No newline at end of file +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) 에 여러 code examples 가 있습니다. \ No newline at end of file diff --git a/docs/ko/quickstart.md b/docs/ko/quickstart.md index 12e00b4b5..34a85a323 100644 --- a/docs/ko/quickstart.md +++ b/docs/ko/quickstart.md @@ -4,9 +4,9 @@ search: --- # 빠른 시작 -## 프로젝트와 가상 환경 생성 +## 프로젝트 및 가상 환경 생성 -이 작업은 한 번만 수행하면 됩니다. +한 번만 수행하면 됩니다. ```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)를 따라 주세요. +API 키가 없다면, 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( ## 에이전트 오케스트레이션 실행 -워크플로가 실행되고 트리아지 에이전트가 두 전문 에이전트 사이를 올바르게 라우팅하는지 확인해 봅시다. +워크플로가 실행되고 트리아지 에이전트가 두 전문 에이전트 간에 올바르게 라우팅하는지 확인해 봅시다. ```python from agents import Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 모두 합쳐 실행하기 +## 전체 구성 실행 -모든 것을 합쳐, 핸드오프와 입력 가드레일을 사용해 전체 워크플로를 실행해 봅시다. +모든 것을 합쳐서 핸드오프와 입력 가드레일을 사용하여 전체 워크플로를 실행해 봅시다. ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 트레이스 보기 +## 트레이스 확인 -에이전트 실행 중에 일어난 일을 검토하려면 [OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동해 에이전트 실행의 트레이스를 확인하세요. +에이전트 실행 중에 발생한 내용을 검토하려면 [OpenAI 대시보드의 Trace viewer](https://platform.openai.com/traces)로 이동하여 실행 트레이스를 확인하세요. ## 다음 단계 -더 복잡한 에이전트형 플로우를 만드는 방법을 살펴보세요: +더 복잡한 에이전트 플로를 만드는 방법을 알아보세요: -- [Agents](agents.md)를 구성하는 방법 알아보기 -- [에이전트 실행](running_agents.md)에 대해 알아보기 -- [tools](tools.md), [guardrails](guardrails.md), [models](models/index.md)에 대해 알아보기 \ No newline at end of file +- [에이전트](agents.md) 구성 방법을 알아보세요. +- [에이전트 실행](running_agents.md)에 대해 알아보세요. +- [도구](tools.md), [가드레일](guardrails.md), [모델](models/index.md)에 대해 알아보세요. \ No newline at end of file diff --git a/docs/ko/realtime/guide.md b/docs/ko/realtime/guide.md index f3635bc19..10af33afd 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 "베타 기능" -실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 하위 호환이 깨지는 변경이 있을 수 있습니다. +실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 하위 호환성이 깨지는 변경이 있을 수 있습니다. ## 개요 -실시간 에이전트는 대화형 플로우를 가능하게 하며, 오디오와 텍스트 입력을 실시간으로 처리하고 실시간 오디오로 응답합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 낮은 지연으로 자연스러운 음성 대화를 제공하고, 인터럽션(중단 처리)을 우아하게 처리할 수 있습니다. +실시간 에이전트는 대화형 흐름을 지원하여 오디오와 텍스트 입력을 실시간으로 처리하고 실시간 오디오로 응답합니다. OpenAI의 Realtime API와 지속적인 연결을 유지하여 낮은 지연 시간으로 자연스러운 음성 대화를 가능하게 하고 인터럽션(중단 처리)을 우아하게 처리합니다. ## 아키텍처 -### 핵심 구성요소 +### 핵심 구성 요소 -실시간 시스템은 다음과 같은 핵심 구성요소로 이루어져 있습니다: +실시간 시스템은 다음의 주요 구성 요소로 이루어집니다: -- **RealtimeAgent**: instructions, tools 및 핸드오프로 구성된 에이전트 +- **RealtimeAgent**: instructions, tools 및 handoffs 로 구성된 에이전트 - **RealtimeRunner**: 구성을 관리합니다. `runner.run()`을 호출해 세션을 얻을 수 있습니다. -- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자가 대화를 시작할 때마다 하나를 만들고, 대화가 끝날 때까지 유지합니다. +- **RealtimeSession**: 단일 상호작용 세션입니다. 일반적으로 사용자 가 대화를 시작할 때마다 하나씩 생성하고, 대화가 끝날 때까지 유지합니다. - **RealtimeModel**: 기본 모델 인터페이스(일반적으로 OpenAI의 WebSocket 구현) ### 세션 흐름 -일반적인 실시간 세션은 다음 흐름을 따릅니다: +일반적인 실시간 세션 흐름은 다음과 같습니다: -1. instructions, tools 및 핸드오프로 **RealtimeAgent(들)를 생성**합니다. +1. instructions, tools 및 handoffs 와 함께 **RealtimeAgent(들)을 생성**합니다 2. 에이전트와 구성 옵션으로 **RealtimeRunner를 설정**합니다 -3. `await runner.run()`을 사용해 **세션을 시작**하고 RealtimeSession을 반환받습니다. -4. `send_audio()` 또는 `send_message()`를 사용해 **오디오 또는 텍스트 메시지 전송**합니다 -5. 세션을 순회(iterate)하여 **이벤트를 수신**합니다 - 이벤트에는 오디오 출력, 전사, 도구 호출, 핸드오프, 오류가 포함됩니다 -6. 사용자가 에이전트 말 위로 말할 때 **인터럽션 처리**를 수행합니다. 이는 현재 오디오 생성을 자동으로 중지합니다 +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 output 지원이 없습니다(`outputType`은 지원되지 않음). -- 음성(voice)은 에이전트별로 구성할 수 있지만 첫 번째 에이전트가 말하기 시작한 후에는 변경할 수 없습니다. -- 그 외 tools, 핸드오프, instructions 등은 동일하게 동작합니다. +- 모델 선택은 에이전트 레벨이 아니라 세션 레벨에서 구성합니다 +- structured outputs 지원 없음(`outputType` 지원되지 않음) +- 음성은 에이전트별로 설정할 수 있지만, 최초 발화 이후에는 변경할 수 없습니다 +- tools, handoffs, 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,22 +119,22 @@ main_agent = RealtimeAgent( ## 이벤트 처리 -세션은 세션 객체를 순회하여 수신할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작 및 종료, 에이전트 핸드오프, 오류가 포함됩니다. 처리해야 할 주요 이벤트는 다음과 같습니다: +세션은 세션 객체를 순회(iterate)하여 수신할 수 있는 이벤트를 스트리밍합니다. 이벤트에는 오디오 출력 청크, 전사 결과, 도구 실행 시작/종료, 에이전트 핸드오프, 오류 등이 포함됩니다. 다음의 핵심 이벤트를 처리하세요: - **audio**: 에이전트 응답의 원문 오디오 데이터 -- **audio_end**: 에이전트가 말을 마침 -- **audio_interrupted**: 사용자가 에이전트를 인터럽션(중단 처리) +- **audio_end**: 에이전트 발화 종료 +- **audio_interrupted**: 사용자가 에이전트를 중단함 - **tool_start/tool_end**: 도구 실행 라이프사이클 - **handoff**: 에이전트 핸드오프 발생 - **error**: 처리 중 오류 발생 -완전한 이벤트 세부 정보는 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]를 참고하세요. +전체 이벤트 세부 정보는 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]를 참조하세요. ## 가드레일 -실시간 에이전트는 출력 가드레일만 지원합니다. 이러한 가드레일은 디바운스되어(매 단어마다가 아니라) 주기적으로 실행되어 실시간 생성 중 성능 문제를 피합니다. 기본 디바운스 길이는 100자이며, 구성 가능합니다. +실시간 에이전트는 출력 가드레일만 지원합니다. 성능 문제를 피하기 위해 실시간 생성 중 매 단어마다가 아니라 디바운싱되어 주기적으로 실행됩니다. 기본 디바운스 길이는 100자이며, 구성 가능합니다. -가드레일은 `RealtimeAgent`에 직접 연결하거나 세션의 `run_config`를 통해 제공할 수 있습니다. 두 소스의 가드레일은 함께 실행됩니다. +가드레일은 `RealtimeAgent` 에 직접 연결하거나 세션의 `run_config` 를 통해 제공할 수 있습니다. 두 소스의 가드레일은 함께 실행됩니다. ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,13 +152,13 @@ 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` 이벤트를 반드시 수신하세요. ## 모델 직접 액세스 @@ -173,4 +173,4 @@ session.model.add_listener(my_custom_listener) ## 코드 예제 -완전한 동작 code examples는 [examples/realtime 디렉터리](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)를 참고하세요. UI 구성 요소가 있는 데모와 없는 데모가 모두 포함되어 있습니다. \ 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 cba0c3089..7f0aa7d26 100644 --- a/docs/ko/realtime/quickstart.md +++ b/docs/ko/realtime/quickstart.md @@ -4,12 +4,12 @@ search: --- # 빠른 시작 -실시간 에이전트를 사용하면 OpenAI의 Realtime API로 AI 에이전트와 음성 대화를 할 수 있습니다. 이 가이드는 첫 번째 실시간 음성 에이전트를 만드는 과정을 안내합니다. +실시간 에이전트는 OpenAI의 Realtime API를 사용해 AI 에이전트와 음성 대화를 가능하게 합니다. 이 가이드는 첫 실시간 음성 에이전트를 만드는 과정을 안내합니다. !!! warning "베타 기능" -실시간 에이전트는 베타 단계입니다. 구현을 개선하는 과정에서 호환성에 영향을 주는 변경이 있을 수 있습니다. +실시간 에이전트는 베타 상태입니다. 구현을 개선하는 동안 일부 깨지는 변경이 있을 수 있습니다. -## 사전 준비 사항 +## 사전 준비 - Python 3.9 이상 - OpenAI API 키 @@ -23,9 +23,9 @@ search: pip install openai-agents ``` -## 첫 번째 실시간 에이전트 만들기 +## 첫 실시간 에이전트 생성 -### 1. 필요한 구성요소 임포트 +### 1. 필수 구성요소 가져오기 ```python import asyncio @@ -109,7 +109,7 @@ def _truncate_str(s: str, max_length: int) -> str: return s ``` -## 전체 예제 +## 완성 예제 다음은 완전한 동작 예제입니다: @@ -200,26 +200,26 @@ if __name__ == "__main__": - `input_audio_format`: 입력 오디오 형식 (`pcm16`, `g711_ulaw`, `g711_alaw`) - `output_audio_format`: 출력 오디오 형식 -- `input_audio_transcription`: 음성 인식 구성 +- `input_audio_transcription`: 전사(Transcription) 구성 ### 턴 감지 -- `type`: 감지 방식 (`server_vad`, `semantic_vad`) +- `type`: 감지 방법 (`server_vad`, `semantic_vad`) - `threshold`: 음성 활동 임계값 (0.0-1.0) -- `silence_duration_ms`: 턴 종료를 감지할 정적 시간 +- `silence_duration_ms`: 턴 종료를 감지할 무음 지속 시간 - `prefix_padding_ms`: 발화 전 오디오 패딩 ## 다음 단계 -- [실시간 에이전트에 대해 더 알아보기](guide.md) -- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 폴더의 동작하는 code examples 확인 +- [실시간 에이전트 더 알아보기](guide.md) +- 동작하는 code examples 는 [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/ko/release.md b/docs/ko/release.md index 4a9d14485..af5f53d8e 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`를 인자(arg)로 받던 몇몇 위치가 이제 `AgentBase`를 인자(arg)로 받습니다. 예: 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`라는 두 개의 새 params가 추가되었습니다. `MCPServer`를 상속하는 모든 클래스에 이 params를 추가해야 합니다. \ No newline at end of file +이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 새로운 매개변수 `run_context`와 `agent`가 추가되었습니다. `MCPServer`를 상속하는 모든 클래스에 이 매개변수를 추가해야 합니다. \ No newline at end of file diff --git a/docs/ko/repl.md b/docs/ko/repl.md index 45bd48ac2..50554e7ff 100644 --- a/docs/ko/repl.md +++ b/docs/ko/repl.md @@ -4,7 +4,8 @@ search: --- # REPL 유틸리티 -SDK는 터미널에서 에이전트 동작을 빠르고 인터랙티브하게 테스트할 수 있는 `run_demo_loop`를 제공합니다. +SDK는 터미널에서 에이전트의 동작을 빠르고 대화형으로 테스트할 수 있도록 `run_demo_loop` 를 제공합니다. + ```python import asyncio @@ -18,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop`는 루프에서 사용자 입력을 요청하고, 턴 사이의 대화 기록을 유지합니다. 기본적으로 생성되는 대로 모델 출력을 스트리밍합니다. 위 예제를 실행하면, run_demo_loop가 인터랙티브 채팅 세션을 시작합니다. 지속적으로 입력을 요청하고, 턴 사이의 전체 대화 기록을 기억하여(에이전트가 논의된 내용을 알 수 있도록) 생성되는 즉시 에이전트의 응답을 실시간으로 자동 스트리밍합니다. +`run_demo_loop` 는 루프에서 사용자 입력을 요청하며, 턴 사이의 대화 기록을 유지합니다. 기본적으로 생성되는 대로 모델 출력을 스트리밍합니다. 위 예제를 실행하면, `run_demo_loop` 가 대화형 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 사이의 전체 대화 기록을 기억하여(그래서 에이전트가 논의된 내용을 알고) 생성되는 대로 에이전트의 응답을 실시간으로 자동 스트리밍합니다. -채팅 세션을 종료하려면 `quit` 또는 `exit`를 입력하고 Enter를 누르거나 `Ctrl-D` 키보드 단축키를 사용하세요. \ No newline at end of file +이 채팅 세션을 종료하려면 `quit` 또는 `exit` 를 입력하고 Enter 키를 누르거나 `Ctrl-D` 키보드 단축키를 사용하면 됩니다. \ No newline at end of file diff --git a/docs/ko/results.md b/docs/ko/results.md index 67c5f8b3a..8efcb6fa8 100644 --- a/docs/ko/results.md +++ b/docs/ko/results.md @@ -6,51 +6,51 @@ search: `Runner.run` 메서드를 호출하면 다음 중 하나를 받습니다: -- `run` 또는 `run_sync`를 호출한 경우 [`RunResult`][agents.result.RunResult] -- `run_streamed`를 호출한 경우 [`RunResultStreaming`][agents.result.RunResultStreaming] +- [`RunResult`][agents.result.RunResult] (`run` 또는 `run_sync` 호출 시) +- [`RunResultStreaming`][agents.result.RunResultStreaming] (`run_streamed` 호출 시) -이 두 가지는 모두 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, 대부분의 유용한 정보가 여기에 포함됩니다. +두 타입 모두 대부분의 유용한 정보가 들어 있는 [`RunResultBase`][agents.result.RunResultBase]를 상속합니다. ## 최종 출력 -[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이는 다음 중 하나입니다: +[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이는 다음 중 하나입니다: -- 마지막 에이전트에 `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 bb9053121..42575ff30 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] 클래스로 실행할 수 있습니다. 선택지는 3가지입니다: -1. [`Runner.run()`][agents.run.Runner.run]: 비동기 실행이며 [`RunResult`][agents.result.RunResult] 를 반환 +1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult] 를 반환 2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드로 내부적으로 `.run()` 을 실행 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기 실행이며 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환. LLM 을 스트리밍 모드로 호출하고, 수신되는 이벤트를 실시간으로 스트리밍 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming] 을 반환. LLM 을 스트리밍 모드로 호출하고, 수신되는 대로 이벤트를 스트리밍 ```python from agents import Agent, Runner @@ -23,55 +23,55 @@ async def main(): # Infinite loop's dance ``` -자세한 내용은 [결과 가이드](results.md)에서 확인하세요. +자세한 내용은 [결과 가이드](results.md)를 참조하세요. ## 에이전트 루프 -`Runner` 의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API 의 아이템 목록일 수 있습니다. +`Runner` 의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 문자열(사용자 메시지로 간주) 또는 OpenAI Responses API 의 입력 아이템 목록일 수 있습니다. -Runner 는 다음과 같은 루프를 실행합니다: +러너는 다음과 같은 루프를 실행합니다: -1. 현재 에이전트와 현재 입력으로 LLM 을 호출 -2. LLM 이 출력 생성 - 1. LLM 이 `final_output` 을 반환하면 루프를 종료하고 결과 반환 - 2. LLM 이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프 재실행 - 3. LLM 이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프 재실행 +1. 현재 입력으로 현재 에이전트에 대해 LLM 을 호출 +2. LLM 이 출력을 생성 + 1. LLM 이 `final_output` 을 반환하면 루프를 종료하고 결과를 반환 + 2. LLM 이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 재실행 + 3. LLM 이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프를 재실행 3. 전달된 `max_turns` 를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생 !!! note - LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고, 도구 호출이 없을 때입니다. + LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없을 때입니다. ## 스트리밍 -스트리밍을 사용하면 LLM 이 실행되는 동안 스트리밍 이벤트를 추가로 수신할 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming] 에는 실행에 대한 모든 정보와 새로 생성된 출력이 포함됩니다. 스트리밍 이벤트는 `.stream_events()` 로 호출할 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요. +스트리밍을 사용하면 LLM 이 실행되는 동안 스트리밍 이벤트를 추가로 수신할 수 있습니다. 스트림이 끝나면 [`RunResultStreaming`][agents.result.RunResultStreaming] 에는 실행에 대한 모든 새로운 출력 등을 포함한 완전한 정보가 담깁니다. 스트리밍 이벤트는 `.stream_events()` 를 호출하면 됩니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참조하세요. ## 실행 구성 -`run_config` 매개변수로 에이전트 실행의 전역 설정을 구성할 수 있습니다: +`run_config` 매개변수로 에이전트 실행에 대한 전역 설정을 구성할 수 있습니다: -- [`model`][agents.run.RunConfig.model]: 각 Agent 의 `model` 설정과 무관하게 사용할 전역 LLM 모델을 설정 -- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회를 위한 모델 제공자, 기본값은 OpenAI -- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의. 예를 들어 전역 `temperature` 또는 `top_p` 를 설정 가능 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 대한 전역 입력 필터. 해당 핸드오프에 이미 필터가 없을 때 적용. 입력 필터를 통해 새 에이전트로 전송되는 입력을 편집할 수 있음. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md) 비활성화 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM 및 도구 호출의 입력/출력 등 민감할 수 있는 데이터를 트레이스에 포함할지 여부를 구성 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, 트레이스 ID, 트레이스 그룹 ID 설정. 최소한 `workflow_name` 설정을 권장. 그룹 ID 는 선택 사항으로 여러 실행에 걸쳐 트레이스를 연결 가능 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터 +- [`model`][agents.run.RunConfig.model]: 각 Agent 의 `model` 과 무관하게 사용할 전역 LLM 모델을 설정 +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회를 위한 모델 제공자, 기본값은 OpenAI +- [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의. 예: 전역 `temperature` 또는 `top_p` 설정 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 입력 필터가 없는 경우 적용할 전역 입력 필터. 새 에이전트에 전달되는 입력을 편집할 수 있음. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참조 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md) 비활성화 +- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: 트레이스에 LLM 및 도구 호출 입력/출력 등 잠재적으로 민감한 데이터를 포함할지 구성 +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행에 대한 트레이싱 워크플로 이름, 트레이스 ID, 트레이스 그룹 ID 설정. 최소한 `workflow_name` 설정을 권장. 그룹 ID 는 여러 실행에 걸쳐 트레이스를 연결할 수 있는 선택 필드 +- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 트레이스에 포함할 메타데이터 ## 대화/채팅 스레드 -어떤 run 메서드를 호출하든 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출), 이는 채팅 대화에서 하나의 논리적 턴을 의미합니다. 예: +어떤 run 메서드를 호출하든 하나 이상의 에이전트가 실행될 수 있으며(따라서 하나 이상의 LLM 호출), 이는 채팅 대화의 단일 논리적 턴을 나타냅니다. 예: 1. 사용자 턴: 사용자가 텍스트 입력 -2. Runner 실행: 첫 번째 에이전트가 LLM 을 호출하고 도구를 실행한 뒤 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 더 많은 도구를 실행하고 출력을 생성 +2. 러너 실행: 첫 번째 에이전트가 LLM 을 호출하고 도구를 실행하며 두 번째 에이전트로 핸드오프, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성 -에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어, 에이전트들이 생성한 모든 새 아이템을 보여주거나 최종 출력만 보여줄 수 있습니다. 이후 사용자가 후속 질문을 할 수 있으며, 이때 다시 run 메서드를 호출하면 됩니다. +에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새로운 아이템을 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 그러면 run 메서드를 다시 호출하면 됩니다. ### 수동 대화 관리 -다음 턴의 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용하여 대화 내역을 수동으로 관리할 수 있습니다: +다음 턴의 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용하여 대화 기록을 수동으로 관리할 수 있습니다: ```python async def main(): @@ -91,9 +91,9 @@ async def main(): # California ``` -### 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 는 자동으로 다음을 수행합니다: +세션은 자동으로 다음을 수행합니다: -- 각 실행 전에 대화 내역을 가져옴 -- 각 실행 후 새 메시지를 저장 -- 다른 세션 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 의 대화 상태 기능에 서버 측 대화 상태 관리를 맡길 수도 있습니다. 이렇게 하면 모든 과거 메시지를 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 자세한 내용은 [OpenAI Conversation state 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. OpenAI 는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다: #### 1. `conversation_id` 사용 -먼저 OpenAI Conversations API 를 사용해 대화를 생성한 뒤, 이후의 모든 호출에서 해당 ID 를 재사용합니다: +먼저 OpenAI Conversations API 로 대화를 생성한 뒤 이후 모든 호출에서 해당 ID 를 재사용합니다: ```python from agents import Agent, Runner @@ -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 @@ -192,16 +192,16 @@ async def main(): ## 장기 실행 에이전트 및 휴먼인더루프 (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]: 에이전트 실행이 `max_turns` 한도를 초과하면 발생. `Runner.run`, `Runner.run_sync`, `Runner.run_streamed` 메서드에 적용. 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냄 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 기본 모델(LLM)이 예기치 않거나 잘못된 출력을 생성할 때 발생. 다음을 포함할 수 있음: + - 잘못된 JSON: 모델이 도구 호출 또는 직접 출력에서 잘못된 JSON 구조를 제공하는 경우, 특히 특정 `output_type` 이 정의된 경우 + - 예기치 않은 도구 관련 실패: 모델이 예상 방식으로 도구를 사용하지 못한 경우 +- [`UserError`][agents.exceptions.UserError]: SDK 를 사용하는 코드 작성자(사용자)가 SDK 사용 중 오류를 만들 때 발생. 잘못된 코드 구현, 잘못된 구성, SDK API 오용 등에서 발생 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 각각 입력 가드레일 또는 출력 가드레일의 조건이 충족될 때 발생. 입력 가드레일은 처리 전에 수신 메시지를 검사하고, 출력 가드레일은 에이전트의 최종 응답을 전달하기 전에 검사 \ No newline at end of file diff --git a/docs/ko/sessions.md b/docs/ko/sessions.md index cfe574a1a..25587494e 100644 --- a/docs/ko/sessions.md +++ b/docs/ko/sessions.md @@ -4,9 +4,9 @@ search: --- # 세션 -Agents SDK 는 여러 에이전트 실행(run) 간에 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에 `.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 @@ -86,9 +86,9 @@ print(last_item) # {"role": "assistant", "content": "Hi there!"} await session.clear_session() ``` -### 수정 시 pop_item 사용 +### 수정을 위한 pop_item 사용 -`pop_item` 메서드는 대화에서 마지막 항목을 되돌리거나 수정하려는 경우에 특히 유용합니다: +`pop_item` 메서드는 대화에서 마지막 아이템을 되돌리거나 수정하고 싶을 때 특히 유용합니다: ```python from agents import Agent, Runner, SQLiteSession @@ -119,7 +119,7 @@ print(f"Agent: {result.final_output}") ## 메모리 옵션 -### 메모리 없음(기본값) +### 메모리 사용 안 함(기본값) ```python # Default behavior - no session memory @@ -128,8 +128,8 @@ result = await Runner.run(agent, "Hello") ### OpenAI Conversations API 메모리 -[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 호스트하는 인프라에 이미 의존하고 있을 때 유용합니다. +[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 @@ -192,9 +192,9 @@ result2 = await Runner.run( 더 고급 사용 사례의 경우, SQLAlchemy 기반 세션 백엔드를 사용할 수 있습니다. 이를 통해 SQLAlchemy 가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 세션 저장소로 사용할 수 있습니다. -**예시 1: 인메모리 SQLite 와 `from_url` 사용** +**예시 1: `from_url` 을 사용한 인메모리 SQLite** -개발 및 테스트에 적합한 가장 간단한 시작 방법입니다. +가장 간단한 시작 방법으로, 개발 및 테스트에 적합합니다. ```python import asyncio @@ -217,7 +217,7 @@ if __name__ == "__main__": **예시 2: 기존 SQLAlchemy 엔진 사용** -프로덕션 애플리케이션에서는 SQLAlchemy `AsyncEngine` 인스턴스를 이미 보유하고 있을 가능성이 큽니다. 이를 세션에 직접 전달할 수 있습니다. +프로덕션 애플리케이션에서는 이미 SQLAlchemy `AsyncEngine` 인스턴스를 보유하고 있을 가능성이 큽니다. 이를 세션에 직접 전달할 수 있습니다. ```python import asyncio @@ -247,9 +247,9 @@ if __name__ == "__main__": ### 암호화된 세션 -보관 중인 대화 데이터의 암호화가 필요한 애플리케이션의 경우, `EncryptedSession` 을 사용하여 투명한 암호화와 자동 TTL 기반 만료로 어떤 세션 백엔드든 감쌀 수 있습니다. 이를 위해서는 `encrypt` extra 가 필요합니다: `pip install openai-agents[encrypt]`. +대화 데이터의 저장 시 암호화가 필요한 애플리케이션의 경우, `EncryptedSession` 을 사용하여 투명한 암호화와 자동 TTL 기반 만료를 갖춘 어떤 세션 백엔드라도 래핑할 수 있습니다. 이를 위해서는 `encrypt` 엑스트라가 필요합니다: `pip install openai-agents[encrypt]`. -`EncryptedSession` 은 세션별 키 파생(HKDF)이 적용된 Fernet 암호화를 사용하며, 오래된 메시지의 자동 만료를 지원합니다. 항목이 TTL을 초과하면 조회 시 조용히 건너뜁니다. +`EncryptedSession` 은 세션별 키 파생(HKDF)을 사용한 Fernet 암호화를 사용하며 오래된 메시지의 자동 만료를 지원합니다. 아이템이 TTL을 초과하면 검색 시 조용히 건너뜁니다. **예시: SQLAlchemy 세션 데이터 암호화** @@ -282,19 +282,19 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**주요 기능:** +**핵심 기능:** -- **투명한 암호화**: 저장 전 모든 세션 항목을 자동으로 암호화하고 조회 시 복호화 -- **세션별 키 파생**: 세션 ID 를 salt 로 사용하는 HKDF 로 고유한 암호화 키 파생 +- **투명한 암호화**: 저장 전에 모든 세션 아이템을 자동으로 암호화하고 검색 시 복호화 +- **세션별 키 파생**: 세션 ID 를 솔트로 사용하는 HKDF 로 고유한 암호화 키 파생 - **TTL 기반 만료**: 구성 가능한 time-to-live(기본값: 10분)에 따라 오래된 메시지를 자동 만료 - **유연한 키 입력**: Fernet 키 또는 원문 문자열을 암호화 키로 허용 -- **어떤 세션이든 래핑**: SQLite, SQLAlchemy, 또는 사용자 정의 세션 구현과 동작 +- **어떤 세션이든 래핑**: SQLite, SQLAlchemy 또는 커스텀 세션 구현과 함께 동작 !!! warning "중요한 보안 참고 사항" - - 암호화 키는 안전하게 저장하세요(예: 환경 변수, 시크릿 매니저) + - 암호화 키를 안전하게 저장하세요(예: 환경 변수, 시크릿 매니저) - 만료된 토큰은 애플리케이션 서버의 시스템 시계를 기준으로 거부됩니다 - 유효한 토큰이 시계 드리프트로 인해 거부되지 않도록 모든 서버가 NTP 로 시간 동기화되어 있는지 확인하세요 - - 기본 세션은 여전히 암호화된 데이터를 저장하므로 데이터베이스 인프라에 대한 제어권을 유지합니다 + - 기본 세션은 여전히 암호화된 데이터를 저장하므로 데이터베이스 인프라에 대한 제어권을 유지할 수 있습니다 ## 사용자 정의 메모리 구현 @@ -344,9 +344,9 @@ result = await Runner.run( ## 세션 관리 -### 세션 ID 네이밍 +### 세션 ID 명명 -대화를 체계적으로 정리할 수 있도록 의미 있는 세션 ID 를 사용하세요: +대화를 체계적으로 구성하는 데 도움이 되는 의미 있는 세션 ID 를 사용하세요: - 사용자 기반: `"user_12345"` - 스레드 기반: `"thread_abc123"` @@ -354,12 +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()`) 사용 -- 투명한 암호화와 TTL 기반 만료로 어떤 세션이든 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key")`) 사용 -- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 대한 사용자 정의 세션 백엔드 구현을 고려 +- 임시 대화에는 인메모리 SQLite (`SQLiteSession("session_id")`) 사용 +- 지속적 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- SQLAlchemy 가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 +- OpenAI Conversations API 에 기록을 저장하길 선호한다면 OpenAI 호스팅 저장소 (`OpenAIConversationsSession()`) 사용 +- 투명한 암호화와 TTL 기반 만료를 위해 어떤 세션이든 래핑하는 암호화 세션 (`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 +- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(Redis, Django 등)에 대한 커스텀 세션 백엔드 구현을 고려 ### 세션 관리 @@ -385,9 +385,9 @@ result2 = await Runner.run( ) ``` -## 전체 예시 +## 전체 예제 -다음은 세션 메모리가 실제로 동작하는 전체 예시입니다: +세션 메모리가 실제로 동작하는 전체 예제는 다음과 같습니다: ```python import asyncio @@ -457,4 +457,4 @@ if __name__ == "__main__": - [`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 +- [`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 d8bc808c6..bb07e72a6 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 72fe4ae86..28376817f 100644 --- a/docs/ko/tools.md +++ b/docs/ko/tools.md @@ -4,23 +4,23 @@ search: --- # 도구 -도구는 에이전트가 행동을 취할 수 있게 합니다. 예를 들어 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지 가능합니다. Agents SDK에는 세 가지 범주의 도구가 있습니다: +도구는 에이전트가 동작을 수행하도록 합니다. 예: 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용까지. Agents SDK 에는 세 가지 종류의 도구가 있습니다: -- 호스티드 툴: LLM 서버에서 AI 모델과 함께 실행됩니다. OpenAI는 리트리벌, 웹 검색 및 컴퓨터 사용을 호스티드 툴로 제공합니다. -- 함수 호출: 임의의 Python 함수를 도구로 사용할 수 있게 합니다. -- 도구로서의 에이전트: 에이전트를 도구로 사용하여 핸드오프 없이 다른 에이전트를 호출할 수 있습니다. +- 호스티드 툴: 이들은 AI 모델과 함께 LLM 서버에서 실행됩니다. OpenAI 는 retrieval, 웹 검색 및 컴퓨터 사용을 호스티드 툴로 제공합니다 +- 함수 호출: 임의의 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 함수의 이름이 됩니다(또는 이름을 직접 지정할 수 있음) +- 도구 설명은 함수의 docstring 에서 가져옵니다(또는 설명을 직접 지정할 수 있음) +- 함수 입력을 위한 스키마는 함수의 인자에서 자동으로 생성됩니다 +- 각 입력에 대한 설명은 비활성화하지 않는 한 함수의 docstring 에서 가져옵니다 -Python의 `inspect` 모듈로 함수 시그니처를 추출하고, 도크스트링 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/), 스키마 생성에는 `pydantic`을 사용합니다. +Python 의 `inspect` 모듈을 사용해 함수 시그니처를 추출하고, [`griffe`](https://mkdocstrings.github.io/griffe/) 로 docstring 을 파싱하며, 스키마 생성에는 `pydantic` 을 사용합니다. ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 함수의 인자로는 어떤 Python 타입이든 사용할 수 있으며, 함수는 동기 또는 비동기로 작성할 수 있습니다. -2. 도크스트링이 있다면 설명과 인자 설명을 추출하는 데 사용됩니다 -3. 선택적으로 `context`를 받을 수 있습니다(첫 번째 인자여야 함). 도구 이름, 설명, 사용할 도크스트링 스타일 등 다양한 override를 설정할 수 있습니다. -4. 데코레이터가 적용된 함수를 도구 목록에 전달할 수 있습니다. +1. 함수의 인자로 어떤 Python 타입이든 사용할 수 있으며, 함수는 동기 또는 비동기가 될 수 있습니다 +2. docstring 이 있으면 설명과 인자 설명을 추출하는 데 사용됩니다 +3. 함수는 선택적으로 `context` 를 받을 수 있습니다(첫 번째 인자여야 함). 또한 도구의 이름, 설명, 사용할 docstring 스타일 등과 같은 override 를 설정할 수 있습니다 +4. 데코레이터가 적용된 함수를 도구 목록에 전달하면 됩니다 -??? note "Expand to see output" +??? note "결과 보기" ``` fetch_weather @@ -177,14 +177,14 @@ for tool in agent.tools: } ``` -### 사용자 정의 함수 도구 +### 커스텀 함수 도구 -때때로 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 이 경우 직접 [`FunctionTool`][agents.tool.FunctionTool]을 생성할 수 있습니다. 다음을 제공해야 합니다: +때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 이럴 때는 직접 [`FunctionTool`][agents.tool.FunctionTool] 을 생성할 수 있습니다. 다음을 제공해야 합니다: - `name` - `description` -- 인자에 대한 JSON 스키마인 `params_json_schema` -- [`ToolContext`][agents.tool_context.ToolContext]와 인자를 JSON 문자열로 받아 도구 출력을 문자열로 반환해야 하는 비동기 함수 `on_invoke_tool` +- `params_json_schema` (인자를 위한 JSON 스키마) +- `on_invoke_tool` ([`ToolContext`][agents.tool_context.ToolContext] 와 JSON 문자열로 된 인자를 받아, 도구 출력을 문자열로 반환하는 async 함수) ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 인자 및 도크스트링 자동 파싱 +### 자동 인자 및 docstring 파싱 -앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인자에 대한 설명을 추출하기 위해 도크스트링을 파싱합니다. 참고 사항: +앞서 언급했듯이, 도구를 위한 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인자에 대한 설명을 추출하기 위해 docstring 을 파싱합니다. 이에 대한 참고 사항: -1. 시그니처 파싱은 `inspect` 모듈로 수행됩니다. 타입 힌트를 사용해 인자의 타입을 이해하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 구성합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다. -2. 도크스트링 파싱에는 `griffe`를 사용합니다. 지원되는 도크스트링 형식은 `google`, `sphinx`, `numpy`입니다. 도크스트링 형식은 자동 감지를 시도하지만 완벽하지 않을 수 있으므로 `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 도크스트링 파싱을 비활성화할 수도 있습니다. +1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 힌트를 사용해 인자 타입을 파악하고, 전체 스키마를 표현하는 Pydantic 모델을 동적으로 구성합니다. Python 기본형, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다 +2. docstring 파싱에는 `griffe` 를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy` 입니다. docstring 형식은 자동 감지를 시도하지만 최선의 노력이므로, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info` 를 `False` 로 설정하여 docstring 파싱을 비활성화할 수도 있습니다 -스키마 추출 코드는 [`agents.function_schema`][]에 있습니다. +스키마 추출을 위한 코드는 [`agents.function_schema`][] 에 있습니다. ## 도구로서의 에이전트 -일부 워크플로에서는 제어를 넘기지 않고, 중앙 에이전트가 특화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션하도록 하고 싶을 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다. +일부 워크플로에서는 제어를 넘기지 않고, 중앙 에이전트가 특화된 에이전트 네트워크를 오케스트레이션하도록 하고 싶을 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다. ```python from agents import Agent, Runner @@ -267,9 +267,9 @@ async def main(): print(result.final_output) ``` -### 툴-에이전트 커스터마이징 +### 도구-에이전트 커스터마이징 -`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환하기 위한 편의 메서드입니다. 그러나 모든 구성을 지원하지는 않습니다. 예를 들어 `max_turns`를 설정할 수 없습니다. 고급 사용 사례에서는 도구 구현에서 직접 `Runner.run`을 사용하세요: +`agent.as_tool` 함수는 에이전트를 도구로 손쉽게 전환하기 위한 편의 메서드입니다. 다만 모든 구성을 지원하지는 않습니다. 예를 들면 `max_turns` 를 설정할 수 없습니다. 고급 사용 사례의 경우, 도구 구현 내에서 `Runner.run` 을 직접 사용하세요: ```python @function_tool @@ -290,13 +290,13 @@ async def run_my_agent() -> str: ### 커스텀 출력 추출 -특정 경우, 중앙 에이전트에 반환하기 전에 툴-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 상황에서 유용합니다: +특정 경우, 중앙 에이전트에 반환하기 전에 도구-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우에 유용합니다: - 하위 에이전트의 대화 기록에서 특정 정보(예: JSON 페이로드)를 추출 -- 에이전트의 최종 답변을 변환하거나 재포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환) -- 에이전트의 응답이 없거나 형식이 잘못된 경우 출력을 검증하거나 대체값 제공 +- 에이전트의 최종 답변을 변환/재포맷(예: 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)`를 받아 불리언을 반환하는 함수 -- **비동기 함수**: 복잡한 조건 로직을 위한 비동기 함수 +- **호출 가능한 함수**: `(context, agent)` 를 받아 불리언을 반환하는 함수 +- **Async 함수**: 복잡한 조건부 로직을 위한 비동기 함수 -비활성화된 도구는 런타임에 LLM에서 완전히 숨겨지므로 다음과 같은 경우에 유용합니다: +비활성화된 도구는 런타임에 LLM 에 완전히 숨겨지므로 다음과 같은 경우에 유용합니다: -- 사용자 권한에 따른 기능 게이팅 -- 환경별 도구 가용성(개발 vs 운영) -- 서로 다른 도구 구성을 A/B 테스트 -- 런타임 상태에 따른 동적 도구 필터링 +- 사용자 권한 기반 기능 게이팅 +- 환경별 도구 가용성(dev vs prod) +- 다양한 도구 구성을 A/B 테스트 +- 런타임 상태 기반 동적 도구 필터링 ## 함수 도구의 오류 처리 -`@function_tool`로 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 크래시한 경우 LLM에 오류 응답을 제공하는 함수입니다. +`@function_tool` 로 함수 도구를 만들 때 `failure_error_function` 을 전달할 수 있습니다. 이는 도구 호출이 크래시한 경우 LLM 에 오류 응답을 제공하는 함수입니다. -- 기본적으로(아무것도 전달하지 않으면) 오류가 발생했음을 LLM에 알리는 `default_tool_error_function`이 실행됩니다. -- 자체 오류 함수를 전달하면 해당 함수가 대신 실행되어 그 응답이 LLM으로 전송됩니다. -- 명시적으로 `None`을 전달하면 도구 호출 오류가 다시 발생(re-raise)하여 직접 처리해야 합니다. 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`, 코드가 크래시한 경우 `UserError` 등이 될 수 있습니다. +- 기본적으로(아무것도 전달하지 않으면) 오류가 발생했음을 LLM 에 알리는 `default_tool_error_function` 이 실행됩니다 +- 사용자 정의 오류 함수를 전달하면 해당 함수가 대신 실행되며, 그 응답이 LLM 에 전송됩니다 +- 명시적으로 `None` 을 전달하면, 도구 호출 오류가 다시 발생하여 사용자가 처리할 수 있습니다. 모델이 잘못된 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 959e7f181..fb84cf10f 100644 --- a/docs/ko/tracing.md +++ b/docs/ko/tracing.md @@ -4,52 +4,52 @@ search: --- # 트레이싱 -Agents SDK에는 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집하는 내장 트레이싱이 포함되어 있습니다. LLM 생성, 도구 호출, 핸드오프, 가드레일, 심지어 사용자 지정 이벤트까지 포함합니다. [Traces 대시보드](https://platform.openai.com/traces)를 사용하여 개발 및 프로덕션 환경에서 워크플로를 디버그하고 시각화하며 모니터링할 수 있습니다. +Agents SDK에는 내장 트레이싱이 포함되어 있어 에이전트 실행 중에 발생하는 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 사용자 지정 이벤트까지. [Traces 대시보드](https://platform.openai.com/traces)를 사용하면 개발 및 프로덕션 환경에서 워크플로를 디버깅, 시각화, 모니터링할 수 있습니다. !!!note 트레이싱은 기본적으로 활성화되어 있습니다. 트레이싱을 비활성화하는 방법은 두 가지입니다: - 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1`를 설정하여 전역으로 비활성화 - 2. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][] 를 `True`로 설정하여 비활성화 + 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1`을 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다 + 2. 단일 실행에 대해서는 [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 트레이싱을 비활성화할 수 있습니다 -***OpenAI API를 사용하는 Zero Data Retention (ZDR) 정책 하의 조직에서는 트레이싱을 사용할 수 없습니다.*** +***OpenAI의 API를 사용하면서 Zero Data Retention (ZDR) 정책 하에 운영하는 조직의 경우, 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 -- **트레이스(Traces)** 는 "워크플로"의 단일 엔드 투 엔드 동작을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - - `workflow_name`: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service" - - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은 `trace_<32_alphanumeric>` 여야 합니다. - - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다. - - `disabled`: True인 경우 트레이스가 기록되지 않습니다. +- **트레이스(Traces)** 는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: + - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "Code generation" 또는 "Customer service" + - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은 `trace_<32_alphanumeric>`여야 합니다 + - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 + - `disabled`: True이면 트레이스가 기록되지 않습니다 - `metadata`: 트레이스에 대한 선택적 메타데이터 -- **스팬(Spans)** 은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 포함됩니다: +- **스팬(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()`으로 래핑됨 +- 오디오 입력(speech-to-text)은 `transcription_span()`으로 래핑됨 +- 오디오 출력(text-to-speech)은 `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. `with trace()`로 `Runner.run`에 대한 두 호출이 래핑되었기 때문에, 개별 실행이 두 개의 트레이스를 생성하지 않고 전체 트레이스의 일부가 됩니다. ## 트레이스 생성 -[`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]를 생성합니다 +- `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성하여 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하고, 이는 배치로 OpenAI 백엔드에 스팬과 트레이스를 내보냅니다 -기본 설정을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 전송하거나 Exporter 동작을 수정하려면 두 가지 옵션이 있습니다: +기본 설정을 사용자 지정하여 다른 또는 추가 백엔드로 트레이스를 전송하거나 익스포터 동작을 수정하려면 두 가지 옵션이 있습니다: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 를 사용하면 준비가 완료된 트레이스와 스팬을 수신하는 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 트레이스를 전송하는 것과 더불어 자체 처리를 수행할 수 있습니다. -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 를 사용하면 기본 프로세서를 고유한 트레이스 프로세서로 **교체**할 수 있습니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는 `TracingProcessor` 를 포함해야 합니다. +1. [`add_trace_processor()`][agents.tracing.add_trace_processor]는 트레이스와 스팬이 준비되는 즉시 수신할 **추가** 트레이스 프로세서를 추가할 수 있게 합니다. 이를 통해 OpenAI 백엔드로 트레이스를 전송하는 것에 더해 자체 처리를 수행할 수 있습니다 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors]는 기본 프로세서를 사용자 지정 트레이스 프로세서로 **교체**할 수 있게 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는 `TracingProcessor`를 포함해야 합니다 ## 비 OpenAI 모델과의 트레이싱 -OpenAI의 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 687a06ab9..365fbe631 100644 --- a/docs/ko/usage.md +++ b/docs/ko/usage.md @@ -4,13 +4,13 @@ search: --- # 사용량 -Agents SDK 는 각 실행(run)마다 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이 정보에 접근하여 비용을 모니터링하고, 제한을 적용하거나, 분석을 기록할 수 있습니다. +Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하고 비용 모니터링, 한도 적용 또는 분석 기록에 활용할 수 있습니다. ## 추적 항목 - **requests**: 수행된 LLM API 호출 수 -- **input_tokens**: 전송된 입력 토큰 총합 -- **output_tokens**: 수신된 출력 토큰 총합 +- **input_tokens**: 전송된 입력 토큰 합계 +- **output_tokens**: 수신된 출력 토큰 합계 - **total_tokens**: 입력 + 출력 - **details**: - `input_tokens_details.cached_tokens` @@ -18,7 +18,7 @@ Agents SDK 는 각 실행(run)마다 토큰 사용량을 자동으로 추적합 ## 실행에서 사용량 접근 -`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) ``` -사용량은 실행 중의 모든 모델 호출(도구 호출과 핸드오프 포함)에 걸쳐 집계됩니다. +사용량은 실행 중 이루어진 모든 모델 호출(도구 호출과 handoffs 포함)에 걸쳐 집계됩니다. ### LiteLLM 모델에서 사용량 활성화 -LiteLLM 공급자는 기본적으로 사용량 지표를 보고하지 않습니다. [`LitellmModel`](models/litellm.md) 을 사용할 때, 에이전트에 `ModelSettings(include_usage=True)` 를 전달하면 LiteLLM 응답이 `result.context_wrapper.usage` 를 채웁니다. +LiteLLM 공급자는 기본적으로 사용량 메트릭을 보고하지 않습니다. [`LitellmModel`](models/litellm.md)을 사용할 때, 에이전트에 `ModelSettings(include_usage=True)`를 전달하면 LiteLLM 응답이 `result.context_wrapper.usage`를 채웁니다. ```python from agents import Agent, ModelSettings, Runner @@ -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): @@ -81,6 +81,6 @@ class MyHooks(RunHooks): 자세한 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 1233fbe40..cdde84ac5 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 Servers**는 회색 상자로 표시됩니다 +- **도구**는 초록색 타원으로 표시됩니다 +- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향 간선입니다 -### 사용 예제 +### 사용 예 ```python import os @@ -69,41 +69,39 @@ draw_graph(triage_agent) ![Agent Graph](../assets/images/graph.png) -이는 **triage agent** 의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 표현한 그래프를 생성합니다. - +이는 **트리아지 에이전트**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프를 생성합니다. ## 시각화 이해 생성된 그래프에는 다음이 포함됩니다: -- 진입점을 나타내는 **시작 노드** (`__start__`) -- 노란색 채우기의 **사각형** 으로 표시된 에이전트 -- 초록색 채우기의 **타원** 으로 표시된 도구 -- 회색 채우기의 **사각형** 으로 표시된 MCP 서버 -- 상호작용을 나타내는 방향 간선 - - 에이전트 간 핸드오프에는 **실선 화살표** - - 도구 호출에는 **점선 화살표** - - MCP 서버 호출에는 **파선 화살표** -- 실행 종료 지점을 나타내는 **끝 노드** (`__end__`) +- 진입 지점을 나타내는 **시작 노드** (`__start__`) +- 노란색 채우기의 **사각형**으로 표시된 에이전트 +- 초록색 채우기의 **타원**으로 표시된 도구 +- 회색 채우기의 **사각형**으로 표시된 MCP Servers +- 상호작용을 나타내는 방향 간선: + - 에이전트 간 핸드오프는 **실선 화살표** + - 도구 호출은 **점선 화살표** + - MCP 서버 호출은 **쇄선 화살표** +- 실행 종료 지점을 나타내는 **종료 노드** (`__end__`) -**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. +**참고:** MCP servers는 최근 버전의 +`agents` 패키지에서 렌더링됩니다 (검증된 버전: **v0.2.8**). 시각화에서 MCP 상자가 보이지 않는다면 최신 릴리스로 업그레이드하세요. ## 그래프 사용자 지정 ### 그래프 표시 -기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에서 표시하려면 다음과 같이 작성하세요: +기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도의 창에서 표시하려면 다음을 작성하세요: ```python draw_graph(triage_agent).view() ``` ### 그래프 저장 -기본적으로 `draw_graph` 는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일 이름을 지정하세요: +기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일명을 지정하세요: ```python draw_graph(triage_agent, filename="agent_graph") ``` -그러면 작업 디렉터리에 `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 2c4268e1f..c736e1a6d 100644 --- a/docs/ko/voice/pipeline.md +++ b/docs/ko/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # 파이프라인과 워크플로 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 기반 워크플로를 음성 앱으로 쉽게 전환할 수 있도록 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오를 전사하고, 오디오 종료를 감지하고, 적절한 시점에 워크플로를 호출하며, 워크플로 출력을 다시 오디오로 변환해 제공합니다. +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 클래스는 에이전트 기반 워크플로를 음성 앱으로 손쉽게 전환할 수 있게 해줍니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 감지, 적절한 시점에 워크플로 호출, 워크플로 출력을 다시 오디오로 변환하는 작업을 처리합니다. ```mermaid graph LR @@ -34,28 +34,28 @@ graph LR ## 파이프라인 구성 -파이프라인을 만들 때 다음을 설정할 수 있습니다: +파이프라인을 생성할 때 다음을 설정할 수 있습니다: -1. 매번 새로운 오디오가 전사될 때 실행되는 코드인 [`workflow`][agents.voice.workflow.VoiceWorkflowBase] +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 모델 설정 + - 모델 제공자: 모델 이름을 실제 모델로 매핑 + - 트레이싱: 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 트레이스 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]은 전체 오디오 전사가 있고 그 결과만 생성하면 될 때 사용합니다. 사전 녹음된 오디오가 있거나, 사용자 발화 종료 시점이 명확한 푸시투토크(push-to-talk) 앱처럼 화자가 말하기를 마치는 시점을 감지할 필요가 없는 경우에 유용합니다. +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 426695232..5d8229f43 100644 --- a/docs/ko/voice/quickstart.md +++ b/docs/ko/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 사전 준비 -Agents SDK의 기본 [빠른 시작 지침](../quickstart.md)을 따라 가상 환경을 설정했는지 확인하세요. 그런 다음, SDK의 선택적 음성 관련 종속 항목을 설치합니다: +Agents SDK의 기본 [빠른 시작 안내](../quickstart.md)를 따라 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택 사항인 음성 관련 종속성을 설치합니다: ```bash pip install 'openai-agents[voice]' @@ -16,9 +16,9 @@ pip install 'openai-agents[voice]' 알아두어야 할 핵심 개념은 [`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 @@ -90,9 +90,9 @@ agent = Agent( ) ``` -## 음성 파이프라인 +## 보이스 파이프라인 -워크플로로 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 사용하여 간단한 음성 파이프라인을 설정하겠습니다. +워크플로로 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 사용하여 간단한 보이스 파이프라인을 설정합니다. ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -이 예제를 실행하면 에이전트가 직접 말합니다! 직접 에이전트와 대화할 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)에서 확인하세요. \ No newline at end of file +이 예제를 실행하면 에이전트가 말합니다! 직접 에이전트와 대화해 볼 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)에서 확인하세요. \ No newline at end of file diff --git a/docs/ko/voice/tracing.md b/docs/ko/voice/tracing.md index ccca68f1b..defd8bc93 100644 --- a/docs/ko/voice/tracing.md +++ b/docs/ko/voice/tracing.md @@ -6,13 +6,13 @@ search: [에이전트가 트레이싱되는 방식](../tracing.md)과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다. -기본 트레이싱 정보는 위 문서를 참고하시고, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다. +기본 트레이싱 정보는 위 문서를 참고하시고, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인 트레이싱을 구성할 수 있습니다. 주요 트레이싱 관련 필드는 다음과 같습니다: -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱 비활성화 여부를 제어합니다. 기본값은 트레이싱 활성화입니다. -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사본 등 민감할 수 있는 데이터를 트레이스에 포함할지 제어합니다. 이는 음성 파이프라인에만 적용되며, Workflow 내부에서 수행되는 작업에는 적용되지 않습니다. -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 트레이스에 오디오 데이터를 포함할지 제어합니다. -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로 이름입니다. -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있게 하는 트레이스의 `group_id` 입니다. -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이스에 함께 포함할 추가 메타데이터입니다. \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱 비활성화 여부를 제어합니다. 기본값은 트레이싱 활성화입니다. +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사와 같은 민감할 수 있는 데이터를 트레이스에 포함할지 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며, Workflow 내부에서 수행되는 작업에는 적용되지 않습니다. +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 트레이스에 오디오 데이터를 포함할지 여부를 제어합니다. +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로의 이름입니다. +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있도록 하는 트레이스의 `group_id` 입니다. +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이스에 포함할 추가 메타데이터입니다. \ No newline at end of file diff --git a/docs/zh/agents.md b/docs/zh/agents.md index 5ad426052..51b3bf3fc 100644 --- a/docs/zh/agents.md +++ b/docs/zh/agents.md @@ -1,15 +1,19 @@ +--- +search: + exclude: true +--- # 智能体 -智能体是应用程序中的核心构建块。一个智能体是一个大型语言模型（LLM），配置了指令和工具。 +智能体是你应用中的核心构建块。一个智能体是一个大语言模型（LLM），通过 instructions 和 tools 进行配置。 ## 基本配置 -智能体最常用到的配置属性包括： +你最常需要为智能体配置的属性包括： -- `name`: 一个必需的字符串，用于标识你的智能体。 -- `instructions`: 也称为开发者消息或系统提示。 -- `model`: 使用哪个LLM，以及可选的 `model_settings` 来配置模型调优参数如temperature、top_p等。 -- `tools`: 智能体可以用来完成任务的工具。 +- `name`: 标识你的智能体的必填字符串。 +- `instructions`: 也称为开发者消息或系统提示词。 +- `model`: 要使用的 LLM，以及可选的 `model_settings` 用于配置如 temperature、top_p 等模型调优参数。 +- `tools`: 智能体可用于完成任务的工具。 ```python from agents import Agent, ModelSettings, function_tool @@ -29,7 +33,7 @@ agent = Agent( ## 上下文 -智能体对于其 `context` 类型是通用的。上下文是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会传递给每个智能体、工具、交接等，作为智能体运行的依赖项和状态的容器。你可以提供任何Python对象作为上下文。 +智能体在其 `context` 类型上是泛型的。上下文是一个依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会传递给每个智能体、工具、任务转移等，作为本次智能体运行的依赖与状态的集合。你可以提供任意 Python 对象作为上下文。 ```python @dataclass @@ -48,7 +52,7 @@ agent = Agent[UserContext]( ## 输出类型 -默认情况下，智能体会产生纯文本（即 `str`）输出。如果你想让智能体产生特定类型的输出，可以使用 `output_type` 参数。一个常见的选择是使用 [Pydantic](https://docs.pydantic.dev/) 对象，但我们支持任何可以包装在 Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 中的类型 - 数据类、列表、TypedDict等。 +默认情况下，智能体生成纯文本（即 `str`）输出。如果你希望智能体生成特定类型的输出，可以使用 `output_type` 参数。一个常见选择是使用 [Pydantic](https://docs.pydantic.dev/) 对象，但我们支持任何可以由 Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 包装的类型——如 dataclasses、lists、TypedDict 等。 ```python from pydantic import BaseModel @@ -69,20 +73,20 @@ agent = Agent( !!! note - 当你传递一个 `output_type` 时，这告诉模型使用 [结构化输出](https://platform.openai.com/docs/guides/structured-outputs) 而不是常规的纯文本响应。 + 当你传入 `output_type` 时，这会告诉模型使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 而不是常规的纯文本响应。 ## 多智能体系统设计模式 -设计多智能体系统有很多方法，但我们通常看到两种广泛适用的模式： +设计多智能体系统的方法很多，但我们常见到两种广泛适用的模式： -1. 管理器（智能体作为工具）：一个中央管理器/编排器调用作为工具公开的专门子智能体，并保持对对话的控制。 -2. 交接：对等智能体将控制权委托给一个专门的智能体，该智能体接管对话。这是分散式的。 +1. 管理器（智能体作为工具）：一个中心管理器/编排器将专业子智能体作为工具调用，并保留对对话的控制权。 +2. 任务转移：对等智能体将控制权移交给一个专业智能体，由其接管对话。这是去中心化的。 -更多详细信息请参见[我们的智能体构建实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。 +更多详情参见[我们的智能体构建实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。 ### 管理器（智能体作为工具） -`customer_facing_agent` 处理所有用户交互，并调用作为工具公开的专门子智能体。更多详细信息请参见 [tools](tools.md#agents-as-tools) 文档。 +`customer_facing_agent` 处理所有用户交互，并调用作为工具暴露的专业子智能体。阅读[工具](tools.md#agents-as-tools)文档了解更多。 ```python from agents import Agent @@ -109,9 +113,9 @@ customer_facing_agent = Agent( ) ``` -### 交接 +### 任务转移 -交接是智能体可以委托的子智能体。当发生交接时，被委托的智能体接收对话历史并接管对话。这种模式使得在单一任务上表现出色的模块化专门智能体成为可能。更多详细信息请参见 [handoffs](handoffs.md) 文档。 +任务转移是指智能体可以委派给的子智能体。当发生任务转移时，被委派的智能体将接收对话历史并接管对话。此模式使得模块化的、在单一任务上表现出色的专业智能体成为可能。阅读[任务转移](handoffs.md)文档了解更多。 ```python from agents import Agent @@ -130,9 +134,9 @@ triage_agent = Agent( ) ``` -## 动态指令 +## 动态 instructions -在大多数情况下，你可以在创建智能体时提供指令。然而，你也可以通过函数提供动态指令。该函数将接收智能体和上下文，并必须返回提示。既可以使用普通函数，也可以使用 `async` 函数。 +在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过函数提供动态 instructions。该函数将接收智能体与上下文，并且必须返回提示词。常规与 `async` 函数均可接受。 ```python def dynamic_instructions( @@ -147,17 +151,17 @@ agent = Agent[UserContext]( ) ``` -## 生命周期事件（钩子） +## 生命周期事件（hooks） -有时候，你可能想要观察智能体的生命周期。例如，你可能想要记录事件，或者在某些事件发生时预取数据。你可以通过 `hooks` 属性在智能体的生命周期中设置钩子。子类化 [`AgentHooks`][agents.lifecycle.AgentHooks] 类，并覆盖你感兴趣的方法。 +有时，你希望观测智能体的生命周期。例如，你可能希望记录事件，或在特定事件发生时预取数据。你可以通过 `hooks` 属性挂接到智能体的生命周期。子类化 [`AgentHooks`][agents.lifecycle.AgentHooks] 类，并重写你感兴趣的方法。 -## 护栏 +## 安全防护措施 -护栏允许你在智能体运行的同时并行运行对用户输入的检查/验证，并在智能体输出产生后对其进行检查/验证。例如，你可以根据相关性筛选用户输入和智能体输出。更多详细信息请参见 [guardrails](guardrails.md) 文档。 +安全防护措施允许你在智能体运行的同时对用户输入进行检查/验证，并在智能体产出结果后对其输出进行检查。例如，你可以筛查用户输入和智能体输出的相关性。阅读[安全防护措施](guardrails.md)文档了解更多。 ## 克隆/复制智能体 -通过使用智能体上的 `clone()` 方法，你可以复制智能体，并选择性地更改任何属性。 +通过在智能体上使用 `clone()` 方法，你可以复制一个智能体，并可选地更改任何你想修改的属性。 ```python pirate_agent = Agent( @@ -172,14 +176,14 @@ robot_agent = pirate_agent.clone( ) ``` -## 强制工具使用 +## 强制使用工具 -提供工具列表并不总是意味着LLM会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制工具使用。有效值包括： +提供工具列表并不总能让 LLM 使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制使用工具。有效取值包括： -1. `auto`，允许LLM决定是否使用工具。 -2. `required`，要求LLM使用工具（但它可以智能地决定使用哪个工具）。 -3. `none`，要求LLM _不_ 使用工具。 -4. 设置特定字符串，例如 `my_tool`，要求LLM使用该特定工具。 +1. `auto`，允许 LLM 决定是否使用工具。 +2. `required`，要求 LLM 使用工具（但它可以智能选择具体的工具）。 +3. `none`，要求 LLM 不使用工具。 +4. 设置一个特定字符串，例如 `my_tool`，要求 LLM 使用该特定工具。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -201,8 +205,8 @@ agent = Agent( `Agent` 配置中的 `tool_use_behavior` 参数控制如何处理工具输出： -- `"run_llm_again"`: 默认。工具运行后，LLM处理结果以产生最终响应。 -- `"stop_on_first_tool"`: 第一个工具调用的输出用作最终响应，无需进一步的LLM处理。 +- `"run_llm_again"`：默认值。运行工具后，由 LLM 处理结果以生成最终响应。 +- `"stop_on_first_tool"`：第一次工具调用的输出直接作为最终响应，不再进行 LLM 处理。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -220,7 +224,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 当指定的工具中的任何一个被调用时停止，并将其输出用作最终响应。 +- `StopAtTools(stop_at_tool_names=[...])`: 如果调用了任一指定工具则停止，使用其输出作为最终响应。 ```python from agents import Agent, Runner, function_tool @@ -244,7 +248,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`: 处理工具结果并决定是停止还是继续LLM的自定义函数。 +- `ToolsToFinalOutputFunction`: 一个自定义函数，用于处理工具结果，并决定是停止还是继续让 LLM 处理。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -282,4 +286,4 @@ agent = Agent( !!! note - 为了防止无限循环，框架会在工具调用后自动将 `tool_choice` 重置为 "auto"。此行为可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 进行配置。无限循环的发生是因为工具结果被发送给LLM，然后由于 `tool_choice` 导致LLM再次生成工具调用，如此循环往复。 \ No newline at end of file + 为防止无限循环，框架会在一次工具调用后自动将 `tool_choice` 重置为 "auto"。可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 配置此行为。出现无限循环的原因是工具结果会被发送给 LLM，而由于 `tool_choice` 的设置，LLM 会再次生成工具调用，如此往复。 \ No newline at end of file diff --git a/docs/zh/config.md b/docs/zh/config.md index 798aaef1b..512f258d3 100644 --- a/docs/zh/config.md +++ b/docs/zh/config.md @@ -4,9 +4,9 @@ search: --- # 配置 SDK -## API 密钥和客户端 +## API 密钥与客户端 -默认情况下，SDK 会在导入后立即查找 `OPENAI_API_KEY` 环境变量以进行 LLM 请求和追踪。如果你无法在应用启动前设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数来设置密钥。 +默认情况下，SDK 在被导入后会立即从环境变量 `OPENAI_API_KEY` 中读取用于 LLM 请求和追踪（tracing）的密钥。如果你无法在应用启动前设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数来设置密钥。 ```python from agents import set_default_openai_key @@ -14,7 +14,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -或者，你也可以配置要使用的 OpenAI 客户端。默认情况下，SDK 会创建一个 `AsyncOpenAI` 实例，使用来自环境变量或上面设置的默认密钥的 API 密钥。你可以通过使用 [set_default_openai_client()][agents.set_default_openai_client] 函数来更改此设置。 +或者，你也可以配置要使用的 OpenAI 客户端。默认情况下，SDK 会创建一个 `AsyncOpenAI` 实例，使用环境变量中的 API 密钥或上面设置的默认密钥。你可以使用 [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] 函数来覆盖此设置以使用聊天完成 API。 +最后，你还可以自定义所使用的 OpenAI API。默认使用 OpenAI Responses API。你可以通过 [set_default_openai_api()][agents.set_default_openai_api] 函数覆盖为使用 Chat Completions API。 ```python from agents import set_default_openai_api @@ -34,7 +34,7 @@ set_default_openai_api("chat_completions") ## 追踪 -追踪默认启用。它默认使用上面部分中的 OpenAI API 密钥（即环境变量或你设置的默认密钥）。你可以通过使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数来专门设置用于追踪的 API 密钥。 +追踪默认启用。它默认使用上节中的 OpenAI API 密钥（即环境变量或你设置的默认密钥）。你可以使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数专门设置用于追踪的 API 密钥。 ```python from agents import set_tracing_export_api_key @@ -42,7 +42,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -你还可以通过使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数来完全禁用追踪。 +你也可以使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数完全禁用追踪。 ```python from agents import set_tracing_disabled @@ -50,11 +50,11 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -## 调试日志记录 +## 调试日志 -SDK 有两个 Python 日志记录器，没有设置任何处理程序。默认情况下，这意味着警告和错误会发送到 `stdout`，但其他日志会被抑制。 +SDK 提供两个未设置任何处理器（handler）的 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,36 +62,36 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -或者，你可以通过添加处理程序、过滤器、格式化程序等来定制日志。你可以在 [Python 日志记录指南](https://docs.python.org/3/howto/logging.html) 中阅读更多内容。 +或者，你可以通过添加处理器、过滤器、格式化器等自定义日志。可参考 [Python 日志指南](https://docs.python.org/3/howto/logging.html)。 ```python import logging -logger = logging.getLogger("openai.agents") # 或 openai.agents.tracing 用于追踪日志记录器 +logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger -# 要使所有日志显示 +# To make all logs show up logger.setLevel(logging.DEBUG) -# 要使信息及以上级别显示 +# To make info and above show up logger.setLevel(logging.INFO) -# 要使警告及以上级别显示 +# To make warning and above show up logger.setLevel(logging.WARNING) -# 等等 +# etc -# 你可以根据需要自定义此设置，但默认情况下这会输出到 `stderr` +# You can customize this as needed, but this will output to `stderr` by default logger.addHandler(logging.StreamHandler()) ``` ### 日志中的敏感数据 -某些日志可能包含敏感数据（例如，用户数据）。如果你想禁用记录这些数据，请设置以下环境变量。 +某些日志可能包含敏感数据（例如用户数据）。如果你希望禁用这些数据的记录，请设置以下环境变量。 -要禁用记录 LLM 输入和输出： +禁用记录 LLM 的输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 ``` -要禁用记录工具输入和输出： +禁用记录工具的输入与输出： ```bash export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 diff --git a/docs/zh/context.md b/docs/zh/context.md index 1176d54f6..db2c77b4e 100644 --- a/docs/zh/context.md +++ b/docs/zh/context.md @@ -4,30 +4,30 @@ search: --- # 上下文管理 -"上下文"是一个含义丰富的术语。你可能关心的主要有两类上下文： +“上下文”一词含义宽泛。你可能关心两大类上下文： -1. 代码本地可用的上下文：这是工具函数运行时、在`on_handoff`等回调中、生命周期钩子中等可能需要的数据和依赖项。 -2. LLM可用的上下文：这是LLM生成响应时看到的数据。 +1. 代码本地可用的上下文：这是工具函数运行时、`on_handoff` 等回调、生命周期钩子等可能需要的数据和依赖。 +2. LLM 可用的上下文：这是 LLM 在生成响应时能看到的数据。 ## 本地上下文 -这通过[`RunContextWrapper`][agents.run_context.RunContextWrapper]类和其中的[`context`][agents.run_context.RunContextWrapper.context]属性来表示。其工作方式是： +这通过 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 类及其内部的 [`context`][agents.run_context.RunContextWrapper.context] 属性来表示。其工作方式如下： -1. 你创建任何你想要的Python对象。常见模式是使用数据类或Pydantic对象。 -2. 你将该对象传递给各种运行方法（例如`Runner.run(..., **context=whatever**)`）。 -3. 你的所有工具调用、生命周期钩子等都将传递一个包装器对象`RunContextWrapper[T]`，其中`T`表示你的上下文对象类型，你可以通过`wrapper.context`访问。 +1. 你创建任意 Python 对象即可。常见模式是使用 dataclass 或 Pydantic 对象。 +2. 将该对象传入各种运行方法（例如 `Runner.run(..., **context=whatever**)`）。 +3. 你所有的工具调用、生命周期钩子等都会收到一个包装对象 `RunContextWrapper[T]`，其中 `T` 表示你的上下文对象类型，你可以通过 `wrapper.context` 访问它。 -**最重要**的事情需要注意：对于给定的智能体运行，每个智能体、工具函数、生命周期等都必须使用相同_类型_的上下文。 +需要注意的**最重要**一点：给定一次智能体运行中的每个智能体、工具函数、生命周期等都必须使用相同类型的上下文。 -你可以将上下文用于： +你可以将上下文用于以下场景： -- 运行的上下文数据（例如用户名/uid或关于用户的其他信息） -- 依赖项（例如日志记录器对象、数据获取器等） -- 辅助函数 +- 运行所需的上下文数据（例如用户名/uid 或关于用户的其他信息） +- 依赖项（例如日志记录器、数据获取器等） +- 帮助函数 !!! danger "注意" - 上下文对象**不会**发送到LLM。它纯粹是一个本地对象，你可以读取、写入和调用其方法。 + 上下文对象**不**会发送给 LLM。它纯粹是一个本地对象，你可以读取、写入并在其上调用方法。 ```python import asyncio @@ -66,17 +66,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 这是上下文对象。我们这里使用了数据类，但你可以使用任何类型。 -2. 这是一个工具。你可以看到它接受一个`RunContextWrapper[UserInfo]`。工具实现从上下文中读取。 -3. 我们用泛型`UserInfo`标记智能体，这样类型检查器可以捕获错误（例如，如果我们尝试传递一个接受不同上下文类型的工具）。 -4. 上下文被传递给`run`函数。 +1. 这是上下文对象。此处使用了 dataclass，但你可以使用任何类型。 +2. 这是一个工具。你可以看到它接收 `RunContextWrapper[UserInfo]`。工具实现会从上下文中读取。 +3. 我们用泛型 `UserInfo` 标注智能体，以便类型检查器能捕获错误（例如，如果我们尝试传入一个期望不同上下文类型的工具）。 +4. 将上下文传递给 `run` 函数。 5. 智能体正确调用工具并获取年龄。 -## 智能体/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. 使用检索或网络搜索。这些是特殊工具，能够从文件或数据库（检索），或从网络（网络搜索）获取相关数据。这对于在相关上下文中"基于"响应很有用。 \ 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. 使用 文件检索 或 网络检索。它们是能够从文件或数据库（文件检索）或从网络（网络检索）中获取相关数据的特殊工具。这有助于用相关的上下文数据“奠基（ground）”响应。 \ No newline at end of file diff --git a/docs/zh/examples.md b/docs/zh/examples.md index 701524f5c..74fc86c91 100644 --- a/docs/zh/examples.md +++ b/docs/zh/examples.md @@ -2,92 +2,92 @@ search: exclude: true --- -# 使用示例 +# 代码示例 -在[仓库](https://github.com/openai/openai-agents-python/tree/main/examples)的示例部分查看SDK的各种示例实现。这些示例被组织成几个类别，展示了不同的模式和功能。 +在[仓库](https://github.com/openai/openai-agents-python/tree/main/examples)的 examples 部分查看多种 SDK 的示例实现。这些代码示例按若干目录组织，展示不同的模式和能力。 -## 示例分类 +## 目录 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 此分类中的示例展示了常见的智能体设计模式，例如： + 本目录中的示例阐释常见的智能体设计模式，例如： - 确定性工作流 - - 智能体作为工具 - - 智能体并行执行 - - 条件工具使用 - - 输入/输出护栏 - - LLM作为评判者 + - 将智能体作为工具使用 + - 并行智能体执行 + - 条件性工具使用 + - 输入/输出安全防护措施 + - LLM 作为评审 - 路由 - - 流式护栏 + - 流式传输安全防护措施 - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 这些示例展示了SDK的基础功能，例如： + 这些示例展示 SDK 的基础能力，例如： - - Hello World示例（默认模型、GPT-5、开源权重模型） + - Hello world 代码示例（默认模型、GPT-5、开放权重模型） - 智能体生命周期管理 - - 动态系统提示 - - 流式输出（文本、项目、函数调用参数） + - 动态系统提示词 + - 流式传输输出（文本、条目、函数调用参数） - 提示模板 - - 文件处理（本地和远程、图像和PDF） - - 使用情况跟踪 + - 文件处理（本地与远程，图像与 PDF） + - 用量追踪 - 非严格输出类型 - - 先前响应ID使用 + - 先前响应 ID 的用法 - **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):** - 航空公司客户服务系统示例。 + 航空公司的客户服务系统示例。 - **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):** - 金融研究智能体，展示了使用智能体和工具进行金融数据分析的结构化研究工作流。 + 一个金融研究智能体，演示使用智能体与工具进行金融数据分析的结构化研究工作流。 - **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):** - 查看带有消息过滤的智能体交接的实际示例。 + 了解带消息过滤的智能体任务转移的实用示例。 - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 展示如何使用托管MCP（模型上下文协议）连接器和批准的示例。 + 演示如何使用托管的 MCP（Model Context Protocol）连接器与审批。 - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 学习如何使用MCP（模型上下文协议）构建智能体，包括： + 学习如何使用 MCP（Model Context Protocol）构建智能体，包括： - - 文件系统示例 - - Git示例 - - MCP提示服务器示例 - - SSE（服务器发送事件）示例 - - 可流式HTTP示例 + - 文件系统代码示例 + - Git 代码示例 + - MCP 提示词服务代码示例 + - SSE（Server-Sent Events）代码示例 + - 可流式传输的 HTTP 代码示例 - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** 智能体的不同内存实现示例，包括： - - SQLite会话存储 - - 高级SQLite会话存储 - - Redis会话存储 - - SQLAlchemy会话存储 + - SQLite 会话存储 + - 高级 SQLite 会话存储 + - Redis 会话存储 + - SQLAlchemy 会话存储 - 加密会话存储 - - OpenAI会话存储 + - OpenAI 会话存储 - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 探索如何在SDK中使用非OpenAI模型，包括自定义提供程序和LiteLLM集成。 + 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方与 LiteLLM 集成。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - 展示如何使用SDK构建实时体验的示例，包括： + 展示如何使用 SDK 构建实时体验的示例，包括： - - Web应用程序 + - Web 应用 - 命令行界面 - - Twilio集成 + - 与 Twilio 集成 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - 展示如何处理推理内容和结构化输出的示例。 + 演示如何处理推理内容与 structured outputs 的示例。 - **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):** - 简单的深度研究克隆，展示了复杂的多智能体研究工作流。 + 简单的深度研究克隆，演示复杂的多智能体研究工作流。 - **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):** - 学习如何实现OpenAI托管工具： + 学习如何实现由OpenAI托管的工具，例如： - - 网络搜索和带过滤的网络搜索 - - 文件搜索 - - 代码解释器 - - 计算机使用 + - 网络检索与带筛选的网络检索 + - 文件检索 + - Code Interpreter + - 计算机操作 - 图像生成 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - 查看使用我们的TTS和STT模型的语音智能体示例，包括流式语音示例。 \ No newline at end of file + 查看语音智能体示例，使用我们的 TTS 与 STT 模型，包括流式语音代码示例。 \ No newline at end of file diff --git a/docs/zh/guardrails.md b/docs/zh/guardrails.md index baa6628a3..5a795b2ed 100644 --- a/docs/zh/guardrails.md +++ b/docs/zh/guardrails.md @@ -2,46 +2,46 @@ search: exclude: true --- -# 护栏 +# 安全防护措施 -护栏与你的智能体 _并行_ 运行，使你能够对用户输入进行检查和验证。例如，假设你有一个使用非常智能（因此速度慢/成本高）模型的智能体来帮助处理客户请求。你不会希望恶意用户要求模型帮助他们做数学作业。因此，你可以使用一个快速/低成本的模型运行护栏。如果护栏检测到恶意使用，它可以立即引发错误，这会阻止昂贵的模型运行并为你节省时间/金钱。 +安全防护措施与智能体_并行_运行，使你能够对用户输入进行检查和验证。比如，假设你有一个使用非常聪明（因此也很慢/昂贵）的模型来处理客户请求的智能体。你不希望恶意用户让该模型帮他们做数学作业。因此，你可以使用一个快速/便宜的模型来运行安全防护措施。如果安全防护措施检测到恶意使用，它可以立即抛出错误，从而阻止昂贵模型的运行，节省时间和成本。 -有两种护栏： +安全防护措施有两种类型： -1. 输入护栏在初始用户输入上运行 -2. 输出护栏在最终的智能体输出上运行 +1. 输入安全防护措施运行在初始用户输入上 +2. 输出安全防护措施运行在最终智能体输出上 -## 输入护栏 +## 输入安全防护措施 -输入护栏分3步运行： +输入安全防护措施分三步运行： -1. 首先，护栏接收传递给智能体的相同输入。 -2. 接下来，护栏函数运行以产生一个 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，然后将其包装在 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] 中 -3. 最后，我们检查 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] 是否为真。如果为真，会引发一个 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 异常，这样你就可以适当地响应用户或处理异常。 +1. 首先，安全防护措施接收与智能体相同的输入。 +2. 接着，安全防护措施函数运行以生成一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后被包装为一个[`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] +3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，将抛出[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered]异常，以便你适当回应用户或处理该异常。 !!! 注意 - 输入护栏旨在在用户输入上运行，因此智能体的护栏仅在智能体是 *第一个* 智能体时才运行。你可能想知道，为什么 `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] 是否为真。如果为真，会引发一个 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 异常，这样你就可以适当地响应用户或处理异常。 +1. 首先，安全防护措施接收由智能体产生的输出。 +2. 接着，安全防护措施函数运行以生成一个[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后被包装为一个[`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] +3. 最后，我们检查[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]是否为 true。若为 true，将抛出[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]异常，以便你适当回应用户或处理该异常。 !!! 注意 - 输出护栏旨在在最终的智能体输出上运行，因此智能体的护栏仅在智能体是 *最后一个* 智能体时才运行。与输入护栏类似，我们这样做是因为护栏往往与实际的智能体相关 - 你会为不同的智能体运行不同的护栏，因此将代码并置有助于可读性。 + 输出安全防护措施旨在作用于最终的智能体输出，因此只有当某个智能体是*最后一个*智能体时，该智能体的安全防护措施才会运行。与输入安全防护措施类似，我们这样做是因为安全防护措施通常与具体的智能体相关——你会为不同的智能体运行不同的安全防护措施，因此将代码就近放置有助于可读性。 -## 触发器 +## 绊线 -如果输入或输出未通过护栏，护栏可以通过触发器发出信号。一旦我们看到已触发触发器的护栏，我们会立即引发一个 `{Input,Output}GuardrailTripwireTriggered` 异常并停止智能体执行。 +如果输入或输出未通过安全防护措施，安全防护措施可以通过绊线进行标识。一旦我们发现某个安全防护措施触发了绊线，我们会立即抛出 `{Input,Output}GuardrailTripwireTriggered` 异常并停止智能体执行。 -## 实现护栏 +## 实现安全防护措施 -你需要提供一个接收输入并返回 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] 的函数。在这个例子中，我们将通过在底层运行一个智能体来实现这一点。 +你需要提供一个函数来接收输入，并返回[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]。在此示例中，我们将通过在幕后运行一个智能体来实现。 ```python from pydantic import BaseModel @@ -94,12 +94,12 @@ async def main(): print("Math homework guardrail tripped") ``` -1. 我们将在护栏函数中使用这个智能体。 -2. 这是接收智能体输入/上下文并返回结果的护栏函数。 -3. 我们可以在护栏结果中包含额外信息。 +1. 我们将在安全防护措施函数中使用这个智能体。 +2. 这是接收智能体输入/上下文并返回结果的安全防护措施函数。 +3. 我们可以在安全防护措施结果中包含额外信息。 4. 这是定义工作流的实际智能体。 -输出护栏类似。 +输出安全防护措施与此类似。 ```python from pydantic import BaseModel @@ -153,6 +153,6 @@ async def main(): ``` 1. 这是实际智能体的输出类型。 -2. 这是护栏的输出类型。 -3. 这是接收智能体输出并返回结果的护栏函数。 +2. 这是安全防护措施的输出类型。 +3. 这是接收智能体输出并返回结果的安全防护措施函数。 4. 这是定义工作流的实际智能体。 \ No newline at end of file diff --git a/docs/zh/handoffs.md b/docs/zh/handoffs.md index 8423d7a4b..4aad79e71 100644 --- a/docs/zh/handoffs.md +++ b/docs/zh/handoffs.md @@ -2,21 +2,21 @@ search: exclude: true --- -# 交接 +# 任务转移 -交接允许智能体将任务委托给另一个智能体。这在不同智能体专门从事不同领域的场景中特别有用。例如，客户支持应用可能让每个智能体专门处理订单状态、退款、常见问题等任务。 +任务转移允许一个智能体将任务委派给另一个智能体。这在不同智能体各自专长不同领域的场景中特别有用。例如，一个客服应用可能有分别处理订单状态、退款、常见问题等任务的智能体。 -交接对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()` 函数自定义任务转移 -[`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`: 是否启用交接。这可以是布尔值或返回布尔值的函数，允许你在运行时动态启用或禁用交接。 +- `agent`: 要移交到的智能体。 +- `tool_name_override`: 默认使用 `Handoff.default_tool_name()`，其解析为 `transfer_to_`。你可以覆盖它。 +- `tool_description_override`: 覆盖来自 `Handoff.default_tool_description()` 的默认工具描述。 +- `on_handoff`: 当任务转移被调用时执行的回调函数。这对于在知道即将发生任务转移时立刻启动某些数据获取非常有用。该函数接收智能体上下文，并且可选地接收由 LLM 生成的输入。输入数据由 `input_type` 参数控制。 +- `input_type`: 任务转移期望的输入类型（可选）。 +- `input_filter`: 用于过滤下一个智能体所接收的输入。详见下文。 +- `is_enabled`: 任务转移是否启用。可以是布尔值或返回布尔值的函数，以便在运行时动态启用或禁用任务转移。 ```python from agents import Agent, handoff, RunContextWrapper @@ -58,9 +58,9 @@ handoff_obj = handoff( ) ``` -## 交接输入 +## 任务转移输入 -在某些情况下，你希望LLM在调用交接时提供一些数据。例如，想象一个交接给"升级智能体"。你可能想要提供一个原因，以便你可以记录它。 +在某些情况下，你希望 LLM 在调用任务转移时提供一些数据。比如，想象一个移交到“升级处理智能体（Escalation agent）”的情况。你可能希望提供一个原因，以便进行日志记录。 ```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/zh/index.md b/docs/zh/index.md index adfe32ae4..5197af51b 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -4,31 +4,31 @@ search: --- # OpenAI Agents SDK -[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) 让您能够在轻量级、易于使用的软件包中构建智能体 AI 应用，抽象化程度极低。它是我们之前用于智能体的实验项目 [Swarm](https://github.com/openai/swarm/tree/main) 的生产级升级版本。Agents SDK 只包含极少量原语： +[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) 让你以轻量、易用、几乎无抽象的方式构建基于智能体的 AI 应用。它是我们此前针对智能体的探索 [Swarm](https://github.com/openai/swarm/tree/main) 的生产可用升级版。Agents SDK 只包含一小组基本组件： -- **Agents**，即配备指令和工具的 LLM -- **Handoffs**，允许智能体将特定任务委托给其他智能体 -- **Guardrails**，支持对智能体输入和输出进行验证 -- **Sessions**，在智能体运行之间自动维护对话历史 +- **智能体**，即配备了 instructions 和工具的 LLM +- **任务转移**，使智能体能将特定任务委托给其他智能体 +- **安全防护措施**，用于校验智能体的输入与输出 +- **会话**，在智能体多次运行间自动维护对话历史 -结合 Python，这些原语足以表达工具和智能体之间的复杂关系，让您无需陡峭的学习曲线即可构建实际应用。此外，SDK 还内置了**追踪**功能，让您能够可视化和调试智能体流程，以及评估它们，甚至为您的应用微调模型。 +结合 Python，这些基本组件足以表达工具与智能体之间的复杂关系，让你在没有陡峭学习曲线的情况下构建真实应用。此外，SDK 内置了**追踪**，可帮助你可视化并调试智能体流程、进行评估，甚至为你的应用微调模型。 ## 为何使用 Agents SDK -SDK 有两个核心设计原则： +该 SDK 的两项核心设计原则： -1. 功能足够丰富以值得使用，但原语足够少以便快速学习。 -2. 开箱即用表现出色，但您可以精确自定义发生的情况。 +1. 功能足够多到值得使用，但基本组件足够少以便快速上手。 +2. 开箱即用效果佳，同时你可以精确定制实际行为。 -以下是 SDK 的主要功能： +SDK 的主要特性包括： -- Agent loop：内置的智能体循环，处理调用工具、将结果发送给 LLM，以及循环直到 LLM 完成。 -- Python-first：使用内置语言功能来编排和链接智能体，而非需要学习新的抽象概念。 -- Handoffs：在多个智能体之间协调和委托的强大功能。 -- Guardrails：与智能体并行运行输入验证和检查，如果检查失败则提前中断。 -- Sessions：跨智能体运行自动管理对话历史，消除手动状态处理。 -- Function tools：将任何 Python 函数转换为工具，具有自动模式生成和 Pydantic 驱动的验证。 -- Tracing：内置追踪功能让您能够可视化、调试和监控工作流程，以及使用 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/zh/mcp.md b/docs/zh/mcp.md index 2613c70ab..55b7c4adb 100644 --- a/docs/zh/mcp.md +++ b/docs/zh/mcp.md @@ -2,34 +2,34 @@ search: exclude: true --- -# 模型上下文协议 (MCP) +# Model context protocol (MCP) -[模型上下文协议](https://modelcontextprotocol.io/introduction) (MCP) 标准化了应用程序如何向语言模型公开工具和上下文的方法。来自官方文档： +[Model context protocol](https://modelcontextprotocol.io/introduction)（MCP）对应用向语言模型暴露工具与上下文的方式进行了标准化。官方文档中提到： -> MCP是一个开放协议，它标准化了应用程序如何向LLM提供上下文的方法。将MCP视为AI应用的USB-C端口。正如USB-C提供了一种将设备连接到各种外围设备和配件的标准化方式，MCP提供了一种将AI模型连接到不同数据源和工具的标准化方式。 +> MCP 是一个开放协议，用于标准化应用向 LLM 提供上下文的方式。将 MCP 想象成面向 AI 应用的 USB-C 接口。正如 USB-C 为你的设备连接各种外设和配件提供了标准化的方式，MCP 也为 AI 模型连接不同数据源与工具提供了标准化路径。 -Agents Python SDK支持多种MCP传输方式。这使你可以重用现有的MCP服务器或构建自己的服务器，将文件系统、HTTP或由连接器支持的工具暴露给智能体。 +Agents Python SDK 支持多种 MCP 传输方式。你可以复用现有 MCP 服务或构建自己的服务，将文件系统、HTTP 或由连接器支持的工具暴露给智能体。 -## 选择MCP集成 +## Choosing an MCP integration -在将MCP服务器连接到智能体之前，决定工具调用应该在哪里执行以及你可以访问哪些传输方式。下表总结了Python SDK支持的选项。 +在将 MCP 服务接入智能体之前，请先决定工具调用应在哪执行，以及你能访问哪些传输方式。下面的矩阵总结了 Python SDK 支持的选项。 -| 你需要什么 | 推荐选项 | -| ------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| 让OpenAI的Responses API代表模型调用公开可访问的MCP服务器 | **托管MCP服务器工具**（通过[`HostedMCPTool`][agents.tool.HostedMCPTool]） | -| 连接到你在本地或远程运行的可流式HTTP服务器 | **可流式HTTP MCP服务器**（通过[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]） | -| 与实现了带服务器发送事件(SSE)的HTTP服务器进行交互 | **带SSE的HTTP MCP服务器**（通过[`MCPServerSse`][agents.mcp.server.MCPServerSse]） | -| 启动本地进程并通过stdin/stdout进行通信 | **stdio MCP服务器**（通过[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]） | +| 你的需求 | 推荐选项 | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| 让 OpenAI 的 Responses API 代表模型调用可公开访问的 MCP 服务 | **托管 MCP 服务工具**，通过 [`HostedMCPTool`][agents.tool.HostedMCPTool] | +| 连接你在本地或远程运行的可流式传输的 HTTP 服务 | **可流式传输的 HTTP MCP 服务**，通过 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| 与实现了带 Server-Sent Events 的 HTTP 协议的服务通信 | **HTTP with SSE MCP 服务**，通过 [`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| 启动本地进程并通过 stdin/stdout 通信 | **stdio MCP 服务**，通过 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -以下各节将介绍每个选项、如何配置它们，以及何时优先选择某个传输方式。 +以下各节将逐一介绍每个选项的配置方法，以及在何种情况下优先选择某种传输方式。 -## 1. 托管MCP服务器工具 +## 1. Hosted MCP server tools -托管工具将整个工具往返过程推送到OpenAI的基础设施中。你的代码不再列出和调用工具，而是[`HostedMCPTool`][agents.tool.HostedMCPTool]将服务器标签（和可选的连接器元数据）转发到Responses API。模型列出远程服务器的工具并在没有额外回调到你的Python进程的情况下调用它们。托管工具目前适用于支持Responses API的托管MCP集成的OpenAI模型。 +托管工具将整个工具调用往返过程放入 OpenAI 的基础设施内。你的代码不再负责列举与调用工具，[`HostedMCPTool`][agents.tool.HostedMCPTool] 会将服务标签（以及可选的连接器元数据）转发给 Responses API。模型会列出远程服务的工具并直接调用，无需对你的 Python 进程进行额外回调。托管工具目前适用于支持 Responses API 托管 MCP 集成的 OpenAI 模型。 -### 基本托管MCP工具 +### Basic hosted MCP tool -通过向智能体的`tools`列表添加[`HostedMCPTool`][agents.tool.HostedMCPTool]来创建托管工具。`tool_config`字典反映了你要发送到REST API的JSON： +通过在智能体的 `tools` 列表中添加一个 [`HostedMCPTool`][agents.tool.HostedMCPTool] 来创建托管工具。`tool_config` 字典与通过 REST API 发送的 JSON 相对应： ```python import asyncio @@ -57,11 +57,11 @@ async def main() -> None: asyncio.run(main()) ``` -托管服务器会自动公开其工具，无需将其添加到 `mcp_servers`。 +托管服务会自动暴露其工具；你无需将其加入 `mcp_servers`。 -### 支持流式传输的托管MCP执行结果 +### Streaming hosted MCP results -托管工具以与函数工具完全相同的方式支持流式传输。向 `Runner.run_streamed` 传递 `stream=True`，即可在模型仍在运行时增量获取MCP输出： +托管工具与工具调用一样支持流式传输。向 `Runner.run_streamed` 传入 `stream=True`，即可在模型仍在处理时消费增量的 MCP 输出： ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -71,9 +71,9 @@ async for event in result.stream_events(): print(result.final_output) ``` -### 可选的审批流程 +### Optional approval flows -如果服务器能够执行敏感操作，可以在每次工具执行前要求人工或程序审批。将 `tool_config` 中的 `require_approval` 设置为单一策略（`"always"`、`"never"`）或从工具名到策略的字典。要在Python中进行判断，请指定 `on_approval_request` 回调函数。 +如果某个服务能执行敏感操作，你可以在每次工具执行前要求人工或程序化审批。在 `tool_config` 中配置 `require_approval`，可设置为单一策略（`"always"`、`"never"`）或一个将工具名映射到策略的字典。若要在 Python 内进行决策，请提供 `on_approval_request` 回调。 ```python from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest @@ -101,11 +101,11 @@ agent = Agent( ) ``` -回调可以是同步或异步的，每当模型需要审批数据才能继续执行时就会被调用。 +回调可为同步或异步，只要模型需要审批数据以继续运行时就会被调用。 -### 支持连接器的托管服务器 +### Connector-backed hosted servers -托管MCP也支持OpenAI连接器。不指定 `server_url`，而是指定 `connector_id` 和访问令牌。Responses API会处理认证，托管服务器会公开该连接器的工具。 +托管 MCP 也支持 OpenAI 连接器。无需指定 `server_url`，改为提供 `connector_id` 和访问令牌。Responses API 负责认证，托管服务将暴露连接器的工具。 ```python import os @@ -121,12 +121,12 @@ HostedMCPTool( ) ``` -包含流式传输、审批和连接器的完整可运行托管工具示例可在 +包含流式传输、审批与连接器的完整托管工具示例可在 [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) 中找到。 -## 2. 可流式HTTP MCP服务器 +## 2. Streamable HTTP MCP servers -如果你想自己管理网络连接，可以使用 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。可流式HTTP服务器最适合需要自己控制传输方式的场景，或者在自己的基础设施中运行服务器同时保持低延迟的情况。 +当你希望自行管理网络连接时，使用 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你掌控传输层，或希望在自有基础设施中运行服务并保持低延迟时，可流式传输的 HTTP 服务是理想选择。 ```python import asyncio @@ -161,16 +161,16 @@ async def main() -> None: asyncio.run(main()) ``` -构造函数接受额外的选项： +构造函数还接受以下选项： -- `client_session_timeout_seconds` 控制HTTP读取超时时间。 -- `use_structured_content` 切换是否优先使用 `tool_result.structured_content` 而非文本输出。 -- `max_retry_attempts` 和 `retry_backoff_seconds_base` 为 `list_tools()` 和 `call_tool()` 添加自动重试。 -- `tool_filter` 可以将公开的工具限制为子集（参见[工具过滤](#工具过滤)）。 +- `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. 带SSE的HTTP MCP服务器 +## 3. HTTP with SSE MCP servers -如果MCP服务器实现了带SSE（服务器发送事件）的HTTP传输，可以实例化 [`MCPServerSse`][agents.mcp.server.MCPServerSse]。除了传输方式外，API与可流式HTTP服务器完全相同。 +如果 MCP 服务实现了带 SSE 的 HTTP 传输，请实例化 [`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，其 API 与可流式传输的 HTTP 服务完全相同。 ```python @@ -197,9 +197,9 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP服务器 +## 4. stdio MCP servers -对于作为本地子进程运行的MCP服务器，使用 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK会启动进程，保持管道打开，并在上下文管理器退出时自动关闭。此选项适用于快速原型开发，或者当服务器仅公开命令行入口点时。 +对于作为本地子进程运行的 MCP 服务，使用 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK 会启动进程、保持管道打开，并在上下文管理器退出时自动关闭。这对快速原型验证或服务仅以命令行入口暴露时非常有用。 ```python from pathlib import Path @@ -225,13 +225,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 @@ -249,11 +249,11 @@ filesystem_server = MCPServerStdio( ) ``` -如果同时指定了 `allowed_tool_names` 和 `blocked_tool_names`，SDK会首先应用允许列表，然后从剩余集合中删除被阻止的工具。 +当同时提供 `allowed_tool_names` 和 `blocked_tool_names` 时，SDK 会先应用允许列表，然后从剩余集合中移除被阻止的工具。 -### 动态工具过滤 +### Dynamic tool filtering -对于更高级的逻辑，可以传递一个接受 [`ToolFilterContext`][agents.mcp.ToolFilterContext] 的可调用对象。可调用对象可以是同步或异步的，当应该公开工具时返回 `True`。 +对于更复杂的逻辑，传入一个可调用对象，它会接收一个 [`ToolFilterContext`][agents.mcp.ToolFilterContext]。该可调用对象可以是同步或异步的，并在应暴露该工具时返回 `True`。 ```python from pathlib import Path @@ -277,14 +277,14 @@ async with MCPServerStdio( ... ``` -过滤器上下文公开了活动的 `run_context`、请求工具的 `agent` 以及 `server_name`。 +过滤上下文会暴露当前的 `run_context`、请求工具的 `agent`，以及 `server_name`。 -## 提示词 +## Prompts -MCP服务器还可以提供提示词来动态生成智能体的指令。支持提示词的服务器会公开以下两个方法： +MCP 服务还可以提供动态生成智能体 instructions 的提示词。支持提示词的服务会暴露两个方法： -- `list_prompts()` 枚举可用的提示词模板。 -- `get_prompt(name, arguments)` 获取具体的提示词，必要时可带参数。 +- `list_prompts()` 列举可用的提示模板。 +- `get_prompt(name, arguments)` 获取具体提示词，可选带参数。 ```python from agents import Agent @@ -302,21 +302,21 @@ agent = Agent( ) ``` -## 缓存 +## Caching -所有智能体执行都会对每个MCP服务器调用 `list_tools()`。由于远程服务器可能导致显著的延迟，所有MCP服务器类都公开了 `cache_tools_list` 选项。只有当你确信工具定义不会频繁更改时才设置为 `True`。如需在之后强制获取新列表，可以在服务器实例上调用 `invalidate_tools_cache()`。 +每次智能体运行都会调用各 MCP 服务的 `list_tools()`。远程服务可能会带来明显的延迟，因此所有 MCP 服务类都提供 `cache_tools_list` 选项。仅当你确信工具定义不经常变化时才将其设为 `True`。若之后需要强制刷新列表，可在服务实例上调用 `invalidate_tools_cache()`。 -## 追踪 +## Tracing -[追踪](./tracing.md)会自动捕获MCP活动，包括： +[Tracing](./tracing.md) 会自动捕获 MCP 活动，包括： -1. 为枚举工具而对MCP服务器的调用。 -2. 与工具调用相关的MCP信息。 +1. 调用 MCP 服务列出工具。 +2. 工具调用中的 MCP 相关信息。 -![MCP追踪截图](../assets/images/mcp-tracing.jpg) +![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg) -## 参考资料 +## Further reading -- [模型上下文协议](https://modelcontextprotocol.io/) – 规范与设计指南。 -- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的stdio、SSE、可流式HTTP示例。 -- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 包含审批和连接器的完整托管MCP演示。 +- [Model Context Protocol](https://modelcontextprotocol.io/) – 规范与设计指南。 +- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的 stdio、SSE 与可流式传输 HTTP 的示例。 +- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 包含审批与连接器的完整托管 MCP 演示。 \ No newline at end of file diff --git a/docs/zh/models/index.md b/docs/zh/models/index.md index 7235d8800..b0f312bcd 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,20 +4,20 @@ search: --- # 模型 -Agents SDK 内置支持两种 OpenAI 模型： +Agents SDK 开箱即用地支持两种 OpenAI 模型形态： -- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 -- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 +- **推荐**：[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]，使用全新的 [Responses API](https://platform.openai.com/docs/api-reference/responses) 调用 OpenAI API。 +- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 调用 OpenAI API。 ## OpenAI 模型 -初始化 `Agent` 时如果没有指定模型，将使用默认模型。当前默认模型是 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)，它在智能体工作流的可预测性和低延迟之间提供了良好的平衡。 +当你在初始化 `Agent` 时未指定模型，将使用默认模型。目前默认模型是 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)，其在智能体工作流的可预期性与低延迟之间具备良好平衡。 -如果你想切换到其他模型如 [`gpt-5`](https://platform.openai.com/docs/models/gpt-5)，请按照下一节的步骤操作。 +如果你想切换到其他模型（例如 [`gpt-5`](https://platform.openai.com/docs/models/gpt-5)），请按照下一节的步骤操作。 ### 默认 OpenAI 模型 -如果你想为所有未设置自定义模型的智能体一致地使用特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。 +如果你希望对所有未设置自定义模型的智能体一致地使用特定模型，请在运行智能体之前设置环境变量 `OPENAI_DEFAULT_MODEL`。 ```bash export OPENAI_DEFAULT_MODEL=gpt-5 @@ -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-")`。 +当你以此方式使用任一 GPT-5 推理模型（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）时，SDK 会默认应用合理的 `ModelSettings`。具体而言，它会将 `reasoning.effort` 和 `verbosity` 都设置为 `"low"`。如果你希望自行构建这些设置，请调用 `agents.models.get_default_model_settings("gpt-5")`。 -为了更低延迟或特定需求，你可以选择不同的模型和设置。要调整默认模型的推理强度，请传递你自己的 `ModelSettings`： +如需更低延迟或满足特定需求，你可以选择不同的模型与设置。要为默认模型调整推理强度，请传入你自己的 `ModelSettings`： ```python from openai.types.shared import Reasoning @@ -38,17 +38,17 @@ my_agent = Agent( name="My Agent", instructions="You're a helpful agent.", model_settings=ModelSettings(reasoning=Reasoning(effort="minimal"), verbosity="low") - # 如果设置了 OPENAI_DEFAULT_MODEL=gpt-5，只传递 model_settings 即可。 - # 显式传递 GPT-5 模型名也是可以的： + # If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only model_settings works. + # It's also fine to pass a GPT-5 model name explicitly: # model="gpt-5", ) ``` -特别是对于更低延迟，使用 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 模型配合 `reasoning.effort="minimal"` 通常会比默认设置更快地返回响应。然而，Responses API 中的一些内置工具（如文件搜索和图像生成）不支持 `"minimal"` 推理强度，这就是为什么 Agents SDK 默认使用 `"low"`。 +特别地，为了更低延迟，使用 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 搭配 `reasoning.effort="minimal"` 通常会比默认设置更快返回响应。然而，Responses API 中的一些内置工具（例如 文件检索 和 图像生成）不支持 `"minimal"` 的推理强度，这也是本 Agents SDK 将默认值设为 `"low"` 的原因。 #### 非 GPT-5 模型 -如果你没有传递自定义 `model_settings` 而使用了非 GPT-5 模型名称，SDK 将回退到与任何模型兼容的通用 `ModelSettings`。 +如果你传入的是非 GPT-5 的模型名称且未提供自定义 `model_settings`，SDK 将退回到与任意模型兼容的通用 `ModelSettings`。 ## 非 OpenAI 模型 @@ -58,38 +58,38 @@ my_agent = Agent( pip install "openai-agents[litellm]" ``` -然后，使用 `litellm/` 前缀的任何[支持的模型](https://docs.litellm.ai/docs/providers)： +然后，使用带有 `litellm/` 前缀的任一[受支持模型](https://docs.litellm.ai/docs/providers)： ```python claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...) gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...) ``` -### 使用非 OpenAI 模型的其他方法 +### 使用非 OpenAI 模型的其他方式 -你有另外 3 种方式集成其他 LLM 提供商（示例[在此](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)）： +你还可以通过另外 3 种方式集成其他 LLM 提供商（示例见[此处](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] 让你在特定智能体实例上指定模型。这让你可以为不同智能体混合匹配不同提供商。查看可配置示例 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用大多数可用模型的简单方法是通过 [LiteLLM 集成](./litellm.md)。 +1. [`set_default_openai_client`][agents.set_default_openai_client] 适用于你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端的场景。适用于 LLM 提供商拥有 OpenAI 兼容 API 端点，且你可设置 `base_url` 与 `api_key` 的情况。可参见可配置示例：[examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)。 +2. [`ModelProvider`][agents.models.interface.ModelProvider] 位于 `Runner.run` 层级。它允许你为“本次运行中的所有智能体使用自定义模型提供商”。可参见可配置示例：[examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)。 +3. [`Agent.model`][agents.agent.Agent.model] 允许你在特定的 Agent 实例上指定模型。这样你就可以为不同的智能体混合搭配不同的提供商。可参见可配置示例：[examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)。使用多数可用模型的简便方式是通过 [LiteLLM 集成](./litellm.md)。 -如果你没有来自 `platform.openai.com` 的 API 密钥，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[不同的追踪处理器](../tracing.md)。 +如果你没有来自 `platform.openai.com` 的 API 密钥，我们建议通过 `set_tracing_disabled()` 禁用 追踪，或设置[不同的追踪进程](../tracing.md)。 !!! note - 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供商还不支持 Responses API。如果你的 LLM 提供商支持它，我们推荐使用 Responses。 + 在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供商尚未支持 Responses API。如果你的 LLM 提供商已支持，我们建议使用 Responses。 -## 混合和匹配模型 +## 模型的混合与搭配 -在单个工作流中，你可能想为每个智能体使用不同的模型。例如，你可以使用更小、更快的模型进行分类，而对复杂任务使用更大、更有能力的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式选择特定模型： +在单个工作流中，你可能希望为每个智能体使用不同的模型。例如，你可以用更小更快的模型做分诊，再用更大更强的模型处理复杂任务。配置 [`Agent`][agents.Agent] 时，你可以通过以下任一方式选择特定模型： -1. 传递模型名称。 -2. 传递任何模型名称 + 可以将该名称映射到模型实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 -3. 直接提供 [`Model`][agents.models.interface.Model] 实现。 +1. 传入模型名称。 +2. 传入任意模型名称 + 可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 +3. 直接提供一个 [`Model`][agents.models.interface.Model] 实现。 !!!note - 虽然我们的 SDK 支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形状，但我们建议为每个工作流使用单一模型形状，因为这两种形状支持不同的功能和工具集。如果你的工作流需要混合匹配模型形状，请确保你使用的所有功能在两者上都可用。 + 虽然我们的 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] 实现。 -当你想进一步配置智能体使用的模型时，你可以传递 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供可选的模型配置参数如 temperature。 +当你希望对某个智能体所用模型进行更深入的配置时，你可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供诸如 temperature 等可选的模型配置参数。 ```python from agents import Agent, ModelSettings @@ -138,7 +138,7 @@ english_agent = Agent( ) ``` -另外，当你使用 OpenAI 的 Responses API 时，[还有其他一些可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，你也可以使用 `extra_args` 传递它们。 +此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，你也可以通过 `extra_args` 传入。 ```python from agents import Agent, ModelSettings @@ -154,26 +154,26 @@ english_agent = Agent( ) ``` -## 使用其他 LLM 提供商时的常见问题 +## 使用其他 LLM 提供商的常见问题 ### 追踪客户端错误 401 -如果你遇到与追踪相关的错误，这是因为追踪被上传到 OpenAI 服务器，而你没有 OpenAI API 密钥。你有三个选项来解决这个问题： +如果你遇到与追踪相关的错误，这是因为追踪会上传至 OpenAI 服务，而你没有 OpenAI API 密钥。你有三种解决方案： 1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. 为追踪设置 OpenAI 密钥：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API 密钥将仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。 -3. 使用非 OpenAI 追踪处理器。参见 [追踪文档](../tracing.md#custom-tracing-processors)。 +2. 为追踪设置一个 OpenAI 密钥：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API 密钥仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。 +3. 使用非 OpenAI 的追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。 ### Responses API 支持 -SDK 默认使用 Responses API，但大多数其他 LLM 提供商还不支持它。你可能会因此看到 404 或类似问题。要解决此问题，你有两个选项： +SDK 默认使用 Responses API，但多数其他 LLM 提供商尚未支持。因此你可能会看到 404 或类似问题。为解决此问题，你有两种选择： -1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。如果你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`，这将会生效。 -2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 +1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。如果你通过环境变量设置了 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`，这将有效。 +2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例见[此处](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 -### 结构化输出支持 +### Structured outputs 支持 -一些模型提供商不支持[结构化输出](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致如下错误： +一些模型提供商不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下的错误： ``` @@ -181,12 +181,12 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -这是某些模型提供商的缺陷 - 它们支持 JSON 输出，但不允许你指定输出使用的 `json_schema`。我们正在研究解决方案，但建议你依赖支持 JSON 模式输出的提供商，否则你的应用经常会因为格式错误的 JSON 而崩溃。 +这是部分模型提供商的不足——它们支持 JSON 输出，但不允许你为输出指定 `json_schema`。我们正在着手修复，但我们建议依赖支持 JSON schema 输出的提供商，否则你的应用可能会因为 JSON 格式不正确而经常出错。 -## 跨提供商混合模型 +## 跨提供商混用模型 -你需要了解模型提供商之间的功能差异，否则可能会遇到错误。例如，OpenAI 支持结构化输出、多模态输入以及托管文件搜索和网络搜索，但许多其他提供商不支持这些功能。请注意这些限制： +你需要了解不同模型提供商之间的功能差异，否则可能会遇到错误。例如，OpenAI 支持 structured outputs、多模态输入以及由OpenAI托管的工具中的 文件检索 和 网络检索，但许多其他提供商并不支持这些功能。需要注意以下限制： -- 不要向不理解它们的提供商发送不受支持的 `tools` -- 在调用仅支持文本的模型前过滤掉多模态输入 -- 注意不支持结构化 JSON 输出的提供商偶尔会生成无效的 JSON \ No newline at end of file +- 不要向不理解的提供商发送不受支持的 `tools` +- 在调用仅支持文本的模型前，过滤掉多模态输入 +- 注意不支持结构化 JSON 输出的提供商偶尔会生成无效 JSON。 \ No newline at end of file diff --git a/docs/zh/models/litellm.md b/docs/zh/models/litellm.md index 4b1db4783..632fbac53 100644 --- a/docs/zh/models/litellm.md +++ b/docs/zh/models/litellm.md @@ -6,29 +6,29 @@ search: !!! note - LiteLLM 集成处于测试阶段。特别是小型模型提供商可能会遇到问题。如果有问题，请通过 [GitHub issues](https://github.com/openai/openai-agents-python/issues) 报告，我们会快速修复。 + LiteLLM 集成处于测试阶段。你在使用部分模型提供方（特别是较小的提供方）时可能会遇到问题。请通过 [Github issues](https://github.com/openai/openai-agents-python/issues) 报告，我们会尽快修复。 -[LiteLLM](https://docs.litellm.ai/docs/) 是一个允许你通过单一接口使用 100+ 模型的库。我们在 Agents SDK 中添加了 LiteLLM 集成，让你可以使用任何 AI 模型。 +[LiteLLM](https://docs.litellm.ai/docs/) 是一个库，允许你通过统一接口使用 100+ 个模型。我们在 Agents SDK 中加入了 LiteLLM 集成，以便你可以使用任意 AI 模型。 ## 设置 -你需要确保 `litellm` 可用。你可以通过安装可选的 `litellm` 依赖组来实现这一点： +你需要确保已安装 `litellm`。可以通过安装可选的 `litellm` 依赖组来完成： ```bash pip install "openai-agents[litellm]" ``` -完成后，你可以在任何智能体中使用 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 +完成后，你可以在任意智能体中使用 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 -## 例 +## 示例 -这是一个完全工作的示例。当你运行它时，系统会要求你输入模型名称和 API 密钥。例如，你可以输入： +下面是一个可完整运行的示例。运行后会提示你输入模型名称和 API 密钥。例如，你可以输入： -- 模型输入 `openai/gpt-4.1`，以及你的 OpenAI API 密钥 -- 模型输入 `anthropic/claude-3-5-sonnet-20240620`，以及你的 Anthropic API 密钥 -- 等等 +- 模型使用 `openai/gpt-4.1`，并提供你的 OpenAI API 密钥 +- 模型使用 `anthropic/claude-3-5-sonnet-20240620`，并提供你的 Anthropic API 密钥 +- 等等 -有关 LiteLLM 支持的完整模型列表，请参见 [litellm 提供商文档](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 请求会通过 `result.context_wrapper.usage` 报告令牌和请求计数，就像内置的 OpenAI 模型一样。 \ No newline at end of file +启用 `include_usage=True` 后，LiteLLM 请求会通过 `result.context_wrapper.usage` 报告 token 和请求计数，与内置的 OpenAI 模型一致。 \ No newline at end of file diff --git a/docs/zh/multi_agent.md b/docs/zh/multi_agent.md index fec68f45a..575058875 100644 --- a/docs/zh/multi_agent.md +++ b/docs/zh/multi_agent.md @@ -4,38 +4,38 @@ search: --- # 多智能体编排 -编排指的是应用中智能体的流程。哪些智能体运行，以什么顺序运行，它们如何决定接下来发生什么？编排智能体主要有两种方式： +编排指的是你在应用中对智能体的流程控制：运行哪些智能体、以什么顺序运行，以及它们如何决定下一步做什么。编排智能体主要有两种方式： -1. 允许LLM做出决策：这使用LLM的智能来计划、推理，并基于此决定采取哪些步骤。 -2. 通过代码编排：通过你的代码确定智能体的流程。 +1. 让 LLM 决策：利用 LLM 的智能进行规划、推理，并据此决定采取哪些步骤。 +2. 通过代码编排：通过你的代码决定智能体的流程。 -你可以混合搭配这些模式。每种方式都有自己的权衡，如下所述。 +你可以混合搭配这些模式。每种方式都有各自的权衡，详见下文。 -## 通过LLM编排 +## 通过 LLM 编排 -智能体是一个配备了指令、工具和交接的LLM。这意味着给定一个开放式任务时，LLM可以自主计划如何解决这个问题，使用工具采取行动和获取数据，并使用交接将任务委托给子智能体。例如，研究智能体可以配备如下工具： +一个智能体是一个具备 instructions、tools 和 任务转移 的 LLM。这意味着在给定一个开放式任务时，LLM 能够自主规划如何完成任务，使用工具采取行动并获取数据，并通过任务转移将任务委派给子智能体。比如，一个研究型智能体可以配备如下工具： -- 网络搜索以在线查找信息 -- 文件搜索和检索以搜索专有数据和连接 -- 计算机使用以在计算机上执行操作 -- 代码执行以进行数据分析 -- 交接给专门擅长规划、报告撰写等的专业智能体。 +- 网络检索以在线查找信息 +- 文件检索与读取以搜索专有数据和连接 +- 计算机操作以在计算机上执行操作 +- 代码执行以进行数据分析 +- 任务转移至擅长规划、报告撰写等的专用智能体 -这种模式在任务是开放式且你希望依赖LLM的智能时非常出色。这里最重要的策略是： +当任务是开放式且你希望依赖 LLM 的智能时，此模式非常适合。这里最重要的策略包括： -1. 投资好的提示。明确说明可用的工具、如何使用它们以及它必须在哪些参数内操作。 -2. 监控你的应用并进行迭代。看看哪里出了问题，并对你的提示进行迭代。 -3. 允许智能体进行内省和改进。例如，在循环中运行它，让它自我批评；或者提供错误消息并让它改进。 -4. 拥有专门擅长一项任务的专业智能体，而不是期望通用智能体擅长任何事情。 -5. 投资[评估](https://platform.openai.com/docs/guides/evals)。这让你可以训练你的智能体改进并更好地完成任务。 +1. 投入精力打磨提示词。清楚说明可用的工具、如何使用它们，以及必须遵循的 参数 范围。 +2. 监控你的应用并持续迭代。观察问题出现在哪里，并迭代优化提示词。 +3. 允许智能体自省与改进。例如，将其运行在循环中，让其自我评估；或者提供错误信息以便其改进。 +4. 使用在单一任务上表现突出的专用智能体，而不是期望一个通用智能体在所有方面都足够出色。 +5. 投入于[评测 (evals)](https://platform.openai.com/docs/guides/evals)。这有助于训练你的智能体不断改进并更好地完成任务。 ## 通过代码编排 -虽然通过LLM编排很强大，但通过代码编排使任务在速度、成本和性能方面更加确定和可预测。这里的常见模式是： +虽然通过 LLM 编排功能强大，但通过代码编排能让任务在速度、成本和性能方面更加确定且可预测。常见模式包括： -- 使用[结构化输出](https://platform.openai.com/docs/guides/structured-outputs)生成格式良好的数据，你可以用代码检查这些数据。例如，你可以要求智能体将任务分类为几个类别，然后根据该类别选择下一个智能体。 -- 通过将前一个的输出转换为下一个的输入来链接多个智能体。你可以将撰写博客文章之类的任务分解为一系列步骤——进行研究、撰写大纲、撰写博客文章、批评它，然后改进它。 -- 在`while`循环中运行执行任务的智能体和提供评估与反馈的智能体，直到评估者说输出通过某些标准。 -- 并行运行多个智能体，例如通过Python原语如`asyncio.gather`。当你有多个不相互依赖的任务时，这对于速度很有用。 +- 使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)生成你可用代码检查的 格式良好的数据。比如，你可以让智能体将任务归类到几个目录，然后根据该目录选择下一个智能体。 +- 将多个智能体串联，把一个智能体的输出转换为下一个的输入。你可以将撰写博客文章之类的任务分解为一系列步骤——做研究、写大纲、写正文、批评性审阅，然后改进。 +- 让执行任务的智能体与负责评估并提供反馈的智能体一起在 `while` 循环中运行，直到评估者认为输出满足某些标准。 +- 并行运行多个智能体，例如通过 Python 基本组件如 `asyncio.gather`。当你有多个彼此独立的任务时，这有助于加速。 -我们在[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)中有许多示例。 \ No newline at end of file +我们在[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)中提供了诸多 code examples。 \ No newline at end of file diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index 6f64776be..67cc8baca 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -6,7 +6,7 @@ search: ## 创建项目和虚拟环境 -您只需要执行一次此操作。 +你只需执行一次。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 激活虚拟环境 -每次开始新的终端会话时都要执行此操作。 +每次打开新的终端会话都需要执行。 ```bash source .venv/bin/activate @@ -25,20 +25,20 @@ source .venv/bin/activate ### 安装 Agents SDK ```bash -pip install openai-agents # 或者 `uv add openai-agents` 等 +pip install openai-agents # or `uv add openai-agents`, etc ``` ### 设置 OpenAI API 密钥 -如果您还没有 OpenAI API 密钥，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建。 +如果你还没有密钥，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建一个 OpenAI API 密钥。 ```bash export OPENAI_API_KEY=sk-... ``` -## 创建您的第一个智能体 +## 创建你的第一个智能体 -智能体通过指令、名称和可选配置（如 `model_config`）来定义 +智能体由 instructions、名称以及可选的配置（例如 `model_config`）定义。 ```python from agents import Agent @@ -49,9 +49,9 @@ agent = Agent( ) ``` -## 添加更多智能体 +## 再添加几个智能体 -可以以相同方式定义额外的智能体。`handoff_descriptions` 为确定交接路由提供额外的上下文 +可以用同样的方式定义更多智能体。`handoff_descriptions` 为确定任务转移路由提供额外上下文。 ```python from agents import Agent @@ -69,9 +69,9 @@ math_tutor_agent = Agent( ) ``` -## 定义您的交接 +## 定义你的任务转移 -在每个智能体上，您可以定义一个出站交接选项清单，智能体可以从中选择来决定如何在任务上取得进展。 +在每个智能体上，你可以定义一个外发的任务转移选项清单，供智能体选择以决定如何推进其任务。 ```python triage_agent = Agent( @@ -83,7 +83,7 @@ triage_agent = Agent( ## 运行智能体编排 -让我们检查工作流是否运行正常，以及分诊智能体是否正确地在这两个专业智能体之间进行路由。 +让我们检查工作流是否运行，以及分诊智能体是否正确地在两个专家型智能体之间路由。 ```python from agents import Runner @@ -93,9 +93,9 @@ async def main(): print(result.final_output) ``` -## 添加护栏 +## 添加安全防护措施 -您可以定义自定义护栏在输入或输出上运行。 +你可以定义自定义的安全防护措施，用于输入或输出。 ```python from agents import GuardrailFunctionOutput, Agent, Runner @@ -121,9 +121,9 @@ async def homework_guardrail(ctx, agent, input_data): ) ``` -## 整合在一起 +## 汇总并运行 -让我们把所有内容整合在一起，运行整个工作流，使用交接和输入护栏。 +让我们把以上内容整合起来，使用任务转移和输入安全防护措施运行整个工作流。 ```python from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner @@ -190,14 +190,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 查看您的追踪 +## 查看你的追踪 -要查看智能体运行期间发生的情况，请导航到 [OpenAI 仪表板中的追踪查看器](https://platform.openai.com/traces) 查看智能体运行的追踪。 +要回顾智能体运行期间发生的事情，请前往 [OpenAI 仪表板中的 Trace 查看器](https://platform.openai.com/traces)查看你的智能体运行追踪。 ## 后续步骤 了解如何构建更复杂的智能体流程： -- 了解如何配置[智能体](agents.md)。 -- 了解[运行智能体](running_agents.md)。 -- 了解[工具](tools.md)、[护栏](guardrails.md)和[模型](models/index.md)。 \ No newline at end of file +- 了解如何配置[智能体](agents.md)。 +- 了解[运行智能体](running_agents.md)。 +- 了解[工具](tools.md)、[安全防护措施](guardrails.md)和[模型](models/index.md)。 \ No newline at end of file diff --git a/docs/zh/realtime/guide.md b/docs/zh/realtime/guide.md index 969776939..aa8ca4ec4 100644 --- a/docs/zh/realtime/guide.md +++ b/docs/zh/realtime/guide.md @@ -4,65 +4,65 @@ search: --- # 指南 -本指南深入介绍如何使用 OpenAI Agents SDK 的实时功能构建支持语音的 AI 智能体。 +本指南将深入介绍如何使用 OpenAI Agents SDK 的实时功能来构建语音交互的 AI 智能体。 !!! warning "测试版功能" -实时智能体处于测试版。随着我们改进实现，可能会出现重大更改。 +实时智能体处于测试阶段。随着实现的改进，可能会发生不兼容变更。 ## 概述 -实时智能体支持对话流程，实时处理音频和文本输入，并以实时音频进行响应。它们与 OpenAI 的实时 API 保持持久连接，实现低延迟的自然语音对话，并能优雅地处理打断情况。 +实时智能体支持对话式流程，可实时处理音频与文本输入，并以实时音频作出响应。它们与 OpenAI 的 Realtime API 保持持久连接，实现低延迟的自然语音对话，并能优雅地处理中断。 ## 架构 ### 核心组件 -实时系统由以下关键组件组成： +实时系统由以下关键组件构成： -- **RealtimeAgent**: 由指令、工具、交接组成的智能体。 -- **RealtimeRunner**: 管理配置。你可以调用 `runner.run()` 来获取会话。 -- **RealtimeSession**: 单个交互会话。通常，每次用户开始对话时创建一个，并在对话结束时保持活动状态。 -- **RealtimeModel**: 底层模型接口（通常是 OpenAI 的 WebSocket 实现） +- **RealtimeAgent**: 一个智能体，通过 instructions、工具和任务转移进行配置。 +- **RealtimeRunner**: 管理配置。可调用 `runner.run()` 获取会话。 +- **RealtimeSession**: 一次交互会话。通常在每次用户开始对话时创建一个，并在对话结束前保持存活。 +- **RealtimeModel**: 底层模型接口（通常是 OpenAI 的 WebSocket 实现） ### 会话流程 典型的实时会话流程如下： -1. 使用指令、工具、交接**创建 RealtimeAgent**。 -2. 使用智能体和配置选项**设置 RealtimeRunner**。 -3. 使用 `await runner.run()`**开始会话**，返回 RealtimeSession。 -4. 使用 `send_audio()` 或 `send_message()`**发送音频或文本消息**。 -5. 通过迭代会话**监听事件**。事件包括音频输出、转录、工具调用、交接、错误。 -6. **处理打断**，当用户在智能体说话时覆盖说话，这将自动停止当前音频生成。 +1. **创建 RealtimeAgent**，配置 instructions、工具和任务转移。 +2. **设置 RealtimeRunner**，传入智能体与配置选项。 +3. **启动会话**，使用 `await runner.run()` 获取 `RealtimeSession`。 +4. **发送音频或文本消息** 到会话，使用 `send_audio()` 或 `send_message()`。 +5. **监听事件**，通过遍历会话获取事件——包括音频输出、转录文本、工具调用、任务转移和错误。 +6. **处理中断**，当用户打断智能体说话时，会自动停止当前音频生成。 -会话维护对话历史并管理与实时模型的持久连接。 +会话维护对话历史，并管理与实时模型的持久连接。 ## 智能体配置 -RealtimeAgent 的工作方式与常规的 Agent 类相似，但有一些关键区别。有关完整的 API 详情，请参阅 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 参考。 +RealtimeAgent 的工作方式与常规 Agent 类似，但有一些关键差异。完整 API 详情见 [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API 参考。 -与常规智能体的主要区别: +相较常规智能体的主要差异： -- 模型选择在会话级别配置，而不是智能体级别。 -- 不支持结构化输出（不支持 `outputType`）。 -- 可以为每个智能体配置语音，但在第一个智能体发言后无法更改。 -- 所有其他功能如工具、交接和指令的工作方式相同。 +- 模型选择在会话级别配置，而非智能体级别。 +- 不支持 structured output（不支持 `outputType`）。 +- 语音可按智能体进行配置，但在第一个智能体发声后不可再更改。 +- 其他功能如工具、任务转移和 instructions 的工作方式相同。 ## 会话配置 ### 模型设置 -会话配置允许您控制底层实时模型的行为。您可以配置模型名称（如 `gpt-realtime`）、语音选择（alloy、echo、fable、onyx、nova、shimmer）以及支持的模态（文本和/或音频）。输入和输出的音频格式都可以设置，PCM16 是默认格式。 +会话配置允许控制底层实时模型的行为。你可以配置模型名称（如 `gpt-realtime`）、语音选择（alloy、echo、fable、onyx、nova、shimmer），以及支持的模态（文本和/或音频）。音频格式可分别为输入和输出设置，默认是 PCM16。 ### 音频配置 -音频设置控制会话如何处理语音输入和输出。您可以配置使用 Whisper 等模型的输入音频转录，设置语言偏好，并提供转录提示以提高特定领域术语的准确性。轮流检测设置控制智能体何时开始和停止响应，包括语音活动检测阈值、静音持续时间和检测到的语音周围的填充选项。 +音频设置控制会话如何处理语音输入与输出。你可以使用如 Whisper 等模型进行输入音频转录、设置语言偏好，并提供转录提示以提升特定领域术语的识别准确率。轮次检测（turn detection）设置用于控制智能体何时开始与停止响应，可配置语音活动检测阈值、静音时长，以及检测语音周围的填充时长。 -## 工具和函数 +## 工具与函数 ### 添加工具 -就像常规智能体一样，实时智能体支持在对话期间执行的函数工具： +与常规智能体相同，实时智能体支持在对话中执行的工具调用（function tools）： ```python from agents import function_tool @@ -86,11 +86,11 @@ agent = RealtimeAgent( ) ``` -## 交接 +## 任务转移 -### 创建交接 +### 创建任务转移 -交接允许在专门智能体之间转移对话。 +任务转移允许在专门化的智能体之间转移对话。 ```python from agents.realtime import realtime_handoff @@ -119,22 +119,22 @@ main_agent = RealtimeAgent( ## 事件处理 -会话流式传输事件，您可以通过迭代会话对象来监听这些事件。事件包括音频输出块、转录结果、工具执行开始和结束、智能体交接和错误。需要处理的关键事件包括： +会话会以流的形式发送事件，你可以通过遍历会话对象来监听。事件包括音频输出片段、转录结果、工具执行的开始与结束、智能体任务转移以及错误。关键事件包括： -- **audio**：来自智能体响应的原始音频数据 -- **audio_end**：智能体结束发言 -- **audio_interrupted**：用户打断智能体 -- **tool_start/tool_end**：工具执行生命周期 -- **handoff**：发生智能体交接 -- **error**：处理过程中发生错误 +- **audio**: 来自智能体响应的原始音频数据 +- **audio_end**: 智能体完成发声 +- **audio_interrupted**: 用户打断了智能体 +- **tool_start/tool_end**: 工具执行生命周期 +- **handoff**: 发生了智能体任务转移 +- **error**: 处理过程中发生错误 -有关完整的事件详情，请参阅 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]。 +完整事件详情参见 [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent]。 -## 护栏功能 +## 安全防护措施 -实时智能体仅支持输出护栏。这些护栏会进行防抖处理并定期运行（不是每个词都运行），以避免实时生成期间的性能问题。默认的防抖长度是 100 个字符，但这是可配置的。 +实时智能体仅支持输出类安全防护措施。这些防护会去抖并定期运行（不是每个词都运行），以避免实时生成期间的性能问题。默认去抖长度为 100 个字符，可配置。 -护栏可以直接附加到 `RealtimeAgent`，也可以通过会话的 `run_config` 提供。来自两个来源的护栏会一起运行。 +安全防护措施可以直接附加到 `RealtimeAgent`，或通过会话的 `run_config` 提供。两处提供的防护会共同生效。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -152,25 +152,25 @@ agent = RealtimeAgent( ) ``` -当护栏被触发时，它会生成一个 `guardrail_tripped` 事件，并可以中断智能体的当前响应。防抖行为有助于在安全性和实时性能需求之间取得平衡。与文本智能体不同，实时智能体在护栏被触发时**不会**引发异常。 +当安全防护措施被触发时，会生成 `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] 接口的直接访问，适用于需要对连接进行更低层级控制的高级用例。 ## 示例 -有关完整的工作示例，请查看 [examples/realtime 目录](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)，其中包含带 UI 组件和不带 UI 组件的演示。 \ No newline at end of file +要查看完整可运行的示例，请访问 [examples/realtime 目录](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)，其中包含带 UI 与不带 UI 的演示。 \ No newline at end of file diff --git a/docs/zh/realtime/quickstart.md b/docs/zh/realtime/quickstart.md index c14d2a461..449e307e4 100644 --- a/docs/zh/realtime/quickstart.md +++ b/docs/zh/realtime/quickstart.md @@ -2,28 +2,28 @@ search: exclude: true --- -# 快速入门 +# 快速开始 -实时智能体通过 OpenAI 的 Realtime API 实现与 AI 智能体的语音对话。本指南将逐步介绍如何创建您的第一个实时语音智能体。 +实时智能体通过 OpenAI 的 Realtime API 实现与你的 AI 智能体进行语音对话。本指南将带你创建第一个实时语音智能体。 -!!! warning "测试版功能" -实时智能体处于测试阶段。随着我们改进实现，可能会出现重大更改。 +!!! warning "测试功能" +Realtime agents 处于测试阶段。随着我们改进实现，可能会出现不兼容的变更。 -## 前提条件 +## 前置条件 -- Python 3.9 或更高版本 -- OpenAI API 密钥 -- 对 OpenAI Agents SDK 的基本了解 +- Python 3.9 或更高版本 +- OpenAI API key +- 对 OpenAI Agents SDK 的基本了解 ## 安装 -如果尚未安装，请安装 OpenAI Agents SDK: +如果尚未安装，请安装 OpenAI Agents SDK： ```bash pip install openai-agents ``` -## 创建您的第一个实时智能体 +## 创建你的第一个实时智能体 ### 1. 导入所需组件 @@ -32,7 +32,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. 创建实时智能体 +### 2. 创建一个实时智能体 ```python agent = RealtimeAgent( @@ -111,7 +111,7 @@ def _truncate_str(s: str, max_length: int) -> str: ## 完整示例 -这是一个完整的工作示例: +以下是可运行的完整示例： ```python import asyncio @@ -192,40 +192,40 @@ if __name__ == "__main__": ### 模型设置 -- `model_name`: 从可用的实时模型中选择 (例如: `gpt-realtime`) -- `voice`: 选择语音 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) -- `modalities`: 启用文本或音频 (`["text"]` 或 `["audio"]`) +- `model_name`: 从可用的实时模型中选择（例如，`gpt-realtime`） +- `voice`: 选择语音（`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`） +- `modalities`: 启用文本或音频（`["text"]` 或 `["audio"]`） ### 音频设置 -- `input_audio_format`: 输入音频格式 (`pcm16`, `g711_ulaw`, `g711_alaw`) -- `output_audio_format`: 输出音频格式 -- `input_audio_transcription`: 转录配置 +- `input_audio_format`: 输入音频格式（`pcm16`、`g711_ulaw`、`g711_alaw`） +- `output_audio_format`: 输出音频格式 +- `input_audio_transcription`: 转写配置 ### 轮次检测 -- `type`: 检测方法 (`server_vad`, `semantic_vad`) -- `threshold`: 语音活动阈值 (0.0-1.0) -- `silence_duration_ms`: 检测轮次结束的静音时长 -- `prefix_padding_ms`: 语音前的音频填充 +- `type`: 检测方法（`server_vad`、`semantic_vad`） +- `threshold`: 语音活动阈值（0.0-1.0） +- `silence_duration_ms`: 用于检测轮次结束的静音时长 +- `prefix_padding_ms`: 语音开始前的音频填充 ## 后续步骤 -- [详细了解实时智能体](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 key： ```bash export OPENAI_API_KEY="your-api-key-here" ``` -或者在创建会话时直接传递: +或在创建会话时直接传入： ```python session = await runner.run(model_config={"api_key": "your-api-key"}) diff --git a/docs/zh/release.md b/docs/zh/release.md index 9228910b0..6e8b84378 100644 --- a/docs/zh/release.md +++ b/docs/zh/release.md @@ -4,29 +4,29 @@ search: --- # 发布流程/变更日志 -本项目采用稍作修改的语义化版本控制，使用 `0.Y.Z` 形式。开头的 `0` 表示 SDK 仍在快速发展。各组件的增量如下： +本项目遵循稍作修改的语义化版本规范，采用 `0.Y.Z` 形式。前导的 `0` 表示 SDK 仍在快速演进中。各部分的递增规则如下： -## 次要（`Y`）版本 +## 次版本（`Y`） -对于未标记为beta的公共接口的**重大更改**，我们将增加次要版本 `Y`。例如，从 `0.0.x` 到 `0.1.x` 的更新可能包含重大更改。 +对于未标注为 beta 的任何公共接口出现的**破坏性变更**，我们将提升次版本号 `Y`。例如，从 `0.0.x` 到 `0.1.x` 可能包含破坏性变更。 -如果你想避免重大更改，我们建议在你的项目中固定到 `0.0.x` 版本。 +如果你不希望引入破坏性变更，建议在你的项目中固定到 `0.0.x` 版本。 -## 补丁（`Z`）版本 +## 修订版本（`Z`） -对于非重大更改，我们将递增 `Z`： +对于非破坏性变更，我们将提升 `Z`： -- 错误修复 +- Bug 修复 - 新功能 -- 私有接口的更改 -- beta功能的更新 +- 私有接口的变更 +- beta 功能的更新 -## 重大更改变更日志 +## 破坏性变更日志 ### 0.2.0 -在此版本中，一些以前接受 `Agent` 作为参数的地方现在改为接受 `AgentBase` 作为参数。例如，MCP 服务器中的 `list_tools()` 调用。这只是一个类型更改，你仍然可以接收 `Agent` 对象。要更新，只需通过将 `Agent` 替换为 `AgentBase` 来修复类型错误。 +此版本中，若干原本接收 `Agent` 作为参数的地方，现改为接收 `AgentBase` 作为参数。例如，MCP 服务中的 `list_tools()` 调用。这只是纯粹的类型层面的变更，你仍将收到 `Agent` 对象。要更新的话，只需将类型错误通过把 `Agent` 替换为 `AgentBase` 修复即可。 ### 0.1.0 -在此版本中，[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] 添加了两个新参数：`run_context` 和 `agent`。你需要将这些参数添加到任何继承自 `MCPServer` 的类中。 \ No newline at end of file +在此版本中，[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] 增加了两个新参数：`run_context` 和 `agent`。你需要在任何继承 `MCPServer` 的类中添加这些参数。 \ No newline at end of file diff --git a/docs/zh/repl.md b/docs/zh/repl.md index 83482beb1..0ce359f33 100644 --- a/docs/zh/repl.md +++ b/docs/zh/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`（然后按回车），或使用键盘快捷键 `Ctrl-D`。 \ No newline at end of file diff --git a/docs/zh/results.md b/docs/zh/results.md index a9002fd2b..f1f8a4c16 100644 --- a/docs/zh/results.md +++ b/docs/zh/results.md @@ -4,53 +4,53 @@ search: --- # 结果 -当你调用`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` 类型的对象 +- `str`，如果最后一个智能体没有定义 `output_type` +- 类型为 `last_agent.output_type` 的对象，如果智能体定义了输出类型。 !!! note - `final_output` 的类型是 `Any`。由于交接的存在，我们无法对其进行静态类型化。如果发生交接，意味着任何智能体都可能成为最后一个智能体，因此我们无法静态地知道可能的输出类型集合。 + `final_output` 的类型是 `Any`。由于任务转移，我们无法进行静态类型标注。如果发生任务转移，意味着任意智能体都有可能成为最后一个运行的智能体，因此我们在静态上无法知道可能的输出类型集合。 -## 下一轮输入 +## 下一轮的输入 -你可以使用 [`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 将结果转换为输入列表，将你提供的原始输入与智能体运行期间生成的项目连接起来。这使得将一个智能体运行的输出传递到另一个运行中，或者在循环中运行并每次添加新的用户输入变得很方便。 +你可以使用 [`result.to_input_list()`][agents.result.RunResultBase.to_input_list] 将结果转换为一个输入列表，它会把你提供的原始输入与智能体运行期间生成的项连接起来。这样可以方便地将一次智能体运行的输出传入另一轮运行，或在循环中运行并在每次追加新的用户输入。 ## 最后一个智能体 -[`last_agent`][agents.result.RunResultBase.last_agent] 属性包含最后运行的智能体。根据你的应用，这在用户下次输入某些内容时通常很有用。例如，如果你有一个前线分类智能体交接给特定语言的智能体，你可以存储最后一个智能体，并在用户下次向智能体发送消息时重用它。 +[`last_agent`][agents.result.RunResultBase.last_agent] 属性包含最后一个运行的智能体。根据你的应用场景，这对下一次用户输入时通常很有用。比如，如果你有一个前线分诊智能体会将任务转移给特定语言的智能体，你可以存储最后一个智能体，并在用户下次与智能体对话时复用它。 -## 新项目 +## 新项 -[`new_items`][agents.result.RunResultBase.new_items] 属性包含运行期间生成的新项目。这些项目是 [`RunItem`][agents.items.RunItem]。运行项目包装了LLM生成的原始项目。 +[`new_items`][agents.result.RunResultBase.new_items] 属性包含运行期间生成的新项。每个项都是 [`RunItem`][agents.items.RunItem]。运行项封装了由 LLM 生成的原始项。 -- [`MessageOutputItem`][agents.items.MessageOutputItem] 表示来自LLM的消息。原始项目是生成的消息。 -- [`HandoffCallItem`][agents.items.HandoffCallItem] 表示LLM调用了交接工具。原始项目是LLM的工具调用项目。 -- [`HandoffOutputItem`][agents.items.HandoffOutputItem] 表示发生了交接。原始项目是对交接工具调用的工具响应。你也可以从项目中访问源/目标智能体。 -- [`ToolCallItem`][agents.items.ToolCallItem] 表示LLM调用了工具。 -- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] 表示调用了工具。原始项目是工具响应。你也可以从项目中访问工具输出。 -- [`ReasoningItem`][agents.items.ReasoningItem] 表示来自LLM的推理项目。原始项目是生成的推理。 +- [`MessageOutputItem`][agents.items.MessageOutputItem] 表示来自 LLM 的消息。原始项是生成的消息。 +- [`HandoffCallItem`][agents.items.HandoffCallItem] 表示 LLM 调用了任务转移工具。原始项是来自 LLM 的工具调用项。 +- [`HandoffOutputItem`][agents.items.HandoffOutputItem] 表示发生了任务转移。原始项是对任务转移工具调用的工具响应。你也可以从该项访问源/目标智能体。 +- [`ToolCallItem`][agents.items.ToolCallItem] 表示 LLM 调用了某个工具。 +- [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] 表示某个工具被调用。原始项是工具响应。你也可以从该项访问工具输出。 +- [`ReasoningItem`][agents.items.ReasoningItem] 表示来自 LLM 的推理项。原始项是生成的推理内容。 ## 其他信息 -### 护栏结果 +### 安全防护措施结果 -[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] 和 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] 属性包含护栏的结果（如果有）。护栏结果有时包含有用的信息，你可能想要记录或存储，因此我们让你可以访问这些信息。 +[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] 和 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] 属性包含安全防护措施（如有）的结果。安全防护措施结果有时包含你可能希望记录或存储的有用信息，因此我们提供了访问方式。 ### 原始响应 -[`raw_responses`][agents.result.RunResultBase.raw_responses] 属性包含LLM生成的 [`ModelResponse`][agents.items.ModelResponse]。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] 属性包含由 LLM 生成的 [`ModelResponse`][agents.items.ModelResponse]。 ### 原始输入 -[`input`][agents.result.RunResultBase.input] 属性包含你提供给`run`方法的原始输入。在大多数情况下你不需要这个，但如果你需要，它可供你使用。 \ No newline at end of file +[`input`][agents.result.RunResultBase.input] 属性包含你提供给 `run` 方法的原始输入。多数情况下你不需要它，但在需要时可用。 \ No newline at end of file diff --git a/docs/zh/running_agents.md b/docs/zh/running_agents.md index 72df09cfd..022b05185 100644 --- a/docs/zh/running_agents.md +++ b/docs/zh/running_agents.md @@ -4,11 +4,11 @@ search: --- # 运行智能体 -你可以通过 [`Runner`][agents.run.Runner] 类来运行智能体。你有3个选项： +你可以通过 [`Runner`][agents.run.Runner] 类来运行智能体。你有 3 个选项： -1. [`Runner.run()`][agents.run.Runner.run]，异步运行并返回 [`RunResult`][agents.result.RunResult]。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync]，这是一个同步方法，底层运行 `.run()`。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，异步运行并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式模式调用LLM，并在接收到事件时将这些事件流式传输给你。 +1. [`Runner.run()`][agents.run.Runner.run]：异步运行并返回 [`RunResult`][agents.result.RunResult]。 +2. [`Runner.run_sync()`][agents.run.Runner.run_sync]：同步方法，内部调用 `.run()`。 +3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]：异步运行并返回 [`RunResultStreaming`][agents.result.RunResultStreaming]。它以流式模式调用 LLM，并在接收时将事件流式传输给你。 ```python from agents import Agent, Runner @@ -23,77 +23,77 @@ async def main(): # Infinite loop's dance ``` -阅读更多内容请参考[结果指南](results.md)。 +更多内容见[结果指南](results.md)。 ## 智能体循环 -当你在`Runner`中使用运行方法时，你传入一个起始智能体和输入。输入可以是字符串（被视为用户消息），或者输入项列表，这些是OpenAI响应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 - LLM输出是否被视为"最终输出"的规则是它产生所需类型的文本输出，并且没有工具调用。 + 判断 LLM 输出是否为“最终输出”的规则是：输出生成了所需类型的文本，且没有工具调用。 ## 流式传输 -流式传输允许你在LLM运行时额外接收流式传输事件。流式传输完成后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含有关运行的完整信息，包括产生的所有新输出。你可以调用 `.stream_events()` 来获取流式传输事件。阅读更多内容请参考[流式传输指南](streaming.md)。 +流式传输允许你在 LLM 运行时额外接收流式事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含关于此次运行的完整信息，包括所有新产出的输出。你可以调用 `.stream_events()` 获取流式事件。更多内容见[流式传输指南](streaming.md)。 ## 运行配置 `run_config` 参数允许你为智能体运行配置一些全局设置： -- [`model`][agents.run.RunConfig.model]: 允许设置要使用的全局LLM模型，不管每个智能体有什么`model`。 -- [`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]：允许设置一个全局的 LLM 模型使用，而不受各个 Agent 自身 `model` 的影响。 +- [`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]：要包含在所有追踪中的元数据。 -## 对话/聊天线程 +## 会话/聊天线程 -调用任何运行方法都可能导致一个或多个智能体运行（因此一个或多个LLM调用），但它代表聊天对话中的单个逻辑轮次。例如： +调用任一运行方法都可能导致一个或多个智能体运行（因此可能会有一次或多次 LLM 调用），但它表示聊天会话中的单个逻辑轮次。例如： 1. 用户轮次：用户输入文本 -2. 运行器运行：第一个智能体调用LLM，运行工具，交接给第二个智能体，第二个智能体运行更多工具，然后产生输出。 +2. Runner 运行：第一个智能体调用 LLM、运行工具、进行任务转移到第二个智能体，第二个智能体再运行更多工具，然后产出输出。 -在智能体运行结束时，你可以选择向用户显示什么。例如，你可能会向用户显示智能体生成的每个新项目，或者只显示最终输出。无论哪种方式，用户都可能会问后续问题，在这种情况下，你可以再次调用运行方法。 +在智能体运行结束时，你可以选择展示给用户的内容。例如，你可以展示所有由智能体生成的新条目，或仅展示最终输出。无论哪种方式，用户可能会提出后续问题，此时你可以再次调用运行方法。 -### 手动对话管理 +### 手动会话管理 -你可以使用 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 方法手动管理对话历史记录，以获取下一轮次的输入： +你可以使用 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 方法手动管理会话历史，以获取下一轮的输入： ```python async def main(): agent = Agent(name="Assistant", instructions="Reply very concisely.") - thread_id = "thread_123" # 示例线程ID + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): - # 第一轮次 + # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?") print(result.final_output) # San Francisco - # 第二轮次 + # Second turn new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}] result = await Runner.run(agent, new_input) print(result.final_output) # California ``` -### 使用Sessions自动对话管理 +### 使用 Sessions 的自动会话管理 -对于更简单的方法，你可以使用[Sessions](sessions.md)来自动处理对话历史记录，而无需手动调用`.to_input_list()`： +更简单的方式是使用 [Sessions](sessions.md) 自动处理会话历史，而无需手动调用 `.to_input_list()`： ```python from agents import Agent, Runner, SQLiteSession @@ -101,40 +101,39 @@ from agents import Agent, Runner, SQLiteSession async def main(): agent = Agent(name="Assistant", instructions="Reply very concisely.") - # 创建会话实例 + # Create session instance session = SQLiteSession("conversation_123") - thread_id = "thread_123" # 示例线程ID + thread_id = "thread_123" # Example thread ID with trace(workflow_name="Conversation", group_id=thread_id): - # 第一轮次 + # First turn result = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session) print(result.final_output) # San Francisco - # 第二轮次 - 智能体自动记住之前的上下文 + # Second turn - agent automatically remembers previous context result = await Runner.run(agent, "What state is it in?", session=session) print(result.final_output) # California ``` -Sessions自动： +Sessions 会自动： -- 在每次运行前检索对话历史记录 -- 在每次运行后存储新消息 -- 为不同的会话ID维护单独的对话 +- 在每次运行前检索会话历史 +- 在每次运行后存储新消息 +- 为不同的 session ID 维护独立的会话 -有关详细信息，请参见[Sessions文档](sessions.md)。 +更多细节参见[Sessions 文档](sessions.md)。 +### 服务端管理的会话 -### 服务器管理的对话 +你也可以让 OpenAI 的会话状态功能在服务端管理会话状态，而不是在本地用 `to_input_list()` 或 `Sessions` 处理。这样可以在不手动重发所有历史消息的情况下保留会话历史。更多详情见 [OpenAI Conversation state 指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 -你还可以让OpenAI对话状态功能在服务器端管理对话状态，而不是使用`to_input_list()`或`Sessions`在本地处理它。这允许你保留对话历史记录，而无需手动重新发送所有过去的消息。有关详细信息，请参见[OpenAI对话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 +OpenAI 提供两种跨轮次跟踪状态的方式： -OpenAI提供了两种跨轮次跟踪状态的方法： +#### 1. 使用 `conversation_id` -#### 1. 使用`conversation_id` - -你首先使用OpenAI对话API创建一个对话，然后为每个后续调用重用其ID： +你首先使用 OpenAI Conversations API 创建一个会话，然后在后续每次调用中复用其 ID： ```python from agents import Agent, Runner @@ -143,18 +142,18 @@ from openai import AsyncOpenAI client = AsyncOpenAI() async def main(): - # 创建一个服务器管理的对话 + # Create a server-managed conversation conversation = await client.conversations.create() - conv_id = conversation.id + conv_id = conversation.id agent = Agent(name="Assistant", instructions="Reply very concisely.") - # 第一轮次 + # First turn result1 = await Runner.run(agent, "What city is the Golden Gate Bridge in?", conversation_id=conv_id) print(result1.final_output) # San Francisco - # 第二轮次重用相同的conversation_id + # Second turn reuses the same conversation_id result2 = await Runner.run( agent, "What state is it in?", @@ -164,9 +163,9 @@ async def main(): # California ``` -#### 2. 使用`previous_response_id` +#### 2. 使用 `previous_response_id` -另一个选项是**响应链接**，其中每个轮次显式链接到前一轮次的响应ID。 +另一种选择是**响应链（response chaining）**，每一轮都显式链接到上一轮的响应 ID。 ```python from agents import Agent, Runner @@ -174,12 +173,12 @@ from agents import Agent, Runner async def main(): agent = Agent(name="Assistant", instructions="Reply very concisely.") - # 第一轮次 + # First turn result1 = await Runner.run(agent, "What city is the Golden Gate Bridge in?") print(result1.final_output) # San Francisco - # 第二轮次，链接到之前的响应 + # Second turn, chained to the previous response result2 = await Runner.run( agent, "What state is it in?", @@ -189,19 +188,18 @@ async def main(): # California ``` +## 长时运行的智能体与人类在回路 -## 长时间运行的智能体和人机交互 - -你可以使用Agents SDK [Temporal](https://temporal.io/) 集成来运行持久的、长时间运行的工作流，包括人机交互任务。查看[此视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)中Temporal和Agents SDK协同工作完成长时间运行任务的演示，以及[查看此处的文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 +你可以使用 Agents SDK 的 [Temporal](https://temporal.io/) 集成来运行持久的、长时运行的工作流，包括人在回路的任务。在[这个视频](https://www.youtube.com/watch?v=fFBZqzT4DD8)中查看 Temporal 与 Agents SDK 协同完成长时任务的演示，并[在此查看文档](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)。 ## 异常 -SDK在某些情况下会引发异常。完整列表在 [`agents.exceptions`][] 中。概述如下： +SDK 在某些情况下会抛出异常。完整列表参见 [`agents.exceptions`][]。概览如下： -- [`AgentsException`][agents.exceptions.AgentsException]: 这是SDK内引发的所有异常的基类。它充当所有其他特定异常的通用类型。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 当智能体的运行超过传递给`Runner.run`、`Runner.run_sync`或`Runner.run_streamed`方法的`max_turns`限制时，会引发此异常。它表明智能体无法在指定的交互轮次内完成其任务。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 当底层模型（LLM）产生意外或无效的输出时，会发生此异常。这可能包括： - - 格式错误的JSON：当模型为工具调用或其直接输出提供格式错误的JSON结构时，特别是如果定义了特定的`output_type`。 - - 意外的工具相关失败：当模型未能以预期方式使用工具时 -- [`UserError`][agents.exceptions.UserError]: 当你（使用SDK编写代码的人）在使用SDK时出错，会引发此异常。这通常是由于代码实现不正确、配置无效或误用SDK的API导致的。 -- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 当满足输入护栏或输出护栏的条件时，分别会引发此异常。输入护栏在处理前检查传入消息，而输出护栏在传递前检查智能体的最终响应。 \ No newline at end of file +- [`AgentsException`][agents.exceptions.AgentsException]：SDK 内抛出的所有异常的基类。它作为通用类型，其他所有特定异常都从其派生。 +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 的 `max_turns` 限制时抛出。表示智能体无法在指定的交互轮次数内完成任务。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）产生意外或无效输出时发生。这可能包括： + - JSON 格式错误：当模型为工具调用或直接输出提供了格式错误的 JSON，尤其是在定义了特定 `output_type` 的情况下。 + - 与工具相关的意外失败：当模型未按预期方式使用工具 +- [`UserError`][agents.exceptions.UserError]：当你（使用 SDK 编写代码的人）在使用 SDK 时出错会抛出。通常由错误的代码实现、无效配置或误用 SDK 的 API 导致。 +- [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]：当输入或输出安全防护措施的条件分别被满足时抛出。输入安全防护在处理前检查传入消息，而输出安全防护在交付前检查智能体的最终响应。 \ No newline at end of file diff --git a/docs/zh/sessions.md b/docs/zh/sessions.md index d60964748..69822cd63 100644 --- a/docs/zh/sessions.md +++ b/docs/zh/sessions.md @@ -4,25 +4,25 @@ search: --- # 会话 -Agents SDK 提供内置的会话记忆功能，可自动在多次智能体运行之间维护对话历史，无需在轮次之间手动处理 `.to_input_list()`。 +Agents SDK 提供内置的会话记忆，用于在多个智能体运行之间自动维护对话历史，无需在回合之间手动处理 `.to_input_list()`。 -会话存储特定会话的对话历史，使智能体能够在无需显式手动内存管理的情况下保持上下文。这对于构建聊天应用程序或智能体需要记住先前交互的多轮对话特别有用。 +会话为特定的会话存储对话历史，使智能体无需显式的手动内存管理即可保持上下文。这对于构建聊天应用或多轮对话尤为有用，让智能体能够记住先前的交互。 ## 快速开始 ```python from agents import Agent, Runner, SQLiteSession -# 创建智能体 +# Create agent agent = Agent( name="Assistant", instructions="Reply very concisely.", ) -# 使用会话ID创建会话实例 +# Create a session instance with a session ID session = SQLiteSession("conversation_123") -# 第一轮 +# First turn result = await Runner.run( agent, "What city is the Golden Gate Bridge in?", @@ -30,7 +30,7 @@ result = await Runner.run( ) print(result.final_output) # "San Francisco" -# 第二轮 - 智能体自动记住之前的上下文 +# Second turn - agent automatically remembers previous context result = await Runner.run( agent, "What state is it in?", @@ -38,7 +38,7 @@ result = await Runner.run( ) print(result.final_output) # "California" -# 同步运行器也同样适用 +# Also works with synchronous runner result = Runner.run_sync( agent, "What's the population?", @@ -49,46 +49,46 @@ print(result.final_output) # "Approximately 39 million" ## 工作原理 -启用会话记忆时： +当启用会话记忆时： -1. **每次运行前**：运行器自动检索会话的对话历史，并将其前置到输入项中。 -2. **每次运行后**：运行期间生成的所有新项（用户输入、助手响应、工具调用等）都会自动存储在会话中。 -3. **上下文保持**：同一会话的每次后续运行都包含完整的对话历史，使智能体能够保持上下文。 +1. **每次运行之前**：运行器会自动检索该会话的对话历史，并将其预置到输入项之前。 +2. **每次运行之后**：运行期间生成的所有新项（用户输入、助手回复、工具调用等）都会自动存储到会话中。 +3. **上下文保留**：使用同一会话的每次后续运行都会包含完整的对话历史，使智能体能够保持上下文。 -这消除了手动调用 `.to_input_list()` 和管理运行之间对话状态的需要。 +这样就无需手动调用 `.to_input_list()` 并在运行之间管理对话状态。 ## 内存操作 ### 基本操作 -会话支持用于管理对话历史的多种操作： +会话支持多种用于管理对话历史的操作： ```python from agents import SQLiteSession session = SQLiteSession("user_123", "conversations.db") -# 获取会话中的所有项 +# Get all items in a session items = await session.get_items() -# 向会话添加新项 +# Add new items to a session new_items = [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi there!"} ] await session.add_items(new_items) -# 移除并返回最近的一项 +# Remove and return the most recent item last_item = await session.pop_item() print(last_item) # {"role": "assistant", "content": "Hi there!"} -# 清除会话中的所有项 +# Clear all items from a session await session.clear_session() ``` ### 使用 pop_item 进行更正 -`pop_item` 方法在你想要撤消或修改对话中的最后一项时特别有用： +当你希望撤销或修改对话中的最后一项时，`pop_item` 方法特别有用： ```python from agents import Agent, Runner, SQLiteSession @@ -96,7 +96,7 @@ from agents import Agent, Runner, SQLiteSession agent = Agent(name="Assistant") session = SQLiteSession("correction_example") -# 初始对话 +# Initial conversation result = await Runner.run( agent, "What's 2 + 2?", @@ -104,11 +104,11 @@ result = await Runner.run( ) print(f"Agent: {result.final_output}") -# 用户想要更正他们的问题 -assistant_item = await session.pop_item() # 移除智能体的响应 -user_item = await session.pop_item() # 移除用户的问题 +# User wants to correct their question +assistant_item = await session.pop_item() # Remove agent's response +user_item = await session.pop_item() # Remove user's question -# 询问更正后的问题 +# Ask a corrected question result = await Runner.run( agent, "What's 2 + 3?", @@ -122,21 +122,21 @@ print(f"Agent: {result.final_output}") ### 无内存（默认） ```python -# 默认行为 - 无会话内存 +# Default behavior - no session memory result = await Runner.run(agent, "Hello") ``` -### OpenAI 对话 API 内存 +### OpenAI Conversations API 内存 -使用 [OpenAI 对话 API](https://platform.openai.com/docs/api-reference/conversations/create) 来持久化 -[对话状态](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api)，无需管理自己的数据库。当你已经依赖 OpenAI 托管的基础设施来存储对话历史时，这很有帮助。 +使用 [OpenAI Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) 来持久化 +[会话状态](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#using-the-conversations-api)，而无需自行管理数据库。当你已经依赖由 OpenAI 托管的基础设施来存储对话历史时，这会很有帮助。 ```python from agents import OpenAIConversationsSession session = OpenAIConversationsSession() -# 可选地通过传递对话 ID 来恢复之前的对话 +# Optionally resume a previous conversation by passing a conversation ID # session = OpenAIConversationsSession(conversation_id="conv_123") result = await Runner.run( @@ -151,13 +151,13 @@ result = await Runner.run( ```python from agents import SQLiteSession -# 内存数据库（进程结束时丢失） +# In-memory database (lost when process ends) session = SQLiteSession("user_123") -# 基于文件的持久数据库 +# Persistent file-based database session = SQLiteSession("user_123", "conversations.db") -# 使用会话 +# Use the session result = await Runner.run( agent, "Hello", @@ -165,14 +165,14 @@ result = await Runner.run( ) ``` -### 多个会话 +### 多会话 ```python from agents import Agent, Runner, SQLiteSession agent = Agent(name="Assistant") -# 不同的会话维护单独的对话历史 +# Different sessions maintain separate conversation histories session_1 = SQLiteSession("user_123", "conversations.db") session_2 = SQLiteSession("user_456", "conversations.db") @@ -188,13 +188,13 @@ result2 = await Runner.run( ) ``` -### SQLAlchemy 驱动的会话 +### 由 SQLAlchemy 支持的会话 -对于更高级的用例，你可以使用 SQLAlchemy 驱动的会话后端。这允许你使用 SQLAlchemy 支持的任何数据库（PostgreSQL、MySQL、SQLite 等）进行会话存储。 +对于更高级的用例，你可以使用由 SQLAlchemy 支持的会话后端。这样你可以使用任何 SQLAlchemy 支持的数据库（PostgreSQL、MySQL、SQLite 等）进行会话存储。 -**示例 1：使用 `from_url` 和内存 SQLite** +**示例 1：使用 `from_url` 配合内存中的 SQLite** -这是最简单的入门方式，非常适合开发和测试。 +这是最简单的入门方式，适合开发与测试。 ```python import asyncio @@ -206,7 +206,7 @@ async def main(): session = SQLAlchemySession.from_url( "user-123", url="sqlite+aiosqlite:///:memory:", - create_tables=True, # 为演示自动创建表 + create_tables=True, # Auto-create tables for the demo ) result = await Runner.run(agent, "Hello", session=session) @@ -217,7 +217,7 @@ if __name__ == "__main__": **示例 2：使用现有的 SQLAlchemy 引擎** -在生产应用中，你可能已经有一个 SQLAlchemy `AsyncEngine` 实例。你可以直接将其传递给会话。 +在生产应用中，你很可能已经有一个 SQLAlchemy 的 `AsyncEngine` 实例。你可以将其直接传递给会话。 ```python import asyncio @@ -226,14 +226,14 @@ from agents.extensions.memory.sqlalchemy_session import SQLAlchemySession from sqlalchemy.ext.asyncio import create_async_engine async def main(): - # 在你的应用中，你会使用现有的引擎 + # In your application, you would use your existing engine engine = create_async_engine("sqlite+aiosqlite:///conversations.db") agent = Agent("Assistant") session = SQLAlchemySession( "user-456", engine=engine, - create_tables=True, # 为演示自动创建表 + create_tables=True, # Auto-create tables for the demo ) result = await Runner.run(agent, "Hello", session=session) @@ -245,10 +245,61 @@ if __name__ == "__main__": asyncio.run(main()) ``` +### 加密会话 + +对于需要对静态对话数据进行加密的应用，你可以使用 `EncryptedSession` 对任何会话后端进行透明加密并启用基于 TTL 的自动过期。需要安装 `encrypt` 可选依赖：`pip install openai-agents[encrypt]`。 + +`EncryptedSession` 使用 Fernet 加密并基于每个会话进行密钥派生（HKDF），支持旧消息的自动过期。当项目超过 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 @@ -256,33 +307,33 @@ from agents.items import TResponseInputItem from typing import List class MyCustomSession(SessionABC): - """遵循会话协议的自定义会话实现。""" + """Custom session implementation following the Session protocol.""" def __init__(self, session_id: str): self.session_id = session_id - # 你的初始化代码在这里 + # Your initialization here async def get_items(self, limit: int | None = None) -> List[TResponseInputItem]: - """检索此会话的对话历史。""" - # 你的实现代码在这里 + """Retrieve conversation history for this session.""" + # Your implementation here pass async def add_items(self, items: List[TResponseInputItem]) -> None: - """为此会话存储新项。""" - # 你的实现代码在这里 + """Store new items for this session.""" + # Your implementation here pass async def pop_item(self) -> TResponseInputItem | None: - """从此会话中移除并返回最近的一项。""" - # 你的实现代码在这里 + """Remove and return the most recent item from this session.""" + # Your implementation here pass async def clear_session(self) -> None: - """清除此会话的所有项。""" - # 你的实现代码在这里 + """Clear all items for this session.""" + # Your implementation here pass -# 使用你的自定义会话 +# Use your custom session agent = Agent(name="Assistant") result = await Runner.run( agent, @@ -293,34 +344,35 @@ result = await Runner.run( ## 会话管理 -### 会话ID命名 +### 会话 ID 命名 -使用有意义的会话ID来帮助你组织对话： +使用有意义的会话 ID 来帮助你组织对话： - 基于用户：`"user_12345"` - 基于线程：`"thread_abc123"` - 基于上下文：`"support_ticket_456"` -### 内存持久性 +### 内存持久化 -- 使用内存 SQLite (`SQLiteSession("session_id")`) 进行临时对话 -- 使用基于文件的 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 进行持久对话 -- 使用 SQLAlchemy 驱动的会话 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 用于具有 SQLAlchemy 支持的现有数据库的生产系统 -- 使用 OpenAI 托管存储 (`OpenAIConversationsSession()`) 当你希望将历史记录存储在 OpenAI 对话 API 中时 -- 考虑为其他生产系统（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()`) +- 使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任意会话提供透明加密和基于 TTL 的过期 +- 针对其他生产系统（Redis、Django 等）的高级用例，考虑实现自定义会话后端 ### 会话管理 ```python -# 当对话应该重新开始时清除会话 +# Clear a session when conversation should start fresh await session.clear_session() -# 不同的智能体可以共享相同的会话 +# Different agents can share the same session support_agent = Agent(name="Support") billing_agent = Agent(name="Billing") session = SQLiteSession("user_123") -# 两个智能体都将看到相同的对话历史 +# Both agents will see the same conversation history result1 = await Runner.run( support_agent, "Help me with my account", @@ -335,7 +387,7 @@ result2 = await Runner.run( ## 完整示例 -以下是展示会话内存实际应用的完整示例： +下面是一个展示会话记忆实际效果的完整示例： ```python import asyncio @@ -343,20 +395,20 @@ from agents import Agent, Runner, SQLiteSession async def main(): - # 创建智能体 + # Create an agent agent = Agent( name="Assistant", instructions="Reply very concisely.", ) - # 创建一个将在运行之间持久的会话实例 + # Create a session instance that will persist across runs session = SQLiteSession("conversation_123", "conversation_history.db") - print("=== 会话示例 ===") - print("智能体将自动记住之前的消息。\n") + print("=== Sessions Example ===") + print("The agent will remember previous messages automatically.\n") - # 第一轮 - print("第一轮:") + # First turn + print("First turn:") print("User: What city is the Golden Gate Bridge in?") result = await Runner.run( agent, @@ -366,8 +418,8 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # 第二轮 - 智能体将记住之前的对话 - print("第二轮:") + # Second turn - the agent will remember the previous conversation + print("Second turn:") print("User: What state is it in?") result = await Runner.run( agent, @@ -377,8 +429,8 @@ async def main(): print(f"Assistant: {result.final_output}") print() - # 第三轮 - 继续对话 - print("第三轮:") + # Third turn - continuing the conversation + print("Third turn:") print("User: What's the population of that state?") result = await Runner.run( agent, @@ -388,9 +440,9 @@ async def main(): print(f"Assistant: {result.final_output}") print() - print("=== 对话完成 ===") - print("注意智能体如何从前几轮记住上下文！") - print("会话自动处理对话历史。") + print("=== Conversation Complete ===") + print("Notice how the agent remembered the context from previous turns!") + print("Sessions automatically handles conversation history.") if __name__ == "__main__": @@ -399,9 +451,10 @@ if __name__ == "__main__": ## API 参考 -有关详细的 API 文档，请参见： +详细的 API 文档参见： - [`Session`][agents.memory.Session] - 协议接口 - [`SQLiteSession`][agents.memory.SQLiteSession] - SQLite 实现 -- [`OpenAIConversationsSession`](ref/memory/openai_conversations_session.md) - OpenAI 对话 API 实现 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 驱动的实现 \ No newline at end of file +- [`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/zh/streaming.md b/docs/zh/streaming.md index 13c2f0884..305ad8444 100644 --- a/docs/zh/streaming.md +++ b/docs/zh/streaming.md @@ -2,17 +2,17 @@ search: exclude: true --- -# 流式处理 +# 流式传输 -流式处理让你可以订阅智能体运行过程中的更新。这对于向最终用户显示进度更新和部分响应很有用。 +流式传输允许你在智能体运行过程中订阅更新。这对于向最终用户展示进度与部分响应非常有用。 -要进行流式处理，你可以调用 [`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响应API格式，这意味着每个事件都有一个类型（如`response.created`、`response.output_text.delta`等）和数据。当你想在生成响应消息时立即将它们流式传输给用户，这些事件很有用。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] 是直接由 LLM 传递的原始事件。它们采用 OpenAI Responses API 格式，这意味着每个事件都有一个类型（如 `response.created`、`response.output_text.delta` 等）以及数据。如果你希望在生成后立刻将响应消息流式传输给用户，这些事件会很有用。 -例如，这将逐token输出LLM生成的文本。 +例如，下面将逐 token 输出由 LLM 生成的文本。 ```python import asyncio @@ -35,11 +35,11 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 运行项目事件和智能体事件 +## 运行条目事件与智能体事件 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 是更高级别的事件。它们通知你某个项目已完全生成的时间。这使你可以在"消息已生成"、"工具已运行"等层面上推送进度更新，而不是每个token。同样，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 在当前智能体发生更改时（例如由于交接的结果）为你提供更新。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 属于更高层级的事件。它会在一个条目完全生成时通知你。这样你就可以在“消息已生成”“工具已运行”等层级推送进度更新，而不是逐个 token。类似地，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如由于一次任务转移）向你提供更新。 -例如，这将忽略原始事件并向用户流式传输更新。 +例如，下面会忽略原始事件，仅向用户流式传输更新。 ```python import asyncio @@ -62,28 +62,28 @@ async def main(): agent, input="Hello", ) - print("=== 运行开始 ===") + print("=== Run starting ===") async for event in result.stream_events(): - # 我们将忽略原始响应事件增量 + # We'll ignore the raw responses event deltas if event.type == "raw_response_event": continue - # 当智能体更新时，打印该信息 + # When the agent updates, print that elif event.type == "agent_updated_stream_event": - print(f"智能体已更新: {event.new_agent.name}") + print(f"Agent updated: {event.new_agent.name}") continue - # 当项目生成时，打印它们 + # When items are generated, print them elif event.type == "run_item_stream_event": if event.item.type == "tool_call_item": - print("-- 工具被调用") + print("-- Tool was called") elif event.item.type == "tool_call_output_item": - print(f"-- 工具输出: {event.item.output}") + print(f"-- Tool output: {event.item.output}") elif event.item.type == "message_output_item": - print(f"-- 消息输出:\n {ItemHelpers.text_message_output(event.item)}") + print(f"-- Message output:\n {ItemHelpers.text_message_output(event.item)}") else: - pass # 忽略其他事件类型 + pass # Ignore other event types - print("=== 运行完成 ===") + print("=== Run complete ===") if __name__ == "__main__": diff --git a/docs/zh/tools.md b/docs/zh/tools.md index b72b53a71..88b21e569 100644 --- a/docs/zh/tools.md +++ b/docs/zh/tools.md @@ -4,23 +4,23 @@ search: --- # 工具 -工具让智能体能够执行操作：比如获取数据、运行代码、调用外部API，甚至使用计算机。Agent SDK中有三类工具： +工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至进行计算机操作。在 Agents SDK 中有三类工具： -- 托管工具：这些工具在AI模型旁边的LLM服务器上运行。OpenAI提供检索、网络搜索和计算机使用作为托管工具。 -- 函数调用：这些允许你将任何Python函数作为工具使用。 -- 智能体作为工具：这允许你将智能体作为工具使用，让智能体可以调用其他智能体而不需要交接控制权。 +- 托管工具：这些工具在 LLM 服务上与 AI 模型并行运行。OpenAI 提供检索、网络检索和计算机操作等托管工具。 +- 工具调用：允许你将任意 Python 函数用作工具。 +- 智能体作为工具：允许你将一个智能体作为工具使用，使智能体之间可以相互调用而无需进行任务转移。 ## 托管工具 -使用 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 时，OpenAI提供了一些内置工具： +使用[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]时，OpenAI 提供一些内置工具： -- [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体搜索网络。 -- [`FileSearchTool`][agents.tool.FileSearchTool] 允许从你的OpenAI向量存储中检索信息。 -- [`ComputerTool`][agents.tool.ComputerTool] 允许自动化计算机使用任务。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让LLM在沙盒环境中执行代码。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程MCP服务器的工具暴露给模型。 +- [`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] 在你的机器上运行shell命令。 +- [`LocalShellTool`][agents.tool.LocalShellTool] 在你的机器上运行 shell 命令。 ```python from agents import Agent, FileSearchTool, Runner, WebSearchTool @@ -41,16 +41,16 @@ async def main(): print(result.final_output) ``` -## 函数工具 +## 工具调用 -你可以使用任何Python函数作为工具。Agents SDK会自动设置工具： +你可以将任意 Python 函数作为工具使用。Agents SDK 会自动设置该工具： -- 工具的名称将是Python函数的名称（或者你可以提供一个名称） -- 工具描述将从函数的文档字符串中获取（或者你可以提供一个描述） -- 函数输入的模式会自动从函数的参数创建 -- 每个输入的描述从函数的文档字符串中获取，除非被禁用 +- 工具名称将是 Python 函数名（或你可以自定义名称） +- 工具描述将取自函数的 docstring（或你可以提供描述） +- 函数输入的模式会根据函数参数自动创建 +- 每个输入的描述将取自函数的 docstring，除非禁用 -我们使用Python的 `inspect` 模块来提取函数签名，同时使用 [`griffe`](https://mkdocstrings.github.io/griffe/) 来解析文档字符串，使用 `pydantic` 来创建模式。 +我们使用 Python 的 `inspect` 模块提取函数签名，结合使用 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，并用 `pydantic` 创建模式。 ```python import json @@ -102,12 +102,12 @@ for tool in agent.tools: ``` -1. 你可以使用任何Python类型作为函数的参数，函数可以是同步或异步的。 -2. 如果存在文档字符串，它们会被用来捕获描述和参数描述 -3. 函数可以选择性地接收 `context`（必须是第一个参数）。你也可以设置覆盖项，比如工具的名称、描述、使用哪种文档字符串风格等。 -4. 你可以将装饰后的函数传递给工具列表。 +1. 你可以使用任意 Python 类型作为函数参数，函数可以是同步或异步。 +2. 如果存在 docstring，将用于提取描述和参数说明。 +3. 函数可选地接收 `context`（必须是第一个参数）。你也可以设置覆盖项，比如工具名称、描述、docstring 风格等。 +4. 你可以将装饰过的函数传入工具列表中。 -??? note "展开查看输出" +??? note "展开以查看输出" ``` 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字符串的参数，并且必须返回作为字符串的工具输出。 +- `name` +- `description` +- `params_json_schema`，即参数的 JSON 模式 +- `on_invoke_tool`，一个异步函数，接收一个 [`ToolContext`][agents.tool_context.ToolContext] 和作为 JSON 字符串的参数，并且必须返回字符串形式的工具输出。 ```python from typing import Any @@ -217,18 +217,18 @@ tool = FunctionTool( ) ``` -### 自动参数和文档字符串解析 +### 自动解析参数与 docstring -如前所述，我们自动解析函数签名来提取工具的模式，并且解析文档字符串来提取工具的描述和各个参数的描述。一些注意事项： +如前所述，我们会自动解析函数签名以提取工具的模式，并解析 docstring 以提取工具及各个参数的描述。注意事项： -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` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这只是尽力而为；你可以在调用 `function_tool` 时显式指定。你也可以通过将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。 -模式提取的代码位于 [`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 @@ -290,21 +290,21 @@ async def run_my_agent() -> str: ### 自定义输出提取 -在某些情况下，你可能希望在将工具智能体的输出返回给中央智能体之前修改它。这可能有用，如果你想： +在某些情况下，你可能希望在将工具化智能体的输出返回给中心智能体之前对其进行修改。这在以下场景中很有用： -- 从子智能体的聊天记录中提取特定信息（例如，JSON有效载荷）。 -- 转换或重新格式化智能体的最终答案（例如，将Markdown转换为纯文本或CSV）。 -- 验证输出或在智能体的响应缺失或格式错误时提供回退值。 +- 从子智能体的对话历史中提取特定信息（例如，一个 JSON 负载）。 +- 转换或重新格式化智能体的最终答案（例如将 Markdown 转为纯文本或 CSV）。 +- 验证输出，或在智能体响应缺失或格式错误时提供回退值。 -你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来做到这一点： +你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现： ```python async def extract_json_payload(run_result: RunResult) -> str: - # 以相反的顺序扫描智能体的输出，直到我们找到来自工具调用的类似JSON的消息。 + # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call. for item in reversed(run_result.new_items): if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"): return item.output.strip() - # 如果什么都没找到，回退到空JSON对象 + # Fallback to an empty JSON object if nothing was found return "{}" @@ -315,9 +315,9 @@ json_tool = data_agent.as_tool( ) ``` -### 条件工具启用 +### 条件启用工具 -你可以使用 `is_enabled` 参数在运行时条件性地启用或禁用智能体工具。这允许你根据上下文、用户偏好或运行时条件动态过滤哪些工具可供LLM使用。 +你可以在运行时使用 `is_enabled` 参数有条件地启用或禁用智能体工具。这允许你根据上下文、用户偏好或运行时条件动态筛选 LLM 可用的工具。 ```python import asyncio @@ -376,22 +376,22 @@ asyncio.run(main()) - **布尔值**：`True`（始终启用）或 `False`（始终禁用） - **可调用函数**：接收 `(context, agent)` 并返回布尔值的函数 -- **异步函数**：用于复杂条件逻辑的异步函数 +- **异步函数**：用于更复杂的条件逻辑 -禁用的工具在运行时对LLM完全隐藏，这使得它适用于： +被禁用的工具在运行时对 LLM 完全不可见，适用于： - 基于用户权限的功能开关 -- 环境特定的工具可用性（开发环境 vs 生产环境） -- A/B测试不同的工具配置 -- 基于运行时状态的动态工具过滤 +- 特定环境的工具可用性（开发 vs 生产） +- A/B 测试不同的工具配置 +- 基于运行时状态的动态工具筛选 -## 函数工具中的错误处理 +## 在函数工具中处理错误 -当你通过 `@function_tool` 创建函数工具时，你可以传递一个 `failure_error_function`。这是一个函数，在工具调用崩溃的情况下向LLM提供错误响应。 +当你通过 `@function_tool` 创建函数工具时，可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。 -- 默认情况下（即如果你没有传递任何东西），它会运行一个 `default_tool_error_function`，告诉LLM发生了错误。 -- 如果你传递自己的错误函数，它会运行那个函数，并将响应发送给LLM。 -- 如果你显式地传递 `None`，那么任何工具调用错误都会被重新抛出，供你处理。这可能是 `ModelBehaviorError`（如果模型产生了无效的JSON），或者 `UserError`（如果你的代码崩溃了）等。 +- 默认情况下（即未传入任何内容），会运行 `default_tool_error_function`，告知 LLM 发生了错误。 +- 如果传入了你自己的错误函数，将改为运行该函数，并把响应发送给 LLM。 +- 如果显式传入 `None`，则任何工具调用错误都会被重新抛出以供你处理。若模型生成了无效 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/zh/tracing.md b/docs/zh/tracing.md index b0ba3bea5..8aba6643d 100644 --- a/docs/zh/tracing.md +++ b/docs/zh/tracing.md @@ -2,54 +2,54 @@ search: exclude: true --- -# 追踪功能 +# 追踪 -Agents SDK包含内置的追踪功能，可全面记录智能体运行期间的事件：LLM生成、工具调用、交接、护栏，甚至发生的自定义事件。使用[追踪仪表板](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并在零数据保留(ZDR)策略下运营的组织，追踪功能不可用。*** +***对于使用 OpenAI 的 API 并遵循 Zero Data Retention (ZDR) 策略的组织，追踪不可用。*** -## 追踪和跨度 +## 追踪与跨度 -- **追踪** 代表"工作流"的单个端到端操作。它们由跨度组成。追踪具有以下属性: - - `workflow_name`: 这是逻辑工作流或应用。例如"代码生成"或"客户服务"。 - - `trace_id`: 追踪的唯一ID。如果你没有传递一个，它会自动生成。格式必须是 `trace_<32_字母数字>`。 - - `group_id`: 可选的组ID，用于链接来自同一会话的多个追踪。例如，你可以使用聊天线程ID。 - - `disabled`: 如果为True，该追踪将不会被记录。 - - `metadata`: 追踪的可选元数据。 -- **跨度** 代表具有开始和结束时间的操作。跨度具有: +- **追踪（Traces）** 表示一次“工作流”的端到端操作，由多个跨度（Spans）组成。追踪具有以下属性： + - `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会追踪以下内容： +默认情况下，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)，将追踪推送到其他目标位置（作为替代或附加目的地）。 -## 高层级追踪 +## 更高层级的追踪 -有时你可能想将多次 `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`）。这会在适当的时候自动开始和结束。 +1. 推荐：将追踪作为上下文管理器使用，即 `with trace(...) as my_trace`。这会在合适的时机自动开始和结束追踪。 2. 也可以手动调用 [`trace.start()`][agents.tracing.Trace.start] 和 [`trace.finish()`][agents.tracing.Trace.finish]。 -当前追踪由Python的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。这意味着它在并发处理中自动工作。如果手动开始/结束追踪，需要向 `start()`/`finish()` 传递 `mark_as_current` 和 `reset_current` 来更新当前追踪。 +当前追踪通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。这意味着它能自动与并发配合。如果你手动开始/结束追踪，需要在 `start()`/`finish()` 中传入 `mark_as_current` 和 `reset_current` 以更新当前追踪。 ## 创建跨度 -你可以使用各种 [`*_span()`][agents.tracing.create] 方法创建跨度。通常不需要手动创建跨度。要追踪自定义跨度信息，可以使用 [`custom_span()`][agents.tracing.custom_span] 函数。 +你可以使用不同的 [`*_span()`][agents.tracing.create] 方法创建跨度。通常，你无需手动创建跨度。提供了 [`custom_span()`][agents.tracing.custom_span] 函数用于追踪自定义跨度信息。 -跨度会自动成为当前追踪的一部分，并嵌套在由Python的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪的最近的当前跨度之下。 +跨度会自动归属到当前追踪下，并嵌套在最近的当前跨度下，该状态通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。 ## 敏感数据 -某些跨度可能会捕获敏感数据。 +某些跨度可能会捕获潜在的敏感数据。 -`generation_span()` 保存LLM生成的输入/输出，`function_span()` 保存函数调用的输入/输出。这些可能包含敏感数据，因此可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用其捕获。 +`generation_span()` 会存储 LLM 生成的输入/输出，而 `function_span()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用对这些数据的捕获。 -类似地，语音跨度默认包含输入/输出音频的base64编码PCM数据。可以设置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 来禁用此音频数据的捕获。 +类似地，音频跨度默认会包含输入和输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 禁用对这些音频数据的捕获。 -## 自定义追踪处理器 +## 自定义追踪进程 -追踪的高层级架构如下： +追踪的高层架构如下： -- 初始化时，创建一个全局的 [`TraceProvider`][agents.tracing.setup.TraceProvider]，负责创建追踪。 -- 为 `TraceProvider` 设置一个 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，它将跨度/追踪批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]。`BackendSpanExporter` 将其批量导出到OpenAI后端。 +- 在初始化时，我们会创建一个全局的 [`TraceProvider`][agents.tracing.setup.TraceProvider]，负责创建追踪。 +- 我们为 `TraceProvider` 配置了一个 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，该进程会将追踪/跨度批量发送至 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者会将跨度与追踪批量导出到 OpenAI 后端。 -要自定义默认设置，发送到其他后端/复制到额外后端/更改导出器行为，有两种方法： +若要自定义此默认设置，以将追踪发送到替代或附加的后端，或修改导出器行为，有两种选择： -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 可以添加**额外的**追踪处理器，一旦追踪和跨度准备就绪就会接收它们。这允许你在发送到OpenAI后端的同时执行自己的处理。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 可以用自己的追踪处理器**替换**默认处理器。要将追踪发送到OpenAI后端，需要包含执行该操作的 `TracingProcessor`。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个额外的追踪进程，它会在追踪和跨度就绪时接收它们。这使你可以在将追踪发送到 OpenAI 后端之外，执行自定义处理。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自定义的追踪进程替换默认进程。这意味着除非你包含一个会将数据发送到 OpenAI 后端的 `TracingProcessor`，否则追踪将不会被发送到 OpenAI 后端。 -## 非OpenAI模型的追踪 +## 使用非 OpenAI 模型进行追踪 -使用OpenAI的API密钥配合非OpenAI模型时，可以在不禁用追踪的情况下启用OpenAI追踪仪表板中的免费追踪。 +你可以使用 OpenAI API key 搭配非 OpenAI 模型，在无需禁用追踪的情况下，在 OpenAI Traces 仪表板中启用免费的追踪。 ```python import os @@ -125,15 +125,15 @@ agent = Agent( ``` ## 注意事项 -- 免费追踪可以在OpenAI追踪仪表板中查看。 +- 在 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) @@ -148,4 +148,4 @@ agent = Agent( - [Galileo](https://v2docs.galileo.ai/integrations/openai-agent-integration#openai-agent-integration) - [Portkey AI](https://portkey.ai/docs/integrations/agents/openai-agents) - [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) -- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) +- [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) \ No newline at end of file diff --git a/docs/zh/usage.md b/docs/zh/usage.md index 67ee8b705..7af7fe355 100644 --- a/docs/zh/usage.md +++ b/docs/zh/usage.md @@ -2,23 +2,23 @@ search: exclude: true --- -# 使用统计 +# 用量 -Agents SDK会自动跟踪每次运行的token使用情况。你可以从运行上下文中访问它，用于监控成本、强制执行限制或记录分析。 +Agents SDK 会自动跟踪每次运行的 token 用量。你可以在运行上下文中访问它，用于监控成本、执行限制或记录分析数据。 -## 跟踪内容 +## 追踪内容 -- **requests**: 发出的LLM API调用数量 -- **input_tokens**: 发送的总输入token数 -- **output_tokens**: 接收的总输出token数 +- **requests**: 发起的 LLM API 调用次数 +- **input_tokens**: 发送的输入 token 总数 +- **output_tokens**: 接收的输出 token 总数 - **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) ``` -使用情况在运行期间的所有模型调用（包括工具调用和交接）中进行汇总。 +用量会跨本次运行中的所有模型调用聚合（包括工具调用和 handoffs）。 -### 启用LiteLLM模型的使用情况 +### 在 LiteLLM 模型中启用用量 -LiteLLM提供程序默认不报告使用指标。当你使用 [`LitellmModel`](models/litellm.md) 时，向你的智能体传递 `ModelSettings(include_usage=True)`，这样LiteLLM响应就会填充到 `result.context_wrapper.usage` 中。 +LiteLLM 提供商默认不报告用量指标。使用 [`LitellmModel`](models/litellm.md) 时，向你的智能体传入 `ModelSettings(include_usage=True)`，以便 LiteLLM 的响应填充 `result.context_wrapper.usage`。 ```python from agents import Agent, ModelSettings, Runner @@ -50,37 +50,37 @@ result = await Runner.run(agent, "What's the weather in Tokyo?") print(result.context_wrapper.usage.total_tokens) ``` -## 在会话中获取使用情况 +## 使用会话访问用量 -当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该特定运行的使用情况。会话为上下文维护对话历史，但每次运行的使用情况是独立的。 +当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行的用量。会话会为上下文维护对话历史，但每次运行的用量彼此独立。 ```python session = SQLiteSession("my_conversation") first = await Runner.run(agent, "Hi!", session=session) -print(first.context_wrapper.usage.total_tokens) # 第一次运行的使用情况 +print(first.context_wrapper.usage.total_tokens) # Usage for first run second = await Runner.run(agent, "Can you elaborate?", session=session) -print(second.context_wrapper.usage.total_tokens) # 第二次运行的使用情况 +print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -请注意，虽然会话在运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的使用情况指标只代表该特定执行。在会话中，先前的消息可能会作为输入重新提供给每次运行，这会影响后续轮次的输入token计数。 +请注意，虽然会话会在多次运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的用量指标仅代表该次执行。在会话中，之前的消息可能会在每次运行时再次作为输入提供，这会影响后续轮次的输入 token 计数。 -## 在钩子中使用使用情况 +## 在钩子中使用用量 -如果你正在使用 `RunHooks`，传递给每个钩子的 `context` 对象包含 `usage`。这让你在关键生命周期时刻记录使用情况。 +如果你使用 `RunHooks`，传递给每个钩子的 `context` 对象包含 `usage`。这使你能够在关键生命周期时刻记录用量。 ```python class MyHooks(RunHooks): async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None: u = context.usage - print(f"{agent.name} → {u.requests} 次请求, {u.total_tokens} 总token数") + print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") ``` ## 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/zh/visualization.md b/docs/zh/visualization.md index 9af8a1a76..335003ef1 100644 --- a/docs/zh/visualization.md +++ b/docs/zh/visualization.md @@ -4,24 +4,24 @@ search: --- # 智能体可视化 -智能体可视化允许你使用 **Graphviz** 生成智能体及其关系的结构化图形表示。这有助于理解应用程序中智能体、工具和交接如何相互作用。 +智能体可视化允许你使用 **Graphviz** 生成智能体及其关系的结构化图形表示。这有助于理解智能体、工具和任务转移在应用中的交互方式。 ## 安装 -安装可选的 `viz` 依赖组: +安装可选的 `viz` 依赖组： ```bash pip install "openai-agents[viz]" ``` -## 生成图表 +## 生成图形 -你可以使用 `draw_graph` 函数生成智能体可视化。此函数创建一个有向图，其中： +你可以使用 `draw_graph` 函数生成智能体可视化。该函数会创建一个有向图，其中： -- **智能体** 表示为黄色框。 -- **MCP 服务器** 表示为灰色框。 -- **工具** 表示为绿色椭圆。 -- **交接** 表示为智能体之间的有向边。 +- **智能体** 用黄色方框表示。 +- **MCP 服务** 用灰色方框表示。 +- **工具** 用绿色椭圆表示。 +- **任务转移** 用从一个智能体指向另一个智能体的有向边表示。 ### 使用示例 @@ -67,41 +67,41 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![智能体图表](../assets/images/graph.png) +![Agent Graph](../assets/images/graph.png) -这会生成一个可视化图表，表示 **分类智能体** 的结构及其与子智能体和工具的连接。 +这将生成一个图形，直观地表示 **分诊智能体** 的结构以及与子智能体和工具的连接。 ## 理解可视化 -生成的图表包括： +生成的图形包括： -- 一个 **开始节点** (`__start__`) 表示入口点。 -- 智能体表示为带有黄色填充的 **矩形**。 -- 工具表示为带有绿色填充的 **椭圆**。 -- MCP 服务器表示为带有灰色填充的 **矩形**。 -- 指示交互的有向边： - - **实线箭头** 用于智能体到智能体的交接。 - - **虚线箭头** 用于工具调用。 - - **点线箭头** 用于 MCP 服务器调用。 -- 一个 **结束节点** (`__end__`) 表示执行终止的位置。 +- 一个表示入口点的 **起始节点**（`__start__`）。 +- 用黄色填充的 **矩形** 表示智能体。 +- 用绿色填充的 **椭圆** 表示工具。 +- 用灰色填充的 **矩形** 表示 MCP 服务。 +- 表示交互的有向边： + - **实线箭头** 表示智能体之间的任务转移。 + - **点线箭头** 表示工具调用。 + - **虚线箭头** 表示 MCP 服务调用。 +- 一个表示执行终止位置的 **结束节点**（`__end__`）。 -**注意：** MCP 服务器在 `agents` 包的最新版本中渲染（已在 **v0.2.8** 中验证）。如果你的可视化中没有看到 MCP 框，请升级到最新版本。 +**注意：** 在 `agents` 包的较新版本（在 **v0.2.8** 中已验证）中会渲染 MCP 服务。如果在你的可视化中未看到 MCP 方框，请升级到最新版本。 -## 自定义图表 +## 自定义图形 -### 图表显示 -默认情况下，`draw_graph` 会内联显示图表。要在单独的窗口中显示图表，请编写以下内容: +### 显示图形 +默认情况下，`draw_graph` 会内联显示图形。若要在单独窗口中显示，请编写： ```python draw_graph(triage_agent).view() ``` -### 保存图表 -默认情况下，`draw_graph` 会内联显示图表。要将其保存为文件，请指定文件名: +### 保存图形 +默认情况下，`draw_graph` 会内联显示图形。若要将其保存为文件，请指定文件名： ```python draw_graph(triage_agent, filename="agent_graph") ``` -这将在工作目录中生成 `agent_graph.png`。 \ No newline at end of file +这将在工作目录下生成 `agent_graph.png`。 \ No newline at end of file diff --git a/docs/zh/voice/pipeline.md b/docs/zh/voice/pipeline.md index b0e5577da..95dd9adde 100644 --- a/docs/zh/voice/pipeline.md +++ b/docs/zh/voice/pipeline.md @@ -2,9 +2,9 @@ search: exclude: true --- -# 管道和工作流 +# 管道与工作流 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个可以轻松将智能体工作流转换为语音应用的类。您传入要运行的工作流，管道会负责转录输入音频、检测音频何时结束、在适当时间调用您的工作流，并将工作流输出转换回音频。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个类，可轻松将你的智能体工作流变成语音应用。你传入要运行的工作流，管道会负责转写输入音频、检测音频何时结束、在合适的时机调用你的工作流，并将工作流输出重新转换为音频。 ```mermaid graph LR @@ -32,31 +32,31 @@ graph LR ``` -## 配置管道 +## 管道配置 -创建管道时，您可以设置以下内容： +创建管道时，你可以设置以下内容： -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]，即每次转录新音频时运行的代码 +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]：即每次有新音频被转写时运行的代码。 2. 使用的 [`speech-to-text`][agents.voice.model.STTModel] 和 [`text-to-speech`][agents.voice.model.TTSModel] 模型 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]，可让您配置以下内容： - - 模型提供程序，可将模型名称映射到模型 - - 追踪，包括是否禁用追踪、是否上传音频文件、工作流名称、追踪ID等 - - TTS 和 STT 模型的设置，如提示、语言和使用的数据类型 +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]：用于配置如下内容： + - 模型提供者，可将模型名称映射到具体模型 + - 追踪，包括是否禁用追踪、是否上传音频文件、工作流名称、追踪 ID 等 + - TTS 与 STT 模型的设置，如 prompt、语言和所用数据类型 ## 运行管道 -您可以通过 [`run()`][agents.voice.pipeline.VoicePipeline.run] 方法运行管道，该方法允许您以两种形式传入音频输入： +你可以通过 [`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]：当可能需要检测用户何时说完时使用。它允许你在检测到时推送音频分片，语音管道会通过称为“语音活动检测 (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]，通知生命周期事件，如轮次开始或结束 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]，是错误事件 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]：包含一段音频分片。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]：通知你如轮次开始或结束等生命周期事件。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]：错误事件。 ```python @@ -76,4 +76,4 @@ async for event in result.stream(): ### 中断 -Agents SDK 目前不支持 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 的任何内置中断支持。相反，对于每个检测到的轮次，它将触发您工作流的单独运行。如果您想在应用程序内处理中断，可以监听 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 事件。`turn_started` 将表示新轮次已被转录并且处理正在开始。`turn_ended` 将在相应轮次的所有音频被调度后触发。您可以使用这些事件在模型开始轮次时静音说话者的麦克风，并在刷新轮次的所有相关音频后取消静音。 \ No newline at end of file +Agents SDK 目前不对 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 提供任何内建的中断支持。相反，对于每个检测到的轮次，它都会触发一次单独的工作流运行。如果你希望在应用内处理中断，可以监听 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 事件。`turn_started` 表示一个新轮次已被转写且处理开始；`turn_ended` 则会在相应轮次的全部音频分发完成后触发。你可以利用这些事件在模型开始一个轮次时将说话者的麦克风静音，并在为该轮次发送完所有相关音频后取消静音。 \ No newline at end of file diff --git a/docs/zh/voice/quickstart.md b/docs/zh/voice/quickstart.md index 7f5185097..d6349c6fb 100644 --- a/docs/zh/voice/quickstart.md +++ b/docs/zh/voice/quickstart.md @@ -4,9 +4,9 @@ search: --- # 快速开始 -## 前提条件 +## 先决条件 -请遵循 OpenAI 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]，它是一个三步流程： -1. 运行语音转文本模型将音频转换为文本。 -2. 运行您的代码（通常是智能体驱动的工作流）以产生结果。 -3. 运行文本转语音模型将结果文本转换回音频。 +1. 运行语音转文本模型，将音频转换为文本。 +2. 运行你的代码（通常是智能体工作流）以产出结果。 +3. 运行文本转语音模型，将结果文本转换回音频。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## 智能体 -首先，让我们设置一些智能体。如果您使用此 SDK 创建过智能体，这应该看起来很熟悉。我们将设置两个智能体、一个交接和一个工具。 +首先，让我们设置一些智能体。如果你使用此 SDK 构建过任何智能体，这应当很熟悉。我们将有几个智能体、一次任务转移，以及一个工具。 ```python import asyncio @@ -90,16 +90,16 @@ agent = Agent( ) ``` -## 语音管道 +## 语音流水线 -我们将使用 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] 作为工作流来设置一个简单的语音管道。 +我们将设置一个简单的语音流水线，使用 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] 作为工作流。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent)) ``` -## 运行管道 +## 流水线运行 ```python import numpy as np @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## 統合 +## 整合 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -如果您运行此示例，智能体将与您对话！请查看 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) 中的示例，了解您可以自己与智能体对话的演示。 \ No newline at end of file +如果你运行这个示例，智能体会对你说话！查看 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) 中的示例，观看一个你可以亲自与智能体对话的演示。 \ No newline at end of file diff --git a/docs/zh/voice/tracing.md b/docs/zh/voice/tracing.md index 4de718ec7..e099ca71c 100644 --- a/docs/zh/voice/tracing.md +++ b/docs/zh/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # 追踪 -与[智能体追踪](../tracing.md)类似，语音管道也会自动被追踪。 +与[智能体的追踪方式](../tracing.md)相同，语音流水线也会被自动追踪。 -您可以阅读上述追踪文档了解基本的追踪信息，但您还可以通过 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] 额外配置管道的追踪。 +你可以阅读上方的追踪文档了解基本信息，此外还可以通过[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]对流水线的追踪进行配置。 -主要的追踪相关字段包括： +与追踪相关的关键字段包括： -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 控制是否禁用追踪。默认情况下，追踪是启用的。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 控制追踪是否包含潜在敏感数据，如音频转录。这专门针对语音管道，而不适用于您工作流内部进行的任何处理。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 控制追踪是否包含音频数据。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 追踪工作流的名称。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 追踪的 `group_id`，让您可以链接多个追踪。 -- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 要包含在追踪中的额外元数据。 \ No newline at end of file +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：控制是否禁用追踪。默认启用追踪。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：控制追踪是否包含潜在敏感数据，比如音频转写。该设置仅适用于语音流水线，不影响你的工作流内部的内容。 +- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]：控制追踪是否包含音频数据。 +- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]：追踪工作流的名称。 +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]：追踪的`group_id`，用于关联多个追踪。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：随追踪一并包含的额外元数据。 \ No newline at end of file