From ff014e1b080aa9a5bf3f9b9bca883763d8c8f567 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Wed, 13 May 2026 16:29:20 +0900 Subject: [PATCH] docs: translate all pages using new settings --- docs/ja/agents.md | 124 +++---- docs/ja/config.md | 48 +-- docs/ja/context.md | 82 ++--- docs/ja/examples.md | 124 +++---- docs/ja/guardrails.md | 70 ++-- docs/ja/handoffs.md | 78 ++-- docs/ja/human_in_the_loop.md | 117 +++--- docs/ja/index.md | 94 ++--- docs/ja/mcp.md | 139 ++++--- docs/ja/models/index.md | 220 ++++++------ docs/ja/models/litellm.md | 2 +- docs/ja/multi_agent.md | 66 ++-- docs/ja/quickstart.md | 50 +-- docs/ja/realtime/guide.md | 128 +++---- docs/ja/realtime/quickstart.md | 54 +-- docs/ja/realtime/transport.md | 54 +-- docs/ja/release.md | 116 +++--- docs/ja/repl.md | 6 +- docs/ja/results.md | 134 +++---- docs/ja/running_agents.md | 220 ++++++------ docs/ja/sandbox/clients.md | 96 ++--- docs/ja/sandbox/guide.md | 352 +++++++++--------- docs/ja/sandbox/memory.md | 60 ++-- docs/ja/sandbox_agents.md | 38 +- docs/ja/sessions/advanced_sqlite_session.md | 42 +-- docs/ja/sessions/encrypted_session.md | 44 +-- docs/ja/sessions/index.md | 156 ++++---- docs/ja/sessions/sqlalchemy_session.md | 12 +- docs/ja/streaming.md | 38 +- docs/ja/tools.md | 253 +++++++------ docs/ja/tracing.md | 104 +++--- docs/ja/usage.md | 42 +-- docs/ja/visualization.md | 51 +-- docs/ja/voice/pipeline.md | 26 +- docs/ja/voice/quickstart.md | 16 +- docs/ja/voice/tracing.md | 14 +- docs/ko/agents.md | 110 +++--- docs/ko/config.md | 48 +-- docs/ko/context.md | 86 ++--- docs/ko/examples.md | 114 +++--- docs/ko/guardrails.md | 70 ++-- docs/ko/handoffs.md | 74 ++-- docs/ko/human_in_the_loop.md | 98 ++--- docs/ko/index.md | 74 ++-- docs/ko/mcp.md | 143 ++++---- docs/ko/models/index.md | 236 ++++++------ docs/ko/multi_agent.md | 66 ++-- docs/ko/quickstart.md | 48 +-- docs/ko/realtime/guide.md | 180 +++++----- docs/ko/realtime/quickstart.md | 52 +-- docs/ko/realtime/transport.md | 62 ++-- docs/ko/release.md | 116 +++--- docs/ko/repl.md | 7 +- docs/ko/results.md | 108 +++--- docs/ko/running_agents.md | 207 +++++------ docs/ko/sandbox/clients.md | 92 ++--- docs/ko/sandbox/guide.md | 350 +++++++++--------- docs/ko/sandbox/memory.md | 60 ++-- docs/ko/sandbox_agents.md | 30 +- docs/ko/sessions/advanced_sqlite_session.md | 32 +- docs/ko/sessions/encrypted_session.md | 34 +- docs/ko/sessions/index.md | 142 ++++---- docs/ko/sessions/sqlalchemy_session.md | 8 +- docs/ko/streaming.md | 36 +- docs/ko/tools.md | 248 ++++++------- docs/ko/tracing.md | 110 +++--- docs/ko/usage.md | 32 +- docs/ko/visualization.md | 49 +-- docs/ko/voice/pipeline.md | 30 +- docs/ko/voice/quickstart.md | 16 +- docs/ko/voice/tracing.md | 12 +- docs/scripts/translate_docs.py | 4 +- docs/zh/agents.md | 146 ++++---- docs/zh/config.md | 52 +-- docs/zh/context.md | 86 ++--- docs/zh/examples.md | 104 +++--- docs/zh/guardrails.md | 68 ++-- docs/zh/handoffs.md | 82 ++--- docs/zh/human_in_the_loop.md | 108 +++--- docs/zh/index.md | 88 ++--- docs/zh/mcp.md | 203 ++++++----- docs/zh/models/index.md | 246 ++++++------- docs/zh/models/litellm.md | 4 +- docs/zh/multi_agent.md | 64 ++-- docs/zh/quickstart.md | 58 +-- docs/zh/realtime/guide.md | 130 +++---- docs/zh/realtime/quickstart.md | 36 +- docs/zh/realtime/transport.md | 72 ++-- docs/zh/release.md | 90 ++--- docs/zh/repl.md | 7 +- docs/zh/results.md | 124 +++---- docs/zh/running_agents.md | 250 ++++++------- docs/zh/sandbox/clients.md | 76 ++-- docs/zh/sandbox/guide.md | 378 ++++++++++---------- docs/zh/sandbox/memory.md | 66 ++-- docs/zh/sandbox_agents.md | 36 +- docs/zh/sessions/advanced_sqlite_session.md | 40 +-- docs/zh/sessions/encrypted_session.md | 40 +-- docs/zh/sessions/index.md | 148 ++++---- docs/zh/sessions/sqlalchemy_session.md | 7 +- docs/zh/streaming.md | 34 +- docs/zh/tools.md | 220 ++++++------ docs/zh/tracing.md | 118 +++--- docs/zh/usage.md | 48 +-- docs/zh/visualization.md | 46 +-- docs/zh/voice/pipeline.md | 28 +- docs/zh/voice/quickstart.md | 20 +- docs/zh/voice/tracing.md | 14 +- uv.lock | 3 +- 109 files changed, 4945 insertions(+), 4849 deletions(-) diff --git a/docs/ja/agents.md b/docs/ja/agents.md index 37e384706c..dd8627904d 100644 --- a/docs/ja/agents.md +++ b/docs/ja/agents.md @@ -4,49 +4,49 @@ search: --- # エージェント -エージェントは、アプリにおける中核的な構成要素です。エージェントは、 instructions、tools、およびハンドオフ、ガードレール、structured outputs などの任意のランタイム動作で設定された大規模言語モデル (LLM) です。 +エージェントは、アプリにおける中核的な構成要素です。エージェントとは、instructions、ツール、およびハンドオフ、ガードレール、structured outputs などの任意のランタイム動作で設定された大規模言語モデル (LLM) です。 -単一のプレーンな `Agent` を定義またはカスタマイズしたい場合は、このページを使用してください。複数のエージェントをどのように協調させるかを決める場合は、[エージェントオーケストレーション](multi_agent.md)をお読みください。エージェントを、マニフェストで定義されたファイルとサンドボックスネイティブな機能を持つ分離ワークスペース内で実行する必要がある場合は、[サンドボックスエージェントの概念](sandbox/guide.md)をお読みください。 +単一のシンプルな `Agent` を定義またはカスタマイズしたい場合は、このページを使用してください。複数のエージェントをどのように連携させるかを検討している場合は、[エージェントオーケストレーション](multi_agent.md) を読んでください。エージェントを、マニフェストで定義されたファイルとサンドボックスネイティブ機能を備えた分離ワークスペース内で実行する必要がある場合は、[Sandbox エージェントの概念](sandbox/guide.md) を読んでください。 -SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、ここでの違いはオーケストレーションです。`Agent` と `Runner` により、SDK がターン、ツール、ガードレール、ハンドオフ、セッションを管理できます。このループを自分で制御したい場合は、代わりに Responses API を直接使用してください。 +SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、ここでの違いはオーケストレーションです。`Agent` と `Runner` により、SDK がターン、ツール、ガードレール、ハンドオフ、セッションを管理できます。そのループを自分で管理したい場合は、代わりに Responses API を直接使用してください。 ## 次のガイドの選択 -このページは、エージェント定義のハブとして使用してください。次に行う必要がある判断に合った隣接ガイドへ移動してください。 +このページをエージェント定義のハブとして使用してください。次に行う判断に合ったガイドへ進んでください。 | したいこと | 次に読むもの | | --- | --- | | モデルまたはプロバイダー設定を選択する | [モデル](models/index.md) | | エージェントに機能を追加する | [ツール](tools.md) | -| 実際のリポジトリ、ドキュメントバンドル、または分離ワークスペースに対してエージェントを実行する | [サンドボックスエージェントのクイックスタート](sandbox_agents.md) | -| マネージャー形式のオーケストレーションとハンドオフのどちらにするかを決める | [エージェントオーケストレーション](multi_agent.md) | +| 実際のリポジトリ、ドキュメントバンドル、または分離ワークスペースに対してエージェントを実行する | [Sandbox エージェントのクイックスタート](sandbox_agents.md) | +| マネージャースタイルのオーケストレーションとハンドオフのどちらにするかを決める | [エージェントオーケストレーション](multi_agent.md) | | ハンドオフ動作を設定する | [ハンドオフ](handoffs.md) | -| ターンの実行、イベントのストリーミング、または会話状態の管理を行う | [エージェントの実行](running_agents.md) | +| ターンを実行し、イベントをストリーミングし、会話状態を管理する | [エージェント実行](running_agents.md) | | 最終出力、実行アイテム、または再開可能な状態を確認する | [結果](results.md) | | ローカル依存関係とランタイム状態を共有する | [コンテキスト管理](context.md) | ## 基本設定 -エージェントの最も一般的なプロパティは次のとおりです。 +エージェントで最も一般的なプロパティは次のとおりです。 | プロパティ | 必須 | 説明 | | --- | --- | --- | -| `name` | はい | 人間が読めるエージェント名。 | -| `instructions` | はい | システムプロンプトまたは動的 instructions コールバック。[動的 instructions](#dynamic-instructions)を参照してください。 | -| `prompt` | いいえ | OpenAI Responses API のプロンプト設定。静的プロンプトオブジェクトまたは関数を受け付けます。[プロンプトテンプレート](#prompt-templates)を参照してください。 | +| `name` | はい | 人間が読みやすいエージェント名。 | +| `instructions` | いいえ | システムプロンプトまたは動的 instructions コールバック。強く推奨します。[動的 instructions](#dynamic-instructions) を参照してください。 | +| `prompt` | いいえ | OpenAI Responses API のプロンプト設定。静的なプロンプトオブジェクトまたは関数を受け付けます。[プロンプトテンプレート](#prompt-templates) を参照してください。 | | `handoff_description` | いいえ | このエージェントがハンドオフ先として提示されるときに公開される短い説明。 | -| `handoffs` | いいえ | 会話を専門エージェントに委任します。[ハンドオフ](handoffs.md)を参照してください。 | -| `model` | いいえ | 使用する LLM。[モデル](models/index.md)を参照してください。 | +| `handoffs` | いいえ | 会話を専門エージェントに委任します。[ハンドオフ](handoffs.md) を参照してください。 | +| `model` | いいえ | 使用する LLM。[モデル](models/index.md) を参照してください。 | | `model_settings` | いいえ | `temperature`、`top_p`、`tool_choice` などのモデル調整パラメーター。 | -| `tools` | いいえ | エージェントが呼び出せるツール。[ツール](tools.md)を参照してください。 | -| `mcp_servers` | いいえ | エージェント用の MCP バックのツール。[MCP ガイド](mcp.md)を参照してください。 | -| `mcp_config` | いいえ | 厳密なスキーマ変換や MCP 失敗時の整形など、MCP ツールの準備方法を微調整します。[MCP ガイド](mcp.md#agent-level-mcp-configuration)を参照してください。 | -| `input_guardrails` | いいえ | このエージェントチェーンの最初のユーザー入力で実行されるガードレール。[ガードレール](guardrails.md)を参照してください。 | -| `output_guardrails` | いいえ | このエージェントの最終出力で実行されるガードレール。[ガードレール](guardrails.md)を参照してください。 | -| `output_type` | いいえ | プレーンテキストの代わりとなる structured outputs 型。[出力型](#output-types)を参照してください。 | -| `hooks` | いいえ | エージェントスコープのライフサイクルコールバック。[ライフサイクルイベント (hooks)](#lifecycle-events-hooks)を参照してください。 | -| `tool_use_behavior` | いいえ | ツール結果をモデルに戻してループさせるか、実行を終了するかを制御します。[ツール使用動作](#tool-use-behavior)を参照してください。 | -| `reset_tool_choice` | いいえ | ツール使用ループを避けるため、ツール呼び出し後に `tool_choice` をリセットします (デフォルト: `True`)。[ツール使用の強制](#forcing-tool-use)を参照してください。 | +| `tools` | いいえ | エージェントが呼び出せるツール。[ツール](tools.md) を参照してください。 | +| `mcp_servers` | いいえ | エージェント向けの MCP ベースのツール。[MCP ガイド](mcp.md) を参照してください。 | +| `mcp_config` | いいえ | 厳格なスキーマ変換や MCP 失敗時の形式設定など、MCP ツールの準備方法を微調整します。[MCP ガイド](mcp.md#agent-level-mcp-configuration) を参照してください。 | +| `input_guardrails` | いいえ | このエージェントチェーンの最初のユーザー入力に対して実行されるガードレール。[ガードレール](guardrails.md) を参照してください。 | +| `output_guardrails` | いいえ | このエージェントの最終出力に対して実行されるガードレール。[ガードレール](guardrails.md) を参照してください。 | +| `output_type` | いいえ | プレーンテキストの代わりとなる構造化出力型。[出力型](#output-types) を参照してください。 | +| `hooks` | いいえ | エージェントスコープのライフサイクルコールバック。[ライフサイクルイベント (フック)](#lifecycle-events-hooks) を参照してください。 | +| `tool_use_behavior` | いいえ | ツールの結果をモデルに戻してループさせるか、実行を終了するかを制御します。[ツール使用の動作](#tool-use-behavior) を参照してください。 | +| `reset_tool_choice` | いいえ | ツール呼び出し後に `tool_choice` をリセットします (デフォルト: `True`)。これによりツール使用ループを避けます。[ツール使用の強制](#forcing-tool-use) を参照してください。 | ```python from agents import Agent, ModelSettings, function_tool @@ -64,13 +64,13 @@ agent = Agent( ) ``` -このセクションのすべては `Agent` に適用されます。`SandboxAgent` は同じ考え方を基にしており、ワークスペーススコープの実行のために `default_manifest`、`base_instructions`、`capabilities`、`run_as` を追加します。[サンドボックスエージェントの概念](sandbox/guide.md)を参照してください。 +このセクションの内容はすべて `Agent` に適用されます。`SandboxAgent` は同じ考え方を基盤とし、それに `default_manifest`、`base_instructions`、`capabilities`、`run_as` を加えて、ワークスペーススコープの実行に対応します。[Sandbox エージェントの概念](sandbox/guide.md) を参照してください。 ## プロンプトテンプレート -`prompt` を設定することで、OpenAI プラットフォームで作成したプロンプトテンプレートを参照できます。これは Responses API を使用する OpenAI モデルで機能します。 +`prompt` を設定することで、OpenAI プラットフォームで作成したプロンプトテンプレートを参照できます。これは Responses API を使用する OpenAI モデルで動作します。 -使用するには、次を行ってください。 +使用するには、次の手順を行ってください。 1. https://platform.openai.com/playground/prompts に移動します 2. 新しいプロンプト変数 `poem_style` を作成します。 @@ -80,7 +80,7 @@ agent = Agent( Write a poem in {{poem_style}} ``` -4. `--prompt-id` フラグを指定して例を実行します。 +4. この例を `--prompt-id` フラグ付きで実行します。 ```python from agents import Agent @@ -127,9 +127,9 @@ result = await Runner.run( ## コンテキスト -エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールです。これは、作成して `Runner.run()` に渡すオブジェクトであり、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態をまとめて保持するものとして機能します。任意の Python オブジェクトをコンテキストとして提供できます。 +エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールです。自分で作成して `Runner.run()` に渡すオブジェクトであり、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行の依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを指定できます。 -完全な `RunContextWrapper` のインターフェース、共有使用量トラッキング、ネストされた `tool_input`、およびシリアライズ時の注意点については、[コンテキストガイド](context.md)をお読みください。 +完全な `RunContextWrapper` インターフェイス、共有された使用量追跡、ネストした `tool_input`、およびシリアライズ上の注意点については、[コンテキストガイド](context.md) を読んでください。 ```python @dataclass @@ -148,7 +148,7 @@ agent = Agent[UserContext]( ## 出力型 -デフォルトでは、エージェントはプレーンテキスト (つまり `str`) の出力を生成します。エージェントに特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用することですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型をサポートしています。dataclasses、lists、TypedDict などです。 +デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) の出力を生成します。エージェントに特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用することですが、Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型にも対応しています。dataclasses、lists、TypedDict などです。 ```python from pydantic import BaseModel @@ -169,20 +169,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. マネージャー (agents as tools): 中央のマネージャー / オーケストレーターが、ツールとして公開された専門サブエージェントを呼び出し、会話の制御を保持します。 -2. ハンドオフ: 対等なエージェントが、会話を引き継ぐ専門エージェントへ制御を渡します。これは分散型です。 +1. マネージャー (agents as tools): 中央のマネージャー/オーケストレーターが、専門化されたサブエージェントをツールとして呼び出し、会話の制御を維持します。 +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) を参照してください。 ### マネージャー (agents as tools) -`customer_facing_agent` はすべてのユーザー操作を処理し、ツールとして公開された専門サブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントをお読みください。 +`customer_facing_agent` はユーザーとのやり取りをすべて処理し、ツールとして公開された専門サブエージェントを呼び出します。詳しくは [ツール](tools.md#agents-as-tools) ドキュメントを読んでください。 ```python from agents import Agent @@ -211,7 +211,7 @@ customer_facing_agent = Agent( ### ハンドオフ -ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに優れたモジュール型の専門エージェントを実現できます。詳細は [ハンドオフ](handoffs.md) ドキュメントをお読みください。 +ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントが会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに優れた、モジュール化された専門エージェントを実現できます。詳しくは [ハンドオフ](handoffs.md) ドキュメントを読んでください。 ```python from agents import Agent @@ -232,7 +232,7 @@ triage_agent = Agent( ## 動的 instructions -ほとんどの場合、エージェントを作成するときに instructions を指定できます。ただし、関数を介して動的 instructions を指定することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が受け付けられます。 +ほとんどの場合、エージェントを作成するときに instructions を指定できます。ただし、関数を通じて動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも受け付けます。 ```python def dynamic_instructions( @@ -247,29 +247,29 @@ agent = Agent[UserContext]( ) ``` -## ライフサイクルイベント (hooks) +## ライフサイクルイベント (フック) -場合によっては、エージェントのライフサイクルを観察したいことがあります。たとえば、特定のイベントが発生したときに、イベントのログ記録、データの事前取得、使用量の記録を行いたい場合があります。 +場合によっては、エージェントのライフサイクルを監視したいことがあります。たとえば、特定のイベントが発生したときに、イベントをログに記録したり、データを事前取得したり、使用量を記録したりできます。 -フックには 2 つのスコープがあります。 +フックのスコープは 2 つあります。 -- [`RunHooks`][agents.lifecycle.RunHooks] は、他のエージェントへのハンドオフを含む `Runner.run(...)` 呼び出し全体を観察します。 -- [`AgentHooks`][agents.lifecycle.AgentHooks] は `agent.hooks` を介して特定のエージェントインスタンスにアタッチされます。 +- [`RunHooks`][agents.lifecycle.RunHooks] は、他のエージェントへのハンドオフを含む `Runner.run(...)` 呼び出し全体を監視します。 +- [`AgentHooks`][agents.lifecycle.AgentHooks] は、`agent.hooks` を通じて特定のエージェントインスタンスにアタッチされます。 -コールバックコンテキストも、イベントによって変わります。 +コールバックのコンテキストもイベントに応じて変わります。 -- エージェント開始 / 終了フックは [`AgentHookContext`][agents.run_context.AgentHookContext] を受け取ります。これは元のコンテキストをラップし、共有実行使用量状態を保持します。 +- エージェントの開始/終了フックは [`AgentHookContext`][agents.run_context.AgentHookContext] を受け取ります。これは元のコンテキストをラップし、共有された実行使用量状態を保持します。 - LLM、ツール、ハンドオフのフックは [`RunContextWrapper`][agents.run_context.RunContextWrapper] を受け取ります。 典型的なフックのタイミングは次のとおりです。 -- `on_agent_start` / `on_agent_end`: 特定のエージェントが最終出力の生成を開始または完了したとき。 -- `on_llm_start` / `on_llm_end`: 各モデル呼び出しの直前直後。 +- `on_agent_start` / `on_agent_end`: 特定のエージェントが最終出力の生成を開始または終了するとき。 +- `on_llm_start` / `on_llm_end`: 各モデル呼び出しの直前/直後。 - `on_tool_start` / `on_tool_end`: 各ローカルツール呼び出しの前後。 - 関数ツールでは、フックの `context` は通常 `ToolContext` であるため、`tool_call_id` などのツール呼び出しメタデータを確認できます。 -- `on_handoff`: 制御が 1 つのエージェントから別のエージェントへ移るとき。 + 関数ツールの場合、フックの `context` は通常 `ToolContext` なので、`tool_call_id` などのツール呼び出しメタデータを確認できます。 +- `on_handoff`: 制御があるエージェントから別のエージェントへ移るとき。 -ワークフロー全体に対して 1 つのオブザーバーが必要な場合は `RunHooks` を使用し、1 つのエージェントにカスタム副作用が必要な場合は `AgentHooks` を使用してください。 +ワークフロー全体に対して単一のオブザーバーが必要な場合は `RunHooks` を使用し、1 つのエージェントにカスタム副作用が必要な場合は `AgentHooks` を使用します。 ```python from agents import Agent, RunHooks, Runner @@ -291,15 +291,15 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks()) print(result.final_output) ``` -完全なコールバックインターフェースについては、[Lifecycle API リファレンス](ref/lifecycle.md)を参照してください。 +完全なコールバック API については、[ライフサイクル API リファレンス](ref/lifecycle.md) を参照してください。 ## ガードレール -ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェック / 検証を実行し、生成後のエージェント出力に対しても実行できます。たとえば、ユーザー入力とエージェント出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントをお読みください。 +ガードレールを使うと、エージェントの実行と並行してユーザー入力に対するチェック/検証を実行し、エージェントの出力が生成された後にその出力に対するチェック/検証を実行できます。たとえば、ユーザー入力とエージェント出力について関連性をスクリーニングできます。詳しくは [ガードレール](guardrails.md) ドキュメントを読んでください。 -## エージェントのクローン / コピー +## エージェントのクローン/コピー -エージェントの `clone()` メソッドを使用すると、Agent を複製し、必要に応じて任意のプロパティを変更できます。 +エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。 ```python pirate_agent = Agent( @@ -319,11 +319,11 @@ 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` などの特定の文字列を設定すると、LLM にその特定のツールを使用することを要求します。 -OpenAI Responses のツール検索を使用している場合、名前付きツール選択にはより多くの制限があります。`tool_choice` で bare namespace 名や deferred-only ツールを対象にすることはできず、`tool_choice="tool_search"` は [`ToolSearchTool`][agents.tool.ToolSearchTool] を対象にしません。このような場合は、`auto` または `required` を優先してください。Responses 固有の制約については、[ホスト型ツール検索](tools.md#hosted-tool-search)を参照してください。 +OpenAI Responses のツール検索を使用している場合、名前付きツール選択にはより多くの制限があります。`tool_choice` で名前空間名だけや deferred-only ツールをターゲットにすることはできず、`tool_choice="tool_search"` は [`ToolSearchTool`][agents.tool.ToolSearchTool] をターゲットにしません。このような場合は、`auto` または `required` を優先してください。Responses 固有の制約については、[ホスト型ツール検索](tools.md#hosted-tool-search) を参照してください。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -341,12 +341,12 @@ agent = Agent( ) ``` -## ツール使用動作 +## ツール使用の動作 -`Agent` 設定の `tool_use_behavior` パラメーターは、ツール出力の処理方法を制御します。 +`Agent` 設定の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。 - `"run_llm_again"`: デフォルトです。ツールが実行され、LLM がその結果を処理して最終応答を生成します。 -- `"stop_on_first_tool"`: 最初のツール呼び出しの出力が、それ以上の LLM 処理なしで最終応答として使用されます。 +- `"stop_on_first_tool"`: 最初のツール呼び出しの出力が、追加の LLM 処理なしで最終応答として使用されます。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -388,7 +388,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`: ツール結果を処理し、LLM で停止するか継続するかを決定するカスタム関数。 +- `ToolsToFinalOutputFunction`: ツールの結果を処理し、停止するか、LLM による処理を続行するかを決定するカスタム関数です。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -426,4 +426,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 4c72cba1a7..223799f346 100644 --- a/docs/ja/config.md +++ b/docs/ja/config.md @@ -4,21 +4,21 @@ search: --- # 設定 -このページでは、通常はアプリケーション起動時に 1 度だけ設定する SDK 全体のデフォルト（デフォルトの OpenAI キーまたはクライアント、デフォルトの OpenAI API 形式、トレーシングエクスポートのデフォルト、ログ動作など）を扱います。 +このページでは、デフォルトの OpenAI キーまたはクライアント、デフォルトの OpenAI API の形式、トレーシングエクスポートのデフォルト、ログ記録の動作など、アプリケーション起動時に通常一度だけ設定する SDK 全体のデフォルトについて説明します。 -これらのデフォルトは sandbox ベースのワークフローにも適用されますが、sandbox ワークスペース、sandbox クライアント、セッション再利用は別途設定します。 +これらのデフォルトはサンドボックスベースのワークフローにも適用されますが、サンドボックスワークスペース、サンドボックスクライアント、セッション再利用は別途設定します。 -代わりに特定のエージェントや実行を設定する必要がある場合は、次から始めてください: +代わりに特定のエージェントまたは実行を設定する必要がある場合は、まず次を参照してください: -- 通常の `Agent` における instructions、ツール、出力タイプ、ハンドオフ、ガードレールについては [Agents](agents.md)。 -- `RunConfig`、セッション、会話状態オプションについては [エージェントの実行](running_agents.md)。 -- `SandboxRunConfig`、マニフェスト、機能、sandbox クライアント固有のワークスペース設定については [Sandbox エージェント](sandbox/guide.md)。 -- モデル選択とプロバイダー設定については [Models](models/index.md)。 -- 実行ごとのトレーシングメタデータとカスタムトレースプロセッサーについては [トレーシング](tracing.md)。 +- [エージェント](agents.md): 通常の `Agent` における instructions、tools、出力型、ハンドオフ、ガードレールについて。 +- [エージェントの実行](running_agents.md): `RunConfig`、セッション、会話状態のオプションについて。 +- [サンドボックスエージェント](sandbox/guide.md): `SandboxRunConfig`、マニフェスト、機能、サンドボックスクライアント固有のワークスペース設定について。 +- [モデル](models/index.md): モデル選択とプロバイダー設定について。 +- [トレーシング](tracing.md): 実行ごとのトレーシングメタデータとカスタムトレースプロセッサーについて。 ## API キーとクライアント -デフォルトでは、SDK は LLM リクエストとトレーシングに `OPENAI_API_KEY` 環境変数を使用します。キーは SDK が最初に OpenAI クライアントを作成する際（遅延初期化）に解決されるため、最初のモデル呼び出し前に環境変数を設定してください。アプリ起動前にその環境変数を設定できない場合は、キーを設定するために [set_default_openai_key()][agents.set_default_openai_key] 関数を使用できます。 +デフォルトでは、SDK は LLM リクエストとトレーシングに `OPENAI_API_KEY` 環境変数を使用します。このキーは、SDK が最初に OpenAI クライアントを作成するときに解決されます（遅延初期化）。そのため、最初のモデル呼び出しの前に環境変数を設定してください。アプリの起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。 ```python from agents import set_default_openai_key @@ -26,7 +26,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -または、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数の API キーまたは上記で設定したデフォルトキーを使用して `AsyncOpenAI` インスタンスを作成します。これは [set_default_openai_client()][agents.set_default_openai_client] 関数で変更できます。 +また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数の API キー、または上記で設定したデフォルトキーを使用して、`AsyncOpenAI` インスタンスを作成します。これは [set_default_openai_client()][agents.set_default_openai_client] 関数を使用して変更できます。 ```python from openai import AsyncOpenAI @@ -36,14 +36,14 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -環境変数ベースのエンドポイント設定を使いたい場合、デフォルトの OpenAI プロバイダーは `OPENAI_BASE_URL` も読み取ります。Responses websocket トランスポートを有効にすると、websocket `/responses` エンドポイント用に `OPENAI_WEBSOCKET_BASE_URL` も読み取ります。 +環境変数ベースのエンドポイント設定を使用したい場合、デフォルトの OpenAI プロバイダーは `OPENAI_BASE_URL` も読み取ります。Responses websocket トランスポートを有効にすると、websocket の `/responses` エンドポイント用に `OPENAI_WEBSOCKET_BASE_URL` も読み取ります。 ```bash export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1" export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1" ``` -最後に、使用する 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 @@ -53,7 +53,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 @@ -61,7 +61,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -モデル通信があるキーまたはクライアントを使い、トレーシングは別の OpenAI キーを使う必要がある場合、デフォルトキーまたはクライアント設定時に `use_for_tracing=False` を渡してから、トレーシングを個別に設定してください。カスタムクライアントを使わない場合は [`set_default_openai_key()`][agents.set_default_openai_key] でも同じパターンが使えます。 +モデルのトラフィックにはあるキーまたはクライアントを使用し、トレーシングには別の OpenAI キーを使用したい場合は、デフォルトキーまたはクライアントを設定するときに `use_for_tracing=False` を渡してから、トレーシングを別途設定します。カスタムクライアントを使用していない場合は、[`set_default_openai_key()`][agents.set_default_openai_key] でも同じパターンを使用できます。 ```python from openai import AsyncOpenAI @@ -76,7 +76,7 @@ set_default_openai_client(custom_client, use_for_tracing=False) set_tracing_export_api_key("sk-tracing") ``` -デフォルトのエクスポーター使用時に、トレースを特定の組織またはプロジェクトに紐付ける必要がある場合は、アプリ起動前に以下の環境変数を設定してください: +デフォルトのエクスポーターを使用する際に、トレースを特定の組織またはプロジェクトに関連付ける必要がある場合は、アプリの起動前にこれらの環境変数を設定してください: ```bash export OPENAI_ORG_ID="org_..." @@ -103,7 +103,7 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -トレーシングを有効のまま、トレースペイロードから機密性の高い可能性がある入出力を除外したい場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を `False` に設定してください: +トレーシングは有効のまま、機密性がある可能性のある入力/出力をトレースペイロードから除外したい場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を `False` に設定します: ```python from agents import Runner, RunConfig @@ -115,19 +115,19 @@ await Runner.run( ) ``` -アプリ起動前にこの環境変数を設定すれば、コードなしでデフォルトを変更することもできます: +アプリの起動前にこの環境変数を設定することで、コードを変更せずにデフォルトを変更することもできます: ```bash export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0 ``` -トレーシング制御の全体については、[トレーシングガイド](tracing.md) を参照してください。 +トレーシング制御の詳細は、[トレーシングガイド](tracing.md) を参照してください。 ## デバッグログ -SDK は 2 つの Python ロガー（`openai.agents` と `openai.agents.tracing`）を定義しており、デフォルトではハンドラーをアタッチしません。ログはアプリケーションの Python ログ設定に従います。 +SDK は 2 つの Python ロガー（`openai.agents` と `openai.agents.tracing`）を定義しますが、デフォルトではハンドラーをアタッチしません。ログはアプリケーションの Python ロギング設定に従います。 -詳細ログを有効にするには、[`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 @@ -135,7 +135,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -または、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。 +または、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) で確認できます。 ```python import logging @@ -156,16 +156,16 @@ logger.addHandler(logging.StreamHandler()) ### ログ内の機密データ -特定のログには機密データ（たとえばユーザーデータ）が含まれる場合があります。 +一部のログには機密データ（たとえば、ユーザーデータ）が含まれる場合があります。 -デフォルトでは、SDK は LLM の入出力やツールの入出力を **ログに記録しません**。これらの保護は次によって制御されます: +デフォルトでは、SDK は LLM の入力/出力やツールの入力/出力を **ログに記録しません** 。これらの保護は次で制御されます: ```bash OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 ``` -デバッグのために一時的にこれらのデータを含める必要がある場合は、アプリ起動前にいずれかの変数を `0`（または `false`）に設定してください: +デバッグのためにこのデータを一時的に含める必要がある場合は、アプリの起動前にいずれかの変数を `0`（または `false`）に設定します: ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0 diff --git a/docs/ja/context.md b/docs/ja/context.md index e868c39990..9152944e89 100644 --- a/docs/ja/context.md +++ b/docs/ja/context.md @@ -4,49 +4,49 @@ search: --- # コンテキスト管理 -コンテキストは多義的な用語です。主に、重要になるコンテキストには 2 つの分類があります。 +コンテキストは多義的な用語です。考慮すべきコンテキストには、主に 2 つの種類があります: -1. コード内でローカルに利用可能なコンテキスト: これは、関数ツールの実行時、`on_handoff` のようなコールバック時、ライフサイクルフック時などに必要になる可能性があるデータや依存関係です。 -2. LLM が利用可能なコンテキスト: これは、LLM がレスポンスを生成するときに参照するデータです。 +1. コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック内、ライフサイクルフック内などで必要になる可能性のあるデータや依存関係です。 +2. LLM が利用できるコンテキスト: これは、LLM が応答を生成するときに参照するデータです。 ## ローカルコンテキスト -これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その内部の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作は次のとおりです。 +これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラス、およびその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです: -1. 任意の Python オブジェクトを作成します。一般的なパターンは、dataclass または Pydantic オブジェクトを使うことです。 -2. そのオブジェクトを各種 run メソッドに渡します（例: `Runner.run(..., context=whatever)`）。 -3. すべてのツール呼び出し、ライフサイクルフックなどには `RunContextWrapper[T]` のラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` でアクセスできます。 +1. 任意の Python オブジェクトを作成します。一般的なパターンは dataclass や Pydantic オブジェクトを使用することです。 +2. そのオブジェクトを各種実行メソッドに渡します (例: `Runner.run(..., context=whatever)`)。 +3. すべてのツール呼び出し、ライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` を通じてアクセスできます。 -ランタイム固有の一部コールバックでは、SDK が `RunContextWrapper[T]` のより特化したサブクラスを渡す場合があります。たとえば、関数ツールのライフサイクルフックは通常 `ToolContext` を受け取り、`tool_call_id`、`tool_name`、`tool_arguments` などのツール呼び出しメタデータにもアクセスできます。 +一部のランタイム固有のコールバックでは、SDK はより特殊化された `RunContextWrapper[T]` のサブクラスを渡す場合があります。たとえば、関数ツールのライフサイクルフックは通常 `ToolContext` を受け取り、これは `tool_call_id`、`tool_name`、`tool_arguments` などのツール呼び出しメタデータも公開します。 -認識しておくべき **最も重要** な点: 特定のエージェント実行におけるすべてのエージェント、関数ツール、ライフサイクルなどは、同じコンテキストの _型_ を使用する必要があります。 +認識すべき **最も重要な** 点は、あるエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどが、同じ _型_ のコンテキストを使用しなければならないということです。 -コンテキストは次のような用途で使用できます。 +コンテキストは、たとえば次の用途に使用できます: -- 実行のためのコンテキストデータ（例: ユーザー名 / uid や、ユーザーに関するその他の情報） -- 依存関係（例: logger オブジェクト、データ取得処理など） +- 実行時のコンテキストデータ (例: ユーザー名 / uid や、ユーザーに関するその他の情報) +- 依存関係 (例: ロガーオブジェクト、データ取得器など) - ヘルパー関数 -!!! danger "注意" +!!! danger "注記" - コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルオブジェクトであり、読み取り、書き込み、メソッド呼び出しが可能です。 + コンテキストオブジェクトは LLM に **送信されません**。これは完全にローカルなオブジェクトであり、読み取り、書き込み、メソッドの呼び出しができます。 -1 回の実行内では、派生ラッパーは同じ基盤のアプリコンテキスト、承認状態、使用量トラッキングを共有します。ネストした [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行では別の `tool_input` が付与される場合がありますが、デフォルトではアプリ状態の分離コピーは取得しません。 +1 回の実行内では、派生したラッパーは同じ基盤となるアプリコンテキスト、承認状態、使用状況の追跡を共有します。ネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] の実行では異なる `tool_input` を付加する場合がありますが、デフォルトではアプリ状態の分離コピーは取得しません。 ### `RunContextWrapper` の公開内容 -[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、アプリで定義したコンテキストオブジェクトのラッパーです。実際には、主に次を使用します。 +[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、アプリで定義したコンテキストオブジェクトを包むラッパーです。実際には、ほとんどの場合、次のものを使用します: -- 独自の可変アプリ状態および依存関係には [`wrapper.context`][agents.run_context.RunContextWrapper.context]。 -- 現在の実行全体の集計されたリクエストおよびトークン使用量には [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]。 -- 現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内で実行されているときの構造化入力には [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]。 -- 承認状態をプログラムで更新する必要がある場合は [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]。 +- [`wrapper.context`][agents.run_context.RunContextWrapper.context]: 独自の可変なアプリ状態と依存関係に使用します。 +- [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]: 現在の実行全体で集計されたリクエストおよびトークン使用量に使用します。 +- [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]: 現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] の内部で実行されている場合の構造化入力に使用します。 +- [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]: 承認状態をプログラムで更新する必要がある場合に使用します。 アプリで定義したオブジェクトは `wrapper.context` のみです。その他のフィールドは SDK が管理するランタイムメタデータです。 -後で human-in-the-loop や永続ジョブワークフロー向けに [`RunState`][agents.run_state.RunState] をシリアライズする場合、そのランタイムメタデータは状態とともに保存されます。シリアライズした状態を永続化または送信する予定がある場合は、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] にシークレットを入れないでください。 +後で human-in-the-loop や耐久ジョブワークフローのために [`RunState`][agents.run_state.RunState] をシリアライズする場合、そのランタイムメタデータは状態とともに保存されます。シリアライズされた状態を永続化または送信する予定がある場合、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] にシークレットを入れないでください。 -会話状態は別の関心事項です。ターンをどのように引き継ぐかに応じて、`result.to_input_list()`、`session`、`conversation_id`、または `previous_response_id` を使用してください。この判断については [results](results.md)、[running agents](running_agents.md)、[sessions](sessions/index.md) を参照してください。 +会話状態は別の関心事です。ターンをどのように引き継ぐかに応じて、`result.to_input_list()`、`session`、`conversation_id`、または `previous_response_id` を使用してください。その判断については、[実行結果](results.md)、[エージェントの実行](running_agents.md)、[セッション](sessions/index.md) を参照してください。 ```python import asyncio @@ -85,18 +85,18 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 -2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツール実装はコンテキストから読み取ります。 -3. 型チェッカーがエラーを検出できるように、エージェントをジェネリック `UserInfo` で指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合）。 +1. これがコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。 +2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることがわかります。ツール実装はコンテキストから読み取ります。 +3. 型チェッカーがエラーを検出できるように、エージェントにジェネリック `UserInfo` を指定します (たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合)。 4. コンテキストは `run` 関数に渡されます。 5. エージェントは正しくツールを呼び出し、年齢を取得します。 --- -### 高度な使用法: `ToolContext` +### 高度な内容: `ToolContext` -場合によっては、実行中のツールに関する追加メタデータ（名前、呼び出し ID、生の引数文字列など）にアクセスしたいことがあります。 -このために、`RunContextWrapper` を拡張する [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。 +場合によっては、実行中のツールに関する追加メタデータ (名前、呼び出し ID、生の引数文字列など) にアクセスしたいことがあります。 +この場合、`RunContextWrapper` を拡張する [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。 ```python from typing import Annotated @@ -125,24 +125,24 @@ agent = Agent( ``` `ToolContext` は `RunContextWrapper` と同じ `.context` プロパティを提供し、 -さらに現在のツール呼び出しに固有の追加フィールドも提供します。 +現在のツール呼び出しに固有の追加フィールドも提供します: -- `tool_name` – 呼び出されるツールの名前 -- `tool_call_id` – このツール呼び出しの一意識別子 -- `tool_arguments` – ツールに渡される生の引数文字列 -- `tool_namespace` – ツールが `tool_namespace()` または他の名前空間付きサーフェスを通じて読み込まれた場合の、ツール呼び出しの Responses 名前空間 -- `qualified_tool_name` – 名前空間が利用可能な場合に、その名前空間で修飾されたツール名 +- `tool_name` – 呼び出されているツールの名前 +- `tool_call_id` – このツール呼び出しの一意の識別子 +- `tool_arguments` – ツールに渡された生の引数文字列 +- `tool_namespace` – ツールが `tool_namespace()` または別の名前空間付きサーフェスを通じて読み込まれた場合の、ツール呼び出しに対する Responses 名前空間 +- `qualified_tool_name` – 名前空間が利用できる場合に、その名前空間で修飾されたツール名 -実行中にツールレベルのメタデータが必要な場合は `ToolContext` を使用してください。 -エージェントとツール間の一般的なコンテキスト共有には、`RunContextWrapper` で十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストした `Agent.as_tool()` 実行が構造化入力を提供した場合は `.tool_input` も公開できます。 +実行中にツールレベルのメタデータが必要な場合は、`ToolContext` を使用してください。 +エージェントとツール間で一般的なコンテキスト共有を行うには、`RunContextWrapper` のままで十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストされた `Agent.as_tool()` 実行が構造化入力を提供した場合には `.tool_input` も公開できます。 --- ## エージェント / LLM コンテキスト -LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。つまり、新しいデータを LLM で利用可能にしたい場合は、その履歴で利用できる形にする必要があります。方法はいくつかあります。 +LLM が呼び出されるとき、その LLM が参照できる **唯一の** データは会話履歴に含まれるものです。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴内で利用可能になるような方法で行う必要があります。これにはいくつかの方法があります: -1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的文字列にもできますし、コンテキストを受け取って文字列を返す動的関数にもできます。これは、常に有用な情報（たとえばユーザー名や現在日付）に対する一般的な手法です。 -2. `Runner.run` 関数を呼び出す際の `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより下位のメッセージを持てます。 -3. 関数ツールを介して公開します。これは _オンデマンド_ のコンテキストに有用です。LLM がデータを必要とするタイミングを判断し、そのデータを取得するためにツールを呼び出せます。 -4. retrieval または Web 検索を使用します。これらは、ファイルやデータベース（retrieval）、または Web（Web 検索）から関連データを取得できる特別なツールです。これは、レスポンスを関連するコンテキストデータに「グラウンディング」するのに有用です。 \ 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. リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベースから関連データを取得する (リトリーバル)、または Web から取得する (Web 検索) ことができる特殊なツールです。これは、関連するコンテキストデータに基づいて応答を「グラウンディング」するのに便利です。 \ No newline at end of file diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 820719c934..30353d9b72 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -4,139 +4,139 @@ search: --- # コード例 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装を確認できます。これらのコード例は、異なるパターンと機能を示す複数のカテゴリーに整理されています。 +SDK のさまざまなサンプル実装は、[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples)の examples セクションで確認できます。これらのコード例は、さまざまなパターンや機能を示す複数のカテゴリーに整理されています。 ## カテゴリー - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - このカテゴリーのコード例では、次のような一般的なエージェント設計パターンを示します。 + このカテゴリーのコード例は、次のような一般的なエージェント設計パターンを示します。 - 決定論的ワークフロー - Agents as tools - ストリーミングイベントを伴う Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`) - 構造化入力パラメーターを伴う Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`) - - 並列エージェント実行 + - エージェントの並列実行 - 条件付きツール使用 - - 異なる挙動でツール使用を強制する (`examples/agent_patterns/forcing_tool_use.py`) - - 入力 / 出力ガードレール - - 審査者としての LLM + - 異なる動作でツール使用を強制 (`examples/agent_patterns/forcing_tool_use.py`) + - 入出力ガードレール + - ジャッジとしての LLM - ルーティング - ストリーミングガードレール - - ツール承認と状態シリアライズを伴う Human-in-the-loop (`examples/agent_patterns/human_in_the_loop.py`) - - ストリーミングを伴う Human-in-the-loop (`examples/agent_patterns/human_in_the_loop_stream.py`) - - 承認フロー向けのカスタム拒否メッセージ (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`) + - ツール承認と状態シリアライズを伴う人間参加型 (`examples/agent_patterns/human_in_the_loop.py`) + - ストリーミングを伴う人間参加型 (`examples/agent_patterns/human_in_the_loop_stream.py`) + - 承認フロー用のカスタム拒否メッセージ (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`) - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - これらのコード例では、次のような SDK の基本機能を紹介します。 + これらのコード例では、SDK の基本的な機能を紹介します。たとえば、次のようなものです。 - - Hello world のコード例 (デフォルトモデル、 GPT-5、 open-weight モデル) + - Hello world の例 (デフォルトモデル、GPT-5、オープンウェイトモデル) - エージェントライフサイクル管理 - - Run hooks と agent hooks のライフサイクル例 (`examples/basic/lifecycle_example.py`) + - 実行フックとエージェントフックのライフサイクル例 (`examples/basic/lifecycle_example.py`) - 動的システムプロンプト - 基本的なツール使用 (`examples/basic/tools.py`) - - ツール入力 / 出力ガードレール (`examples/basic/tool_guardrails.py`) + - ツール入出力ガードレール (`examples/basic/tool_guardrails.py`) - 画像ツール出力 (`examples/basic/image_tool_output.py`) - - ストリーミング出力 (テキスト、項目、関数呼び出し引数) - - 複数ターンで共有セッションヘルパーを使用する Responses websocket transport (`examples/basic/stream_ws.py`) + - ストリーミング出力 (テキスト、アイテム、関数呼び出し引数) + - ターン間で共有セッションヘルパーを使用する Responses WebSocket トランスポート (`examples/basic/stream_ws.py`) - プロンプトテンプレート - ファイル処理 (ローカルとリモート、画像と PDF) - - 使用状況追跡 - - Runner 管理の再試行設定 (`examples/basic/retry.py`) - - サードパーティアダプター経由の Runner 管理再試行 (`examples/basic/retry_litellm.py`) - - 非 strict な出力型 - - 以前の response ID の使用 + - 使用状況の追跡 + - Runner 管理のリトライ設定 (`examples/basic/retry.py`) + - サードパーティアダプターを介した Runner 管理のリトライ (`examples/basic/retry_litellm.py`) + - 非厳密な出力型 + - 以前のレスポンス 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):** - メッセージフィルタリングを含む、エージェントのハンドオフの実践的なコード例です。 + メッセージフィルタリングを伴うエージェントのハンドオフの実用的なコード例です。以下を含みます: - - メッセージフィルター例 (`examples/handoffs/message_filter.py`) + - メッセージフィルターの例 (`examples/handoffs/message_filter.py`) - ストリーミングを伴うメッセージフィルター (`examples/handoffs/message_filter_streaming.py`) - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - OpenAI Responses API で hosted MCP (Model Context Protocol) を使用する方法を示すコード例です。以下を含みます。 + OpenAI Responses API でホスト型 MCP (Model Context Protocol) を使用する方法を示すコード例です。以下を含みます: - - 承認なしのシンプルな hosted MCP (`examples/hosted_mcp/simple.py`) + - 承認なしのシンプルなホスト型 MCP (`examples/hosted_mcp/simple.py`) - Google Calendar などの MCP コネクター (`examples/hosted_mcp/connectors.py`) - - 割り込みベース承認を伴う Human-in-the-loop (`examples/hosted_mcp/human_in_the_loop.py`) - - MCP ツール呼び出しの on-approval コールバック (`examples/hosted_mcp/on_approval.py`) + - 中断ベースの承認を伴う人間参加型 (`examples/hosted_mcp/human_in_the_loop.py`) + - MCP ツール呼び出しの承認時コールバック (`examples/hosted_mcp/on_approval.py`) - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 以下を含め、 MCP (Model Context Protocol) でエージェントを構築する方法を学べます。 + MCP (Model Context Protocol) でエージェントを構築する方法を学びます。以下を含みます: - - Filesystem のコード例 - - Git のコード例 - - MCP prompt server のコード例 - - SSE (Server-Sent Events) のコード例 + - ファイルシステムの例 + - Git の例 + - MCP プロンプトサーバーの例 + - SSE (Server-Sent Events) の例 - SSE リモートサーバー接続 (`examples/mcp/sse_remote_example`) - - Streamable HTTP のコード例 + - Streamable HTTP の例 - Streamable HTTP リモート接続 (`examples/mcp/streamable_http_remote_example`) - - Streamable HTTP 向けカスタム HTTP client factory (`examples/mcp/streamablehttp_custom_client_example`) - - `MCPUtil.get_all_function_tools` による全 MCP ツールの事前取得 (`examples/mcp/get_all_mcp_tools_example`) + - Streamable HTTP 用のカスタム HTTP クライアントファクトリー (`examples/mcp/streamablehttp_custom_client_example`) + - `MCPUtil.get_all_function_tools` によるすべての MCP ツールの事前取得 (`examples/mcp/get_all_mcp_tools_example`) - FastAPI を使用した MCPServerManager (`examples/mcp/manager_example`) - MCP ツールフィルタリング (`examples/mcp/tool_filter_example`) - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - エージェント向けのさまざまなメモリ実装のコード例です。以下を含みます。 + エージェント向けのさまざまなメモリ実装のコード例です。以下を含みます: - SQLite セッションストレージ - 高度な SQLite セッションストレージ - Redis セッションストレージ - SQLAlchemy セッションストレージ - - Dapr state store セッションストレージ + - Dapr 状態ストアセッションストレージ - 暗号化セッションストレージ - OpenAI Conversations セッションストレージ - - Responses compaction セッションストレージ - - `ModelSettings(store=False)` を使用したステートレスな Responses compaction (`examples/memory/compaction_session_stateless_example.py`) - - ファイルベースのセッションストレージ (`examples/memory/file_session.py`) - - Human-in-the-loop を伴うファイルベースセッション (`examples/memory/file_hitl_example.py`) - - Human-in-the-loop を伴う SQLite インメモリセッション (`examples/memory/memory_session_hitl_example.py`) - - Human-in-the-loop を伴う OpenAI Conversations セッション (`examples/memory/openai_session_hitl_example.py`) + - Responses 圧縮セッションストレージ + - `ModelSettings(store=False)` を使用したステートレスな Responses 圧縮 (`examples/memory/compaction_session_stateless_example.py`) + - ファイルバック型セッションストレージ (`examples/memory/file_session.py`) + - 人間参加型を伴うファイルバック型セッション (`examples/memory/file_hitl_example.py`) + - 人間参加型を伴う SQLite インメモリセッション (`examples/memory/memory_session_hitl_example.py`) + - 人間参加型を伴う OpenAI Conversations セッション (`examples/memory/openai_session_hitl_example.py`) - セッションをまたぐ HITL 承認 / 拒否シナリオ (`examples/memory/hitl_session_scenario.py`) - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - カスタムプロバイダーやサードパーティアダプターを含め、 SDK で非 OpenAI モデルを使用する方法を確認できます。 + カスタムプロバイダーやサードパーティアダプターを含め、SDK で OpenAI 以外のモデルを使用する方法を確認できます。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK を使用してリアルタイム体験を構築する方法を示すコード例です。以下を含みます。 + SDK を使用してリアルタイム体験を構築する方法を示すコード例です。以下を含みます: - - 構造化されたテキストおよび画像メッセージによる Web アプリケーションパターン + - 構造化テキストと画像メッセージを扱う Web アプリケーションパターン - コマンドライン音声ループと再生処理 - WebSocket 経由の Twilio Media Streams 統合 - - Realtime Calls API attach フローを使用した Twilio SIP 統合 + - Realtime Calls API の attach フローを使用した Twilio SIP 統合 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - reasoning content の扱い方を示すコード例です。以下を含みます。 + 推論コンテンツの扱い方を示すコード例です。以下を含みます: - - Runner API、ストリーミング、非ストリーミングでの reasoning content (`examples/reasoning_content/runner_example.py`) - - OpenRouter 経由で OSS モデルを使用した reasoning content (`examples/reasoning_content/gpt_oss_stream.py`) - - 基本的な reasoning content のコード例 (`examples/reasoning_content/main.py`) + - Runner API での推論コンテンツ、ストリーミングと非ストリーミング (`examples/reasoning_content/runner_example.py`) + - OpenRouter 経由の OSS モデルでの推論コンテンツ (`examples/reasoning_content/gpt_oss_stream.py`) + - 基本的な推論コンテンツの例 (`examples/reasoning_content/main.py`) - **[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 がホストするツールと実験的な Codex ツール機能の実装方法を学べます。 + OpenAI がホストするツールや、次のような実験的な Codex ツール群の実装方法を学びます: - - Web 検索 とフィルター付き Web 検索 + - Web 検索およびフィルター付き Web 検索 - ファイル検索 - Code interpreter - ファイル編集と承認を伴う apply patch ツール (`examples/tools/apply_patch.py`) - - 承認コールバックを伴う shell ツール実行 (`examples/tools/shell.py`) - - Human-in-the-loop 割り込みベース承認を伴う shell ツール (`examples/tools/shell_human_in_the_loop.py`) - - インラインスキルを伴う hosted container shell (`examples/tools/container_shell_inline_skill.py`) - - スキル参照を伴う hosted container shell (`examples/tools/container_shell_skill_reference.py`) - - ローカルスキルを伴う local shell (`examples/tools/local_shell_skill.py`) - - 名前空間と遅延ツールを伴うツール検索 (`examples/tools/tool_search.py`) + - 承認コールバックを伴うシェルツール実行 (`examples/tools/shell.py`) + - 人間参加型の中断ベース承認を伴うシェルツール (`examples/tools/shell_human_in_the_loop.py`) + - インラインスキルを使用するホスト型コンテナーシェル (`examples/tools/container_shell_inline_skill.py`) + - スキル参照を使用するホスト型コンテナーシェル (`examples/tools/container_shell_skill_reference.py`) + - ローカルスキルを使用するローカルシェル (`examples/tools/local_shell_skill.py`) + - 名前空間と遅延ツールを使用するツール検索 (`examples/tools/tool_search.py`) - コンピュータ操作 - 画像生成 - 実験的な Codex ツールワークフロー (`examples/tools/codex.py`) - 実験的な Codex 同一スレッドワークフロー (`examples/tools/codex_same_thread.py`) - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):** - ストリーミング音声のコード例を含む、 TTS および STT モデルを使用した音声エージェントのコード例を確認できます。 \ No newline at end of file + OpenAI の TTS および STT モデルを使用する音声エージェントの例をご覧ください。ストリーミング音声の例も含まれます。 \ No newline at end of file diff --git a/docs/ja/guardrails.md b/docs/ja/guardrails.md index 3d3bd3c551..4424183866 100644 --- a/docs/ja/guardrails.md +++ b/docs/ja/guardrails.md @@ -4,74 +4,74 @@ search: --- # ガードレール -ガードレールを使うと、ユーザー入力とエージェント出力のチェックや検証を行えます。たとえば、顧客リクエスト対応のために非常に高性能（したがって低速 / 高コスト）なモデルを使うエージェントがあるとします。悪意のあるユーザーに、そのモデルで数学の宿題を手伝わせたくはありません。そのため、高速 / 低コストなモデルでガードレールを実行できます。ガードレールが悪意のある利用を検知した場合、すぐにエラーを発生させて高コストなモデルの実行を防げます。これにより時間とコストを節約できます（ **blocking guardrails** を使う場合。並列ガードレールでは、ガードレール完了前に高コストなモデルがすでに実行を開始している可能性があります。詳細は下記の「実行モード」を参照してください）。 +ガードレールを使用すると、ユーザー入力とエージェント出力のチェックと検証を行えます。例えば、顧客リクエストの支援に非常に賢い（そのため遅く高コストな）モデルを使用するエージェントがあるとします。悪意あるユーザーが、そのモデルに数学の宿題を手伝わせることは望ましくありません。そのため、高速/低コストなモデルでガードレールを実行できます。ガードレールが悪用を検出した場合、ただちにエラーを発生させ、高コストなモデルの実行を防ぐことができ、時間とコストを節約できます（ **ブロッキングガードレールを使用している場合です。並列ガードレールでは、ガードレールが完了する前に高コストなモデルの実行がすでに開始している可能性があります。詳細は以下の「実行モード」を参照してください** ）。 ガードレールには 2 種類あります。 -1. Input ガードレールは最初のユーザー入力で実行されます -2. Output ガードレールは最終的なエージェント出力で実行されます +1. 入力ガードレールは最初のユーザー入力に対して実行されます +2. 出力ガードレールは最終的なエージェント出力に対して実行されます -## ワークフロー境界 +## ワークフローの境界 -ガードレールはエージェントとツールにアタッチされますが、ワークフロー内の同じタイミングで実行されるわけではありません。 +ガードレールはエージェントやツールに付与されますが、ワークフロー内の同じ時点ですべてが実行されるわけではありません。 -- **Input ガードレール** はチェーン内の最初のエージェントに対してのみ実行されます。 -- **Output ガードレール** は最終出力を生成するエージェントに対してのみ実行されます。 -- **ツールガードレール** はカスタム関数ツールの呼び出しごとに実行され、Input ガードレールは実行前、Output ガードレールは実行後に実行されます。 +- **入力ガードレール** は、チェーン内の最初のエージェントに対してのみ実行されます。 +- **出力ガードレール** は、最終出力を生成するエージェントに対してのみ実行されます。 +- **ツールガードレール** は、すべてのカスタム関数ツール呼び出しで実行されます。入力ガードレールは実行前に、出力ガードレールは実行後に実行されます。 -manager、ハンドオフ、または委譲された specialist を含むワークフローで、カスタム関数ツール呼び出しごとにチェックが必要な場合は、エージェントレベルの Input / Output ガードレールのみに頼るのではなく、ツールガードレールを使用してください。 +マネージャー、ハンドオフ、または委任先のスペシャリストを含むワークフローで、各カスタム関数ツール呼び出しの周囲にチェックが必要な場合は、エージェントレベルの入力/出力ガードレールだけに頼るのではなく、ツールガードレールを使用してください。 -## Input ガードレール +## 入力ガードレール -Input ガードレールは 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] 例外が発生するため、ユーザーへの適切な応答や例外処理を行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true であるかどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへ適切に応答したり、例外を処理したりできます。 !!! Note - Input ガードレールはユーザー入力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントである場合にのみ実行されます。`guardrails` プロパティが `Runner.run` に渡されるのではなくエージェント側にある理由は何か、と疑問に思うかもしれません。これは、ガードレールが実際の Agent に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。 + 入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントのガードレールは、そのエージェントが *最初の* エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティが `Runner.run` に渡されるのではなく、エージェント上にあるのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに関連することが多いためです。エージェントごとに異なるガードレールを実行することになるため、コードを同じ場所に配置すると読みやすさの面で有用です。 ### 実行モード -Input ガードレールは 2 つの実行モードをサポートしています。 +入力ガードレールは 2 つの実行モードをサポートします。 -- **並列実行**（デフォルト、`run_in_parallel=True`）: ガードレールはエージェント実行と同時に並行して実行されます。両方が同時に開始されるため、レイテンシの面で最も有利です。ただし、ガードレールが失敗した場合、キャンセルされる前にエージェントがすでにトークンを消費し、ツールを実行している可能性があります。 +- **並列実行** （デフォルト、 `run_in_parallel=True` ）: ガードレールはエージェントの実行と同時に実行されます。両方が同時に開始するため、レイテンシーの面で最良です。ただし、ガードレールが失敗した場合、キャンセルされる前にエージェントがすでにトークンを消費し、ツールを実行している可能性があります。 -- **ブロッキング実行**（`run_in_parallel=False`）: ガードレールはエージェント開始 *前* に実行され、完了します。ガードレールの tripwire がトリガーされた場合、エージェントは実行されないため、トークン消費とツール実行を防げます。これはコスト最適化に理想的で、ツール呼び出しによる潜在的な副作用を避けたい場合にも適しています。 +- **ブロッキング実行** （ `run_in_parallel=False` ）: ガードレールはエージェントの開始 *前に* 実行され、完了します。ガードレールのトリップワイヤーがトリガーされた場合、エージェントは一切実行されないため、トークン消費とツール実行を防げます。これは、コスト最適化や、ツール呼び出しによる潜在的な副作用を避けたい場合に最適です。 -## Output ガードレール +## 出力ガードレール -Output ガードレールは 3 ステップで実行されます。 +出力ガードレールは 3 ステップで実行されます。 -1. まず、ガードレールはエージェントが生成した出力を受け取ります。 +1. まず、ガードレールはエージェントによって生成された出力を受け取ります。 2. 次に、ガードレール関数が実行されて [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます -3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへの適切な応答や例外処理を行えます。 +3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true であるかどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへ適切に応答したり、例外を処理したりできます。 !!! Note - Output ガードレールは最終的なエージェント出力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最後* のエージェントである場合にのみ実行されます。Input ガードレールと同様に、これはガードレールが実際の Agent に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。 + 出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、エージェントのガードレールは、そのエージェントが *最後の* エージェントである場合にのみ実行されます。入力ガードレールと同様に、これはガードレールが実際のエージェントに関連することが多いためです。エージェントごとに異なるガードレールを実行することになるため、コードを同じ場所に配置すると読みやすさの面で有用です。 - Output ガードレールは常にエージェント完了後に実行されるため、`run_in_parallel` パラメーターはサポートしていません。 + 出力ガードレールは常にエージェントの完了後に実行されるため、 `run_in_parallel` パラメーターはサポートしていません。 ## ツールガードレール -ツールガードレールは **function tools** をラップし、実行の前後でツール呼び出しを検証またはブロックできます。設定はツール自体に対して行い、そのツールが呼び出されるたびに実行されます。 +ツールガードレールは **関数ツール** をラップし、実行前後にツール呼び出しを検証またはブロックできるようにします。ツール自体に設定され、そのツールが呼び出されるたびに実行されます。 -- Input ツールガードレールはツール実行前に実行され、呼び出しをスキップする、メッセージで出力を置き換える、または tripwire を発生させることができます。 -- Output ツールガードレールはツール実行後に実行され、出力を置き換えるか、tripwire を発生させることができます。 -- ツールガードレールは [`function_tool`][agents.tool.function_tool] で作成された関数ツールにのみ適用されます。ハンドオフは通常の関数ツールパイプラインではなく SDK のハンドオフパイプラインを通るため、ツールガードレールはハンドオフ呼び出し自体には適用されません。Hosted ツール（`WebSearchTool`、`FileSearchTool`、`HostedMCPTool`、`CodeInterpreterTool`、`ImageGenerationTool`）および組み込み実行ツール（`ComputerTool`、`ShellTool`、`ApplyPatchTool`、`LocalShellTool`）もこのガードレールパイプラインを使用せず、[`Agent.as_tool()`][agents.agent.Agent.as_tool] でも現在はツールガードレールオプションを直接公開していません。 +- 入力ツールガードレールはツールの実行前に実行され、呼び出しのスキップ、出力のメッセージへの置き換え、またはトリップワイヤーの発生を行えます。 +- 出力ツールガードレールはツールの実行後に実行され、出力の置き換え、またはトリップワイヤーの発生を行えます。 +- ツールガードレールは、[`function_tool`][agents.tool.function_tool] で作成された関数ツールにのみ適用されます。ハンドオフは通常の関数ツールパイプラインではなく SDK のハンドオフパイプラインを通るため、ツールガードレールはハンドオフ呼び出し自体には適用されません。ホスト型ツール（ `WebSearchTool` 、 `FileSearchTool` 、 `HostedMCPTool` 、 `CodeInterpreterTool` 、 `ImageGenerationTool` ）や組み込み実行ツール（ `ComputerTool` 、 `ShellTool` 、 `ApplyPatchTool` 、 `LocalShellTool` ）もこのガードレールパイプラインを使用しません。また、[`Agent.as_tool()`][agents.agent.Agent.as_tool] は現在、ツールガードレールのオプションを直接公開していません。 詳細は以下のコードスニペットを参照してください。 ## トリップワイヤー -入力または出力がガードレールに失敗した場合、Guardrail は tripwire でこれを通知できます。tripwire がトリガーされたガードレールを検知すると、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、Agent の実行を停止します。 +入力または出力がガードレールの検査に合格しない場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーがトリガーされたガードレールを検出すると、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェント実行を停止します。 -## ガードレール実装 +## ガードレールの実装 -入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。この例では、内部で Agent を実行してこれを実現します。 +入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行することでこれを行います。 ```python from pydantic import BaseModel @@ -124,12 +124,12 @@ async def main(): print("Math homework guardrail tripped") ``` -1. このエージェントをガードレール関数内で使用します。 -2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。 -3. ガードレール結果には追加情報を含められます。 +1. このエージェントをガードレール関数で使用します。 +2. これは、エージェントの入力/コンテキストを受け取り、実行結果を返すガードレール関数です。 +3. ガードレールの実行結果に追加情報を含めることができます。 4. これはワークフローを定義する実際のエージェントです。 -Output ガードレールも同様です。 +出力ガードレールも同様です。 ```python from pydantic import BaseModel @@ -184,10 +184,10 @@ async def main(): 1. これは実際のエージェントの出力型です。 2. これはガードレールの出力型です。 -3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。 +3. これは、エージェントの出力を受け取り、実行結果を返すガードレール関数です。 4. これはワークフローを定義する実際のエージェントです。 -最後に、ツールガードレールの例を示します。 +最後に、ツールガードレールのコード例を示します。 ```python import json diff --git a/docs/ja/handoffs.md b/docs/ja/handoffs.md index 91f0810699..a44c31621e 100644 --- a/docs/ja/handoffs.md +++ b/docs/ja/handoffs.md @@ -4,21 +4,21 @@ 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` オブジェクトを受け取ることもできます。 -プレーンな `Agent` インスタンスを渡す場合、[`handoff_description`][agents.agent.Agent.handoff_description]（設定されている場合）がデフォルトのツール説明に追記されます。これを使うと、完全な `handoff()` オブジェクトを書かなくても、どのときにそのハンドオフをモデルが選ぶべきかを示せます。 +単純な `Agent` インスタンスを渡した場合、それらの [`handoff_description`][agents.agent.Agent.handoff_description]（設定されている場合）が既定のツール説明に追加されます。完全な `handoff()` オブジェクトを書かずに、モデルがそのハンドオフを選ぶべきタイミングを示すために使用してください。 -Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加えて、任意のオーバーライドや input filter を指定できます。 +Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用して、ハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、省略可能なオーバーライドや入力フィルターを指定できます。 ### 基本的な使い方 -シンプルなハンドオフは次のように作成できます。 +簡単なハンドオフは次のように作成できます。 ```python from agents import Agent, handoff @@ -30,22 +30,22 @@ 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`: ハンドオフのツール呼び出し引数のスキーマです。設定すると、パース済みペイロードが `on_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`: ハンドオフのツール呼び出し引数のスキーマです。設定されている場合、解析済みのペイロードが `on_handoff` に渡されます。 - `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。 -- `is_enabled`: ハンドオフを有効にするかどうかです。boolean または boolean を返す関数を指定でき、実行時に動的に有効 / 無効を切り替えられます。 -- `nest_handoff_history`: RunConfig レベルの `nest_handoff_history` 設定を呼び出し単位で上書きする任意設定です。`None` の場合、アクティブな実行設定で定義された値が代わりに使われます。 +- `is_enabled`: ハンドオフが有効かどうかです。これはブール値、またはブール値を返す関数にできます。これにより、実行時にハンドオフを動的に有効化または無効化できます。 +- `nest_handoff_history`: RunConfig レベルの `nest_handoff_history` 設定に対する、呼び出しごとの任意のオーバーライドです。`None` の場合、アクティブな実行設定で定義された値が代わりに使用されます。 -[`handoff()`][agents.handoffs.handoff] ヘルパーは、常に渡された特定の `agent` に制御を移します。遷移先候補が複数ある場合は、遷移先ごとにハンドオフを 1 つずつ登録し、モデルにその中から選ばせてください。独自のハンドオフコードが呼び出し時に返すエージェントを決定する必要がある場合にのみ、カスタム [`Handoff`][agents.handoffs.Handoff] を使用してください。 +[`handoff()`][agents.handoffs.handoff] ヘルパーは、常に渡された特定の `agent` に制御を移します。複数の宛先候補がある場合は、宛先ごとに 1 つのハンドオフを登録し、モデルにそれらの中から選ばせてください。独自のハンドオフコードが、呼び出し時にどのエージェントを返すかを決定する必要がある場合にのみ、カスタム [`Handoff`][agents.handoffs.Handoff] を使用してください。 ```python from agents import Agent, handoff, RunContextWrapper @@ -65,7 +65,7 @@ handoff_obj = handoff( ## ハンドオフ入力 -状況によっては、ハンドオフを呼び出すときに LLM にデータを渡してほしいことがあります。たとえば「Escalation agent」へのハンドオフを考えてみてください。ログに記録できるよう、理由を渡してほしい場合があります。 +状況によっては、ハンドオフを呼び出す際に LLM に何らかのデータを提供させたい場合があります。たとえば、「エスカレーションエージェント」へのハンドオフを想像してください。理由を提供させて、それをログに記録したい場合があります。 ```python from pydantic import BaseModel @@ -87,42 +87,42 @@ handoff_obj = handoff( ) ``` -`input_type` は、ハンドオフツール呼び出し自体の引数を記述します。SDK はそのスキーマをハンドオフツールの `parameters` としてモデルに公開し、返された JSON をローカルで検証して、パース済みの値を `on_handoff` に渡します。 +`input_type` は、ハンドオフツール呼び出し自体の引数を記述します。SDK はそのスキーマをハンドオフツールの `parameters` としてモデルに公開し、返された JSON をローカルで検証して、解析済みの値を `on_handoff` に渡します。 -これは次のエージェントのメイン入力を置き換えるものではなく、遷移先を変更するものでもありません。[`handoff()`][agents.handoffs.handoff] ヘルパーは、引き続きラップした特定のエージェントへハンドオフします。また、受信側エージェントは、[`input_filter`][agents.handoffs.Handoff.input_filter] やネストされたハンドオフ履歴設定で変更しない限り、会話履歴を引き続き参照します。 +これは次のエージェントのメイン入力を置き換えるものではなく、別の宛先を選ぶものでもありません。[`handoff()`][agents.handoffs.handoff] ヘルパーは引き続き、ラップした特定のエージェントに転送し、受信側エージェントは [`input_filter`][agents.handoffs.Handoff.input_filter] またはネストされたハンドオフ履歴設定で変更しない限り、会話履歴を参照します。 -`input_type` は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] とも別物です。`input_type` は、ハンドオフ時にモデルが決定するメタデータに使い、ローカルですでに持っているアプリケーション状態や依存関係には使わないでください。 +`input_type` は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] とも別です。`input_type` は、ハンドオフ時にモデルが決定するメタデータに使用し、アプリケーション状態やローカルにすでにある依存関係には使用しないでください。 -### `input_type` を使うタイミング +### `input_type` の使用場面 -ハンドオフに `reason`、`language`、`priority`、`summary` のような、モデル生成の小さなメタデータが必要な場合に `input_type` を使ってください。たとえば、トリアージエージェントは `{ "reason": "duplicate_charge", "priority": "high" }` を付けて返金エージェントへハンドオフでき、`on_handoff` は返金エージェントに制御が移る前にそのメタデータをログ化または永続化できます。 +`input_type` は、ハンドオフで `reason`、`language`、`priority`、`summary` など、モデルが生成する小さなメタデータが必要な場合に使用します。たとえば、トリアージエージェントは `{ "reason": "duplicate_charge", "priority": "high" }` を付けて返金エージェントにハンドオフでき、`on_handoff` は返金エージェントが引き継ぐ前にそのメタデータをログに記録したり永続化したりできます。 -目的が異なる場合は、別の仕組みを選んでください。 +目的が異なる場合は、別の仕組みを選択してください。 -- 既存のアプリケーション状態と依存関係は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] に入れてください。[context ガイド](context.md)を参照してください。 -- 受信側エージェントが見る履歴を変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]、または [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] を使ってください。 -- 複数の専門エージェントが候補にある場合は、遷移先ごとにハンドオフを 1 つずつ登録してください。`input_type` は選ばれたハンドオフにメタデータを追加できますが、遷移先の振り分けはしません。 -- 会話を転送せずにネストされた専門エージェント向けの構造化入力が欲しい場合は、[`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool] を優先してください。[tools](tools.md#structured-input-for-tool-agents)を参照してください。 +- 既存のアプリケーション状態と依存関係は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] に入れてください。[コンテキストガイド](context.md) を参照してください。 +- 受信側エージェントが参照する履歴を変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]、または [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] を使用してください。 +- 複数の専門エージェント候補がある場合は、宛先ごとに 1 つのハンドオフを登録してください。`input_type` は選択されたハンドオフにメタデータを追加できますが、宛先間の振り分けは行いません。 +- 会話を転送せずにネストされた専門エージェントへ構造化入力を渡したい場合は、[`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool] を優先してください。[ツール](tools.md#structured-input-for-tool-agents)を参照してください。 -## input filter +## 入力フィルター -ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を参照できる状態になります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。input filter は、既存入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。 +ハンドオフが発生すると、新しいエージェントが会話を引き継いだかのように、以前の会話履歴全体を参照できるようになります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で既存の入力を受け取り、新しい `HandoffInputData` を返す必要がある関数です。 [`HandoffInputData`][agents.handoffs.HandoffInputData] には次が含まれます。 -- `input_history`: `Runner.run(...)` 開始前の入力履歴。 -- `pre_handoff_items`: ハンドオフが呼び出されたエージェントターンより前に生成されたアイテム。 -- `new_items`: 現在のターン中に生成されたアイテム（ハンドオフ呼び出しとハンドオフ出力アイテムを含む）。 -- `input_items`: `new_items` の代わりに次のエージェントへ渡す任意のアイテム。これにより、セッション履歴用に `new_items` を保ったまま、モデル入力をフィルタリングできます。 -- `run_context`: ハンドオフ呼び出し時点でアクティブな [`RunContextWrapper`][agents.run_context.RunContextWrapper]。 +- `input_history`: `Runner.run(...)` が開始される前の入力履歴です。 +- `pre_handoff_items`: ハンドオフが呼び出されたエージェントターンの前に生成された項目です。 +- `new_items`: 現在のターン中に生成された項目です。ハンドオフ呼び出しとハンドオフ出力項目を含みます。 +- `input_items`: `new_items` の代わりに次のエージェントへ転送する任意の項目です。`new_items` をセッション履歴用にそのまま保持しながら、モデル入力をフィルタリングできます。 +- `run_context`: ハンドオフが呼び出された時点でアクティブな [`RunContextWrapper`][agents.run_context.RunContextWrapper] です。 -ネストされたハンドオフは opt-in のベータとして提供されており、安定化のためデフォルトでは無効です。[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を有効にすると、runner はそれまでの transcript を 1 つの assistant 要約メッセージに折りたたみ、同一 run 中に複数のハンドオフが起きると新しいターンが追記され続ける `` ブロックに包みます。完全な `input_filter` を書かずに生成メッセージを置き換えたい場合は、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] で独自のマッピング関数を渡せます。この opt-in は、ハンドオフ側と run 側のいずれも明示的な `input_filter` を指定していない場合にのみ適用されるため、すでにペイロードをカスタマイズしている既存コード（このリポジトリのコード例を含む）は変更なしで現在の挙動を維持します。[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡すことで、単一ハンドオフのネスト挙動を上書きできます（これは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を設定します）。生成要約のラッパーテキストだけを変更したい場合は、エージェント実行前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 +ネストされたハンドオフはオプトインのベータとして利用可能で、安定化中のため既定では無効です。[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を有効にすると、ランナーはそれまでのトランスクリプトを単一の assistant 要約メッセージにまとめ、それを `` ブロックでラップします。このブロックには、同じ実行中に複数のハンドオフが発生した場合、新しいターンが追加され続けます。完全な `input_filter` を書かずに生成されたメッセージを置き換えるには、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 経由で独自のマッピング関数を提供できます。このオプトインは、ハンドオフと実行のどちらも明示的な `input_filter` を提供していない場合にのみ適用されるため、すでにペイロードをカスタマイズしている既存のコード（このリポジトリのコード例を含む）は、変更なしで現在の動作を維持します。単一のハンドオフについてネスト動作を上書きするには、[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡します。これにより [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] が設定されます。生成された要約のラッパーテキストを変更するだけでよい場合は、エージェントを実行する前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（および必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。 -ハンドオフ側とアクティブな [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] の両方でフィルターが定義されている場合、その特定ハンドオフではハンドオフ単位の [`input_filter`][agents.handoffs.Handoff.input_filter] が優先されます。 +ハンドオフとアクティブな [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] の両方でフィルターが定義されている場合、その特定のハンドオフでは、ハンドオフごとの [`input_filter`][agents.handoffs.Handoff.input_filter] が優先されます。 !!! note - ハンドオフは単一の run 内に留まります。入力ガードレールは依然としてチェーン内の最初のエージェントにのみ適用され、出力ガードレールは最終出力を生成するエージェントにのみ適用されます。ワークフロー内の各カスタム function-tool 呼び出しごとにチェックが必要な場合は、ツールガードレールを使用してください。 + ハンドオフは単一の実行内に留まります。入力ガードレールは引き続きチェーン内の最初のエージェントにのみ適用され、出力ガードレールは最終出力を生成するエージェントにのみ適用されます。ワークフロー内の各カスタム関数ツール呼び出しの周辺でチェックが必要な場合は、ツールガードレールを使用してください。 一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装されています。 @@ -138,11 +138,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/human_in_the_loop.md b/docs/ja/human_in_the_loop.md index 6f08743b56..5466e7f28d 100644 --- a/docs/ja/human_in_the_loop.md +++ b/docs/ja/human_in_the_loop.md @@ -2,19 +2,19 @@ search: exclude: true --- -# Human-in-the-loop +# ヒューマンインザループ -human-in-the-loop ( HITL ) フローを使用すると、機密性の高いツール呼び出しを人が承認または拒否するまで、エージェント実行を一時停止できます。ツールは承認が必要なタイミングを宣言し、実行結果は保留中の承認を中断として表示し、`RunState` によって判断後に実行をシリアライズおよび再開できます。 +human-in-the-loop (HITL) フローを使用すると、機密性の高いツール呼び出しが人によって承認または拒否されるまで、エージェントの実行を一時停止できます。ツールは承認が必要なタイミングを宣言し、実行結果は保留中の承認を中断として表面化し、`RunState` によって判断後の実行をシリアライズして再開できます。 -この承認サーフェスは実行全体に適用され、現在のトップレベルエージェントに限定されません。同じパターンは、ツールが現在のエージェントに属する場合、ハンドオフで到達したエージェントに属する場合、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に属する場合にも適用されます。ネストされた `Agent.as_tool()` の場合でも、中断は外側の実行に表示されるため、外側の `RunState` で承認または拒否し、元のトップレベル実行を再開します。 +この承認が表面化する範囲は実行全体であり、現在のトップレベルエージェントに限定されません。同じパターンは、ツールが現在のエージェントに属する場合、ハンドオフで到達したエージェントに属する場合、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に属する場合にも適用されます。ネストされた `Agent.as_tool()` の場合でも、中断は外側の実行に表面化するため、外側の `RunState` で承認または拒否し、元のトップレベル実行を再開します。 -`Agent.as_tool()` では、承認は 2 つの異なるレイヤーで発生する可能性があります。エージェントツール自体が `Agent.as_tool(..., needs_approval=...)` によって承認を要求でき、さらにネストされたエージェント内のツールがネスト実行開始後に独自の承認を発生させることもできます。どちらも同じ外側実行の中断フローで処理されます。 +`Agent.as_tool()` では、承認は 2 つの異なる層で発生することがあります。エージェントツール自体が `Agent.as_tool(..., needs_approval=...)` によって承認を必要とする場合があり、ネストされたエージェント内のツールが、ネストされた実行の開始後に独自の承認を要求する場合もあります。どちらも同じ外側の実行の中断フローで処理されます。 -このページでは、`interruptions` を介した手動承認フローに焦点を当てます。アプリがコードで判断できる場合、一部のツールタイプはプログラムによる承認コールバックもサポートしており、実行を一時停止せずに継続できます。 +このページでは、`interruptions` による手動承認フローに焦点を当てます。アプリがコード内で判断できる場合、一部のツールタイプはプログラムによる承認コールバックもサポートしているため、一時停止せずに実行を継続できます。 -## 承認が必要なツールのマーキング +## 承認が必要なツールのマーク付け -`needs_approval` を `True` に設定すると常に承認が必要になり、呼び出しごとに判断する非同期関数を渡すこともできます。呼び出し可能オブジェクトは、実行コンテキスト、解析済みツールパラメーター、ツール呼び出し ID を受け取ります。 +常に承認を必須にするには `needs_approval` を `True` に設定し、呼び出しごとに判断するには async 関数を指定します。この呼び出し可能オブジェクトは、実行コンテキスト、解析済みのツールパラメーター、ツール呼び出し ID を受け取ります。 ```python from agents import Agent, Runner, function_tool @@ -41,28 +41,28 @@ agent = Agent( ) ``` -`needs_approval` は [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool]、[`ApplyPatchTool`][agents.tool.ApplyPatchTool] で利用できます。ローカル MCP サーバーも、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の `require_approval` を通じて承認をサポートします。ホスト型 MCP サーバーは、[`HostedMCPTool`][agents.tool.HostedMCPTool] の `tool_config={"require_approval": "always"}` と、任意の `on_approval_request` コールバックを介して承認をサポートします。 shell および apply_patch ツールは、割り込みを表示せずに自動承認または自動拒否したい場合に `on_approval` コールバックを受け付けます。 +`needs_approval` は [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool]、[`ApplyPatchTool`][agents.tool.ApplyPatchTool] で利用できます。ローカル MCP サーバーも、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の `require_approval` によって承認をサポートします。ホスト型 MCP サーバーは、`tool_config={"require_approval": "always"}` と任意の `on_approval_request` コールバックを指定した [`HostedMCPTool`][agents.tool.HostedMCPTool] によって承認をサポートします。シェルツールと apply_patch ツールは、中断を表面化させずに自動承認または自動拒否したい場合に、`on_approval` コールバックを受け付けます。 ## 承認フローの仕組み -1. モデルがツール呼び出しを出力すると、ランナーはその承認ルール (`needs_approval`、`require_approval`、またはホスト型 MCP の同等機能) を評価します。 -2. そのツール呼び出しに対する承認判断がすでに [`RunContextWrapper`][agents.run_context.RunContextWrapper] に保存されている場合、ランナーは確認なしで続行します。呼び出し単位の承認は特定の呼び出し ID にスコープされます。実行の残り期間における同ツールへの今後の呼び出しにも同じ判断を保持するには、`always_approve=True` または `always_reject=True` を渡します。 -3. それ以外の場合、実行は一時停止し、`RunResult.interruptions` (または `RunResultStreaming.interruptions`) に `agent.name`、`tool_name`、`arguments` などの詳細を含む [`ToolApprovalItem`][agents.items.ToolApprovalItem] エントリーが入ります。これには、ハンドオフ後またはネストされた `Agent.as_tool()` 実行内で発生した承認も含まれます。 -4. `result.to_state()` で結果を `RunState` に変換し、`state.approve(...)` または `state.reject(...)` を呼び出した後、`Runner.run(agent, state)` または `Runner.run_streamed(agent, state)` で再開します。ここで `agent` は、その実行の元のトップレベルエージェントです。 -5. 再開された実行は中断地点から継続し、新たな承認が必要であればこのフローに再度入ります。 +1. モデルがツール呼び出しを生成すると、ランナーはその承認ルール（`needs_approval`、`require_approval`、またはホスト型 MCP の同等設定）を評価します。 +2. そのツール呼び出しに対する承認判断がすでに [`RunContextWrapper`][agents.run_context.RunContextWrapper] に保存されている場合、ランナーはプロンプトを表示せずに続行します。呼び出しごとの承認は特定の呼び出し ID にスコープされます。実行の残りの期間におけるそのツールへの今後の呼び出しにも同じ判断を保持するには、`always_approve=True` または `always_reject=True` を渡します。 +3. それ以外の場合、実行は一時停止し、`RunResult.interruptions`（または `RunResultStreaming.interruptions`）に、`agent.name`、`tool_name`、`arguments` などの詳細を含む [`ToolApprovalItem`][agents.items.ToolApprovalItem] エントリが含まれます。これには、ハンドオフ後、またはネストされた `Agent.as_tool()` 実行内で要求された承認も含まれます。 +4. `result.to_state()` で実行結果を `RunState` に変換し、`state.approve(...)` または `state.reject(...)` を呼び出してから、`Runner.run(agent, state)` または `Runner.run_streamed(agent, state)` で再開します。ここで `agent` は、その実行の元のトップレベルエージェントです。 +5. 再開された実行は中断した箇所から続行し、新しい承認が必要になった場合はこのフローに再び入ります。 -`always_approve=True` または `always_reject=True` で作成された固定判断は実行状態に保存されるため、同じ一時停止済み実行を後で再開する際に `state.to_string()` / `RunState.from_string(...)` および `state.to_json()` / `RunState.from_json(...)` をまたいで保持されます。 +`always_approve=True` または `always_reject=True` で作成された固定的な判断は実行状態に保存されるため、後で同じ一時停止中の実行を再開する際に、`state.to_string()` / `RunState.from_string(...)` や `state.to_json()` / `RunState.from_json(...)` を経ても保持されます。 -同じパスで保留中の承認をすべて解決する必要はありません。`interruptions` には、通常の関数ツール、ホスト型 MCP 承認、ネストされた `Agent.as_tool()` 承認が混在する可能性があります。一部の項目のみ承認または拒否して再実行した場合、解決済みの呼び出しは継続し、未解決のものは `interruptions` に残って実行を再び一時停止します。 +同じパスで保留中の承認をすべて解決する必要はありません。`interruptions` には、通常の関数ツール、ホスト型 MCP 承認、ネストされた `Agent.as_tool()` 承認が混在する場合があります。一部の項目だけを承認または拒否してから再実行すると、解決済みの呼び出しは続行できますが、未解決のものは `interruptions` に残り、実行を再び一時停止します。 -## 拒否メッセージのカスタマイズ +## カスタム拒否メッセージ -デフォルトでは、拒否されたツール呼び出しは SDK の標準拒否テキストを実行に返します。このメッセージは 2 つのレイヤーでカスタマイズできます。 +デフォルトでは、拒否されたツール呼び出しは SDK の標準拒否テキストを実行内に返します。このメッセージは 2 つの層でカスタマイズできます。 -- 実行全体のフォールバック: [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter] を設定し、実行全体の承認拒否に対するモデル可視のデフォルトメッセージを制御します。 -- 呼び出し単位の上書き: 特定の拒否ツール呼び出しだけ別メッセージを表示したい場合、`state.reject(...)` に `rejection_message=...` を渡します。 +- 実行全体のフォールバック: 実行全体にわたる承認拒否について、モデルから見えるデフォルトメッセージを制御するには、[`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter] を設定します。 +- 呼び出しごとの上書き: 特定の拒否されたツール呼び出しで別のメッセージを表面化させたい場合は、`state.reject(...)` に `rejection_message=...` を渡します。 -両方が指定された場合、呼び出し単位の `rejection_message` が実行全体フォーマッターより優先されます。 +両方が指定された場合は、呼び出しごとの `rejection_message` が実行全体のフォーマッターより優先されます。 ```python from agents import RunConfig, ToolErrorFormatterArgs @@ -83,27 +83,27 @@ state.reject( ) ``` -両レイヤーを組み合わせて示す完全な例は [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py) を参照してください。 +両方の層を組み合わせて示す完全な例については、[`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py) を参照してください。 ## 自動承認判断 -手動 `interruptions` は最も汎用的なパターンですが、唯一ではありません。 +手動の `interruptions` は最も一般的なパターンですが、それだけではありません。 -- ローカル [`ShellTool`][agents.tool.ShellTool] と [`ApplyPatchTool`][agents.tool.ApplyPatchTool] は `on_approval` を使用してコード内で即時に承認または拒否できます。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] は、同種のプログラムによる判断のために `tool_config={"require_approval": "always"}` と `on_approval_request` を併用できます。 +- ローカルの [`ShellTool`][agents.tool.ShellTool] と [`ApplyPatchTool`][agents.tool.ApplyPatchTool] は、`on_approval` を使用してコード内で即座に承認または拒否できます。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] は、`tool_config={"require_approval": "always"}` と `on_approval_request` を組み合わせて使用することで、同じ種類のプログラムによる判断を行えます。 - 通常の [`function_tool`][agents.tool.function_tool] ツールと [`Agent.as_tool()`][agents.agent.Agent.as_tool] は、このページの手動中断フローを使用します。 -これらのコールバックが判断を返すと、実行は人の応答を待って一時停止せずに継続します。 Realtime および音声セッション API については、[Realtime ガイド](realtime/guide.md) の承認フローを参照してください。 +これらのコールバックが判断を返すと、実行は人間の応答を待って一時停止せずに続行します。Realtime と音声セッション API については、[Realtime ガイド](realtime/guide.md)の承認フローを参照してください。 ## ストリーミングとセッション -同じ中断フローはストリーミング実行でも機能します。ストリーミング実行が一時停止したら、イテレーターが終了するまで [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events] を消費し、[`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] を確認して解決し、再開後の出力もストリーミングを継続したい場合は [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] で再開します。このパターンのストリーミング版は [ストリーミング](streaming.md) を参照してください。 +同じ中断フローはストリーミング実行でも機能します。ストリーミング実行が一時停止した後は、イテレーターが終了するまで [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events] を消費し続け、[`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] を確認し、それらを解決して、再開後の出力もストリーミングし続けたい場合は [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] で再開します。このパターンのストリーミング版については、[ストリーミング](streaming.md)を参照してください。 -セッションも使用している場合は、`RunState` から再開する際に同じセッションインスタンスを渡し続けるか、同じバックエンドストアを指す別のセッションオブジェクトを渡してください。再開されたターンは同じ保存済み会話履歴に追加されます。セッションライフサイクルの詳細は [セッション](sessions/index.md) を参照してください。 +セッションも使用している場合は、`RunState` から再開するときに同じセッションインスタンスを渡し続けるか、同じバックエンドストアを指す別のセッションオブジェクトを渡します。これにより、再開されたターンは同じ保存済み会話履歴に追加されます。セッションのライフサイクルの詳細については、[セッション](sessions/index.md)を参照してください。 ## 例: 一時停止、承認、再開 -以下のスニペットは JavaScript の HITL ガイドを踏襲しています。ツールに承認が必要なときに一時停止し、状態をディスクに保存し、再読み込みして、判断を収集した後に再開します。 +以下のスニペットは JavaScript HITL ガイドに対応するものです。ツールが承認を必要とすると一時停止し、状態をディスクに永続化し、再読み込みして、判断を収集した後に再開します。 ```python import asyncio @@ -167,43 +167,42 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例では、`prompt_approval` は `input()` を使用し `run_in_executor(...)` で実行されるため同期的です。承認ソースがすでに非同期 ( 例: HTTP リクエストや非同期データベースクエリ) の場合は、`async def` 関数を使用して直接 `await` できます。 +この例では、`prompt_approval` は `input()` を使用し、`run_in_executor(...)` で実行されるため同期的です。承認元がすでに非同期である場合（たとえば、HTTP リクエストや async データベースクエリ）、代わりに `async def` 関数を使用して直接 `await` できます。 -承認待ち中にも出力をストリーミングしたい場合は、`Runner.run_streamed` を呼び出し、完了まで `result.stream_events()` を消費し、その後は上記と同じ `result.to_state()` と再開手順に従ってください。 +承認待ちの間に出力をストリーミングするには、`Runner.run_streamed` を呼び出し、完了するまで `result.stream_events()` を消費してから、上記と同じ `result.to_state()` と再開手順に従います。 -## リポジトリのパターンと例 +## リポジトリのパターンとコード例 -- **ストリーミング承認**: `examples/agent_patterns/human_in_the_loop_stream.py` は、`stream_events()` を最後まで処理し、保留中ツール呼び出しを承認してから `Runner.run_streamed(agent, state)` で再開する方法を示します。 -- **カスタム拒否テキスト**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py` は、承認が拒否されたときに実行レベルの `tool_error_formatter` と呼び出し単位の `rejection_message` 上書きを組み合わせる方法を示します。 -- **Agent as tool 承認**: `Agent.as_tool(..., needs_approval=...)` は、委譲されたエージェントタスクにレビューが必要な場合にも同じ中断フローを適用します。ネストされた中断も外側の実行に表示されるため、ネスト側ではなく元のトップレベルエージェントを再開してください。 -- **ローカル shell / apply_patch ツール**: `ShellTool` と `ApplyPatchTool` も `needs_approval` をサポートします。将来の呼び出しのために判断をキャッシュするには `state.approve(interruption, always_approve=True)` または `state.reject(..., always_reject=True)` を使用します。自動判断には `on_approval` を指定します ( `examples/tools/shell.py` を参照)。手動判断には中断を処理します ( `examples/tools/shell_human_in_the_loop.py` を参照)。ホスト型 shell 環境は `needs_approval` または `on_approval` をサポートしません。[ツールガイド](tools.md) を参照してください。 -- **ローカル MCP サーバー**: `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` で `require_approval` を使用し、MCP ツール呼び出しを制御します ( `examples/mcp/get_all_mcp_tools_example/main.py` および `examples/mcp/tool_filter_example/main.py` を参照)。 -- **ホスト型 MCP サーバー**: HITL を強制するには `HostedMCPTool` で `require_approval` を `"always"` に設定し、必要に応じて `on_approval_request` を指定して自動承認または拒否します ( `examples/hosted_mcp/human_in_the_loop.py` および `examples/hosted_mcp/on_approval.py` を参照)。信頼済みサーバーには `"never"` を使用します (`examples/hosted_mcp/simple.py`)。 -- **セッションとメモリ**: 複数ターンにわたり承認と会話履歴を保持するには `Runner.run` にセッションを渡します。 SQLite および OpenAI Conversations セッションのバリアントは `examples/memory/memory_session_hitl_example.py` と `examples/memory/openai_session_hitl_example.py` にあります。 -- **Realtime エージェント**: realtime デモは `RealtimeSession` の `approve_tool_call` / `reject_tool_call` を介してツール呼び出しを承認または拒否する WebSocket メッセージを公開します ( サーバー側ハンドラーは `examples/realtime/app/server.py`、API サーフェスは [Realtime ガイド](realtime/guide.md#tool-approvals) を参照)。 +- **ストリーミング承認**: `examples/agent_patterns/human_in_the_loop_stream.py` は、`stream_events()` を最後まで消費し、その後に保留中のツール呼び出しを承認してから `Runner.run_streamed(agent, state)` で再開する方法を示しています。 +- **カスタム拒否テキスト**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py` は、承認が拒否されたときに、実行レベルの `tool_error_formatter` と呼び出しごとの `rejection_message` 上書きを組み合わせる方法を示しています。 +- **ツールとしてのエージェントの承認**: `Agent.as_tool(..., needs_approval=...)` は、委任されたエージェントタスクにレビューが必要な場合に、同じ中断フローを適用します。ネストされた中断も外側の実行に表面化するため、ネストされたエージェントではなく、元のトップレベルエージェントを再開します。 +- **ローカルシェルと apply_patch ツール**: `ShellTool` と `ApplyPatchTool` も `needs_approval` をサポートします。今後の呼び出しに対して判断をキャッシュするには、`state.approve(interruption, always_approve=True)` または `state.reject(..., always_reject=True)` を使用します。自動判断には `on_approval` を指定します（`examples/tools/shell.py` を参照）。手動判断には中断を処理します（`examples/tools/shell_human_in_the_loop.py` を参照）。ホスト型シェル環境は `needs_approval` または `on_approval` をサポートしていません。[ツールガイド](tools.md)を参照してください。 +- **ローカル MCP サーバー**: MCP ツール呼び出しを制御するには、`MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` で `require_approval` を使用します（`examples/mcp/get_all_mcp_tools_example/main.py` と `examples/mcp/tool_filter_example/main.py` を参照）。 +- **ホスト型 MCP サーバー**: HITL を強制するには、`HostedMCPTool` で `require_approval` を `"always"` に設定し、必要に応じて自動承認または拒否のために `on_approval_request` を指定します（`examples/hosted_mcp/human_in_the_loop.py` と `examples/hosted_mcp/on_approval.py` を参照）。信頼できるサーバーには `"never"` を使用します（`examples/hosted_mcp/simple.py`）。 +- **セッションとメモリ**: 承認と会話履歴が複数ターンにわたって保持されるように、`Runner.run` にセッションを渡します。SQLite と OpenAI Conversations セッションのバリエーションは、`examples/memory/memory_session_hitl_example.py` と `examples/memory/openai_session_hitl_example.py` にあります。 +- **Realtime エージェント**: Realtime デモは、`RealtimeSession` 上の `approve_tool_call` / `reject_tool_call` を介してツール呼び出しを承認または拒否する WebSocket メッセージを公開しています（サーバー側ハンドラーについては `examples/realtime/app/server.py`、API サーフェスについては [Realtime ガイド](realtime/guide.md#tool-approvals)を参照）。 -## 長時間実行承認 +## 長時間にわたる承認 -`RunState` は永続性を考慮して設計されています。保留中作業をデータベースやキューに保存するには `state.to_json()` または `state.to_string()` を使用し、後で `RunState.from_json(...)` または `RunState.from_string(...)` で再作成します。 +`RunState` は耐久性を持つように設計されています。保留中の作業をデータベースまたはキューに保存するには `state.to_json()` または `state.to_string()` を使用し、後で `RunState.from_json(...)` または `RunState.from_string(...)` で再作成します。 有用なシリアライズオプション: -- `context_serializer`: マッピング以外のコンテキストオブジェクトをどのようにシリアライズするかをカスタマイズします。 -- `context_deserializer`: `RunState.from_json(...)` または `RunState.from_string(...)` で状態をロードするときに、マッピング以外のコンテキストオブジェクトを再構築します。 +- `context_serializer`: 非マッピングのコンテキストオブジェクトをシリアライズする方法をカスタマイズします。 +- `context_deserializer`: `RunState.from_json(...)` または `RunState.from_string(...)` で状態を読み込むときに、非マッピングのコンテキストオブジェクトを再構築します。 - `strict_context=True`: コンテキストがすでに - マッピングであるか、適切な serializer / deserializer を提供しない限り、シリアライズまたはデシリアライズを失敗させます。 -- `context_override`: 状態ロード時にシリアライズ済みコンテキストを置き換えます。これは - 元のコンテキストオブジェクトを復元したくない場合に有用ですが、すでに - シリアライズ済みペイロードからそのコンテキストを削除するものではありません。 -- `include_tracing_api_key=True`: 再開作業でも同じ認証情報でトレースをエクスポートし続ける必要がある場合に、 - シリアライズされたトレースペイロードに tracing API キーを含めます。 - -シリアライズされた実行状態には、アプリコンテキストに加えて、承認、 -使用量、シリアライズされた `tool_input`、ネストされた agent-as-tool 再開、トレースメタデータ、サーバー管理の -会話設定など、SDK 管理の実行時メタデータが含まれます。シリアライズ状態を保存または転送する予定がある場合は、 -`RunContextWrapper.context` を永続化データとして扱い、意図的に -状態と一緒に移動させたい場合を除き、そこに秘密情報を置かないでください。 - -## 保留タスクのバージョニング - -承認がしばらく保留される可能性がある場合は、シリアライズ状態と一緒にエージェント定義または SDK のバージョンマーカーを保存してください。これにより、デシリアライズを対応するコードパスに振り分け、モデル、プロンプト、またはツール定義が変更された際の非互換性を回避できます。 \ No newline at end of file + マッピングであるか、適切なシリアライザー/デシリアライザーを指定している場合を除き、シリアライズまたはデシリアライズを失敗させます。 +- `context_override`: 状態を読み込むときに、シリアライズされたコンテキストを置き換えます。これは、元のコンテキストオブジェクトを復元したくない場合に便利ですが、 + すでにシリアライズされたペイロードからそのコンテキストを削除するわけではありません。 +- `include_tracing_api_key=True`: 同じ認証情報でトレースのエクスポートを継続するために再開後の作業で必要な場合、 + シリアライズされたトレースペイロードにトレーシング API キーを含めます。 + +シリアライズされた実行状態には、アプリのコンテキストに加えて、承認、 +使用量、シリアライズされた `tool_input`、ネストされた agent-as-tool の再開、トレースメタデータ、サーバー管理の +会話設定など、SDK が管理するランタイムメタデータが含まれます。シリアライズされた状態を保存または送信する予定がある場合は、 +`RunContextWrapper.context` を永続化データとして扱い、状態と一緒に移動することを意図している場合を除き、 +そこにシークレットを置かないでください。 + +## 保留中タスクのバージョニング + +承認がしばらく保留状態のままになる可能性がある場合は、シリアライズされた状態と一緒に、エージェント定義または SDK のバージョンマーカーを保存してください。そうすれば、モデル、プロンプト、ツール定義が変更されたときの非互換性を避けるために、デシリアライズを対応するコードパスにルーティングできます。 \ No newline at end of file diff --git a/docs/ja/index.md b/docs/ja/index.md index 0e5eae93aa..fb10c680f0 100644 --- a/docs/ja/index.md +++ b/docs/ja/index.md @@ -4,51 +4,51 @@ 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 です -- **Agents as tools / ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任できるようにします -- **ガードレール**: エージェントの入力と出力を検証できます +- **エージェント**: 指示とツールを備えた LLM です +- **Agents as tools / ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任できるようにします +- **ガードレール**: エージェントの入力と出力の検証を可能にします -Python と組み合わせることで、これらの基本コンポーネントはツールとエージェントの複雑な関係を表現するのに十分強力であり、急な学習曲線なしに実世界のアプリケーションを構築できます。さらに SDK には組み込みの **トレーシング** が含まれており、エージェント型フローを可視化してデバッグできるだけでなく、それらを評価し、アプリケーション向けにモデルをファインチューニングすることもできます。 +Python と組み合わせることで、これらの基本コンポーネントは、ツールとエージェント間の複雑な関係を表現するのに十分強力であり、習得のハードルを高くすることなく実世界のアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が含まれており、エージェント型フローの可視化とデバッグ、評価、さらにはアプリケーション向けのモデルのファインチューニングも可能です。 -## Agents SDK を使用する理由 +## Agents SDK の利用理由 -SDK には 2 つの主要な設計原則があります。 +SDK の設計を支える原則は 2 つあります: -1. 使う価値があるだけの十分な機能を備えつつ、すばやく学習できるだけ基本コンポーネントを少なくすること。 -2. そのままでも非常にうまく動作しつつ、何が起こるかを正確にカスタマイズできること。 +1. 使用する価値がある十分な機能を備えつつ、すばやく学べるだけの少数の基本コンポーネントに抑えること。 +2. そのままでも優れた動作をしつつ、何が起こるかを正確にカスタマイズできること。 -SDK の主な機能は次のとおりです。 +SDK の主な機能は次のとおりです: -- **エージェントループ**: ツールの呼び出しを処理し、実行結果を LLM に返し、タスクが完了するまで継続する組み込みのエージェントループです。 -- **Python ファースト**: 新しい抽象化を学ぶ必要なく、組み込みの言語機能を使ってエージェントをオーケストレーションし、連鎖させます。 -- **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整し委任するための強力な仕組みです。 -- **サンドボックスエージェント**: マニフェストで定義されたファイル、サンドボックスクライアントの選択、再開可能なサンドボックスセッションを備えた、実際に分離されたワークスペース内で専門エージェントを実行します。 -- **ガードレール**: エージェント実行と並行して入力検証と安全性チェックを実行し、チェックに合格しない場合は早期に失敗させます。 -- **関数ツール**: 任意の Python 関数を、自動スキーマ生成と Pydantic による検証付きのツールに変換します。 -- **MCP サーバーツール呼び出し**: 関数ツールと同じ方法で動作する、組み込みの MCP サーバーツール統合です。 -- **セッション**: エージェントループ内で作業コンテキストを維持するための永続的なメモリレイヤーです。 -- **Human in the loop**: エージェント実行全体で人間を関与させるための組み込みの仕組みです。 -- **トレーシング**: ワークフローの可視化、デバッグ、監視のための組み込みトレーシングで、OpenAI の評価、ファインチューニング、蒸留ツール群をサポートします。 -- **Realtime Agents**: `gpt-realtime-2`、自動割り込み検出、コンテキスト管理、ガードレールなどを使って強力な音声エージェントを構築します。 +- **エージェントループ**: ツール呼び出しを処理し、結果を LLM に送り返し、タスクが完了するまで継続する組み込みのエージェントループです。 +- **Python ファースト**: 新しい抽象化を学ぶ必要なく、組み込みの言語機能を使ってエージェントをオーケストレーションし、連鎖させます。 +- **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整し、委任するための強力な仕組みです。 +- **Sandbox エージェント**: マニフェストで定義されたファイル、Sandbox クライアントの選択、再開可能なサンドボックスセッションを備えた、実際の隔離ワークスペース内で専門エージェントを実行します。 +- **ガードレール**: エージェント実行と並行して入力検証と安全性チェックを実行し、チェックに通らない場合は即座に失敗として終了します。 +- **関数ツール**: スキーマの自動生成と Pydantic によるバリデーションにより、任意の Python 関数をツールに変換します。 +- **MCP サーバーのツール呼び出し**: 関数ツールと同じように動作する、組み込みの MCP サーバーツール統合です。 +- **セッション**: エージェントループ内で作業コンテキストを維持するための永続的なメモリレイヤーです。 +- **ヒューマンインザループ**: エージェント実行の各所に人間を関与させるための組み込みの仕組みです。 +- **トレーシング**: ワークフローを可視化、デバッグ、監視するための組み込みのトレーシングで、OpenAI の評価、ファインチューニング、蒸留ツール群をサポートします。 +- **Realtime エージェント**: `gpt-realtime-2` を使い、自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築します。 -## Agents SDK または Responses API +## Agents SDK と Responses API の選択 -SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、モデル呼び出しの周辺により高レベルのランタイムを追加します。 +SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、モデル呼び出しの周りに高レベルのランタイムを追加します。 -次の場合は Responses API を直接使用します。 +次の場合は Responses API を直接使用します: -- ループ、ツールのディスパッチ、状態処理を自分で管理したい場合 -- ワークフローが短時間で完了し、主にモデルの応答を返すことが目的の場合 +- ループ、ツールのディスパッチ、状態処理を自分で管理したい場合 +- ワークフローが短期間で、主にモデルの応答を返すことが目的の場合 -次の場合は Agents SDK を使用します。 +次の場合は Agents SDK を使用します: -- ターン、ツール実行、ガードレール、ハンドオフ、またはセッションをランタイムに管理させたい場合 -- エージェントが成果物を生成する、または複数の協調されたステップにわたって動作する必要がある場合 -- [サンドボックスエージェント](sandbox_agents.md) を通じて、実際のワークスペースまたは再開可能な実行が必要な場合 +- ランタイムにターン、ツール実行、ガードレール、ハンドオフ、またはセッションを管理させたい場合 +- エージェントが成果物を生成する、または複数の協調したステップにわたって動作する必要がある場合 +- 実際のワークスペース、または [Sandbox エージェント](sandbox_agents.md) による再開可能な実行が必要な場合 -どちらか一方を全体で選ぶ必要はありません。多くのアプリケーションでは、管理されたワークフローに SDK を使用し、低レベルの経路には Responses API を直接呼び出します。 +アプリケーション全体でどちらか一方を選ぶ必要はありません。多くのアプリケーションでは、管理されたワークフローには SDK を使用し、低レベルの処理経路では Responses API を直接呼び出します。 ## インストール @@ -56,7 +56,7 @@ SDK は OpenAI モデルに対してデフォルトで Responses API を使用 pip install openai-agents ``` -## Hello World の例 +## Hello world の例 ```python from agents import Agent, Runner @@ -71,31 +71,31 @@ print(result.final_output) # Infinite loop's dance. ``` -（_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定していることを確認してください_） +(_これを実行する場合は、 `OPENAI_API_KEY` 環境変数を設定していることを確認してください_) ```bash export OPENAI_API_KEY=sk-... ``` -## はじめに +## 開始ポイント -- [クイックスタート](quickstart.md)で、最初のテキストベースのエージェントを構築します。 -- 次に、[エージェントの実行](running_agents.md#choose-a-memory-strategy)で、ターンをまたいで状態をどのように引き継ぐかを決定します。 -- タスクが実際のファイル、リポジトリ、またはエージェントごとに分離されたワークスペース状態に依存する場合は、[サンドボックスエージェントのクイックスタート](sandbox_agents.md)を読んでください。 -- ハンドオフとマネージャースタイルのオーケストレーションのどちらを選ぶか検討している場合は、[エージェントオーケストレーション](multi_agent.md)を読んでください。 +- [クイックスタート](quickstart.md) で、最初のテキストベースのエージェントを構築します。 +- 次に、[エージェントの実行](running_agents.md#choose-a-memory-strategy) で、ターン間で状態をどのように引き継ぐかを決定します。 +- タスクが実際のファイル、リポジトリ、またはエージェントごとに隔離されたワークスペース状態に依存する場合は、[Sandbox エージェントのクイックスタート](sandbox_agents.md) を参照してください。 +- ハンドオフとマネージャースタイルのオーケストレーションのどちらにするかを決める場合は、[エージェントオーケストレーション](multi_agent.md) を参照してください。 ## パスの選択 -実行したい作業はわかっているものの、どのページで説明されているかわからない場合は、この表を使用してください。 +実行したい作業は分かっているものの、どのページで説明されているか分からない場合は、この表を使用してください。 -| 目的 | ここから開始 | +| 目的 | 参照先 | | --- | --- | | 最初のテキストエージェントを構築し、完全な 1 回の実行を確認する | [クイックスタート](quickstart.md) | -| 関数ツール、ホスト型ツール、または Agents as tools を追加する | [ツール](tools.md) | -| 実際に分離されたワークスペース内で、コーディング、レビュー、またはドキュメントエージェントを実行する | [サンドボックスエージェントのクイックスタート](sandbox_agents.md) と [サンドボックスクライアント](sandbox/clients.md) | -| ハンドオフとマネージャースタイルのオーケストレーションのどちらにするか決定する | [エージェントオーケストレーション](multi_agent.md) | -| ターンをまたいでメモリを保持する | [エージェントの実行](running_agents.md#choose-a-memory-strategy) と [セッション](sessions/index.md) | +| 関数ツール、OpenAI がホストするツール、または agents as tools を追加する | [ツール](tools.md) | +| 実際の隔離ワークスペース内で、コーディング、レビュー、またはドキュメント処理のエージェントを実行する | [Sandbox エージェントのクイックスタート](sandbox_agents.md) and [Sandbox クライアント](sandbox/clients.md) | +| ハンドオフとマネージャースタイルのオーケストレーションのどちらを使うか決める | [エージェントオーケストレーション](multi_agent.md) | +| ターン間でメモリを保持する | [エージェントの実行](running_agents.md#choose-a-memory-strategy) and [セッション](sessions/index.md) | | OpenAI モデル、WebSocket トランスポート、または OpenAI 以外のプロバイダーを使用する | [モデル](models/index.md) | -| 出力、実行項目、割り込み、再開状態を確認する | [実行結果](results.md) | -| `gpt-realtime-2` を使って低レイテンシの音声エージェントを構築する | [Realtime エージェントのクイックスタート](realtime/quickstart.md) と [Realtime トランスポート](realtime/transport.md) | -| 音声テキスト変換 / エージェント / テキスト音声変換のパイプラインを構築する | [音声パイプラインのクイックスタート](voice/quickstart.md) | \ No newline at end of file +| 出力、実行アイテム、割り込み、再開状態を確認する | [実行結果](results.md) | +| `gpt-realtime-2` を使って低レイテンシの音声エージェントを構築する | [Realtime エージェントのクイックスタート](realtime/quickstart.md) and [Realtime トランスポート](realtime/transport.md) | +| 音声認識 / エージェント / 音声合成のパイプラインを構築する | [音声パイプラインのクイックスタート](voice/quickstart.md) | \ No newline at end of file diff --git a/docs/ja/mcp.md b/docs/ja/mcp.md index b077db8fc8..cc93cc2f8b 100644 --- a/docs/ja/mcp.md +++ b/docs/ja/mcp.md @@ -4,30 +4,33 @@ 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 モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。 +> アプリケーションのための USB-C ポートのようなものだと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同じように、MCP +> は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。 -Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、ファイルシステム、HTTP、またはコネクターに基づくツールをエージェントに公開するために独自に構築したりできます。 +Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、独自に構築して +ファイルシステム、HTTP、またはコネクターを基盤とするツールをエージェントに公開できます。 -## MCP 連携の選択 +## MCP 統合の選択 -MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行すべきか、どのトランスポートに到達できるかを決定します。以下の表は、Python SDK がサポートするオプションをまとめたものです。 +MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決定してください。 +以下の表は、Python SDK がサポートする選択肢をまとめたものです。 | 必要なこと | 推奨オプション | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| OpenAI の Responses API が、モデルに代わって公開到達可能な MCP サーバーを呼び出せるようにする| [`HostedMCPTool`][agents.tool.HostedMCPTool] 経由の **Hosted MCP server tools** | -| ローカルまたはリモートで実行している Streamable HTTP サーバーに接続する | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 経由の **Streamable HTTP MCP servers** | -| Server-Sent Events を使用した HTTP を実装するサーバーと通信する | [`MCPServerSse`][agents.mcp.server.MCPServerSse] 経由の **HTTP with SSE MCP servers** | -| ローカルプロセスを起動し、stdin/stdout 経由で通信する | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 経由の **stdio MCP servers** | +| OpenAI の Responses API に、モデルの代理で公開到達可能な MCP サーバーを呼び出させる| [`HostedMCPTool`][agents.tool.HostedMCPTool] 経由の **ホスト型 MCP サーバーツール** | +| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 経由の **Streamable HTTP MCP サーバー** | +| Server-Sent Events を用いた HTTP を実装しているサーバーと通信する | [`MCPServerSse`][agents.mcp.server.MCPServerSse] 経由の **SSE 付き HTTP MCP サーバー** | +| ローカルプロセスを起動し、stdin/stdout 経由で通信する | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 経由の **stdio MCP サーバー** | -以下のセクションでは、各オプション、設定方法、あるトランスポートを別のものより優先すべき場合について説明します。 +以下のセクションでは、各オプション、設定方法、あるトランスポートを別のトランスポートより優先すべき場合について説明します。 ## エージェントレベルの MCP 設定 -トランスポートの選択に加えて、`Agent.mcp_config` を設定することで MCP ツールの準備方法を調整できます。 +トランスポートの選択に加えて、`Agent.mcp_config` を設定することで、MCP ツールの準備方法を調整できます。 ```python from agents import Agent @@ -53,27 +56,30 @@ agent = Agent( - `failure_error_function` は、MCP ツール呼び出しの失敗をモデルにどのように提示するかを制御します。 - `failure_error_function` が未設定の場合、SDK はデフォルトのツールエラーフォーマッターを使用します。 - サーバーレベルの `failure_error_function` は、そのサーバーについて `Agent.mcp_config["failure_error_function"]` を上書きします。 -- `include_server_in_tool_names` はオプトインです。有効にすると、各ローカル MCP ツールは決定的なサーバー接頭辞付きの名前でモデルに公開されます。これにより、複数の MCP サーバーが同じ名前のツールを公開している場合の衝突を避けやすくなります。生成される名前は ASCII セーフで、関数ツール名の長さ制限内に収まり、同じエージェント上の既存のローカル関数ツール名や有効なハンドオフ名を避けます。SDK は引き続き、元のサーバー上で元の MCP ツール名を呼び出します。 +- `include_server_in_tool_names` はオプトインです。有効にすると、各ローカル MCP ツールは、決定的なサーバープレフィックス付きの名前でモデルに公開されます。これにより、複数の MCP サーバーが同じ名前のツールを公開している場合の衝突を避けやすくなります。生成される名前は ASCII セーフで、関数ツール名の長さ制限内に収まり、同じエージェント上の既存のローカル関数ツール名と有効なハンドオフ名を避けます。SDK は引き続き、元のサーバー上で元の MCP ツール名を呼び出します。 ## トランスポート間で共通するパターン -トランスポートを選択した後、多くの連携では同じ追加判断が必要になります。 +トランスポートを選択した後、多くの統合では同じような追加判断が必要です。 -- ツールの一部だけを公開する方法（[ツールフィルタリング](#tool-filtering)）。 +- ツールのサブセットのみを公開する方法（[ツールフィルタリング](#tool-filtering)）。 - サーバーが再利用可能なプロンプトも提供するかどうか（[プロンプト](#prompts)）。 - `list_tools()` をキャッシュすべきかどうか（[キャッシュ](#caching)）。 - MCP アクティビティがトレースにどのように表示されるか（[トレーシング](#tracing)）。 -ローカル MCP サーバー（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`）では、承認ポリシーと呼び出しごとの `_meta` ペイロードも共通概念です。Streamable HTTP セクションでは最も完全な例を示しており、同じパターンは他のローカルトランスポートにも適用されます。 +ローカル MCP サーバー（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`）では、承認ポリシーと呼び出しごとの `_meta` ペイロードも共通の概念です。Streamable HTTP セクションでは最も完全な例を示しており、同じパターンは他のローカルトランスポートにも適用できます。 -## 1. Hosted MCP server tools +## 1. ホスト型 MCP サーバーツール -ホスト型ツールは、ツールの往復全体を OpenAI のインフラストラクチャに移します。コードがツールを一覧表示して呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] がサーバーラベル（および任意のコネクターメタデータ）を Responses API に転送します。モデルは、Python プロセスへの追加コールバックなしでリモートサーバーのツールを一覧表示し、それらを呼び出します。ホスト型ツールは現在、Responses API のホスト型 MCP 連携をサポートする OpenAI モデルで動作します。 +ホスト型ツールでは、ツールの往復処理全体を OpenAI のインフラストラクチャに委ねます。コードでツールを一覧表示して呼び出す代わりに、 +[`HostedMCPTool`][agents.tool.HostedMCPTool] がサーバーラベル（および任意のコネクターメタデータ）を Responses API に転送します。 +モデルはリモートサーバーのツールを一覧表示し、Python プロセスへの追加のコールバックなしでそれらを呼び出します。ホスト型ツールは現在、 +Responses API のホスト型 MCP 統合をサポートする OpenAI モデルで動作します。 -### 基本的な hosted MCP ツール +### 基本的なホスト型 MCP ツール -エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して、ホスト型ツールを作成します。`tool_config` -dict は、REST API に送信する JSON を反映します。 +[`HostedMCPTool`][agents.tool.HostedMCPTool] をエージェントの `tools` リストに追加して、ホスト型ツールを作成します。`tool_config` +dict は、REST API に送信する JSON と同じ構造です。 ```python import asyncio @@ -107,11 +113,12 @@ asyncio.run(main()) ホスト型サーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。 -ホスト型ツール検索でホスト型 MCP サーバーを遅延読み込みしたい場合は、`tool_config["defer_loading"] = True` を設定し、[`ToolSearchTool`][agents.tool.ToolSearchTool] をエージェントに追加します。これは OpenAI Responses モデルでのみサポートされます。完全なツール検索の設定と制約については、[ツール](tools.md#hosted-tool-search) を参照してください。 +ホスト型ツール検索でホスト型 MCP サーバーを遅延読み込みしたい場合は、`tool_config["defer_loading"] = True` を設定し、[`ToolSearchTool`][agents.tool.ToolSearchTool] をエージェントに追加します。これは OpenAI Responses モデルでのみサポートされます。ツール検索の完全な設定と制約については、[ツール](tools.md#hosted-tool-search)を参照してください。 -### hosted MCP 実行結果のストリーミング +### ホスト型 MCP 実行結果のストリーミング -ホスト型ツールは、関数ツールとまったく同じ方法で実行結果のストリーミングをサポートします。モデルがまだ動作している間に増分 MCP 出力を消費するには、`Runner.run_streamed` を使用します。 +ホスト型ツールは、関数ツールとまったく同じ方法で実行結果のストリーミングをサポートします。`Runner.run_streamed` を使用して、 +モデルがまだ動作している間に、増分 MCP 出力を受け取ります。 ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -123,7 +130,9 @@ 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 @@ -151,11 +160,12 @@ agent = Agent( ) ``` -コールバックは同期または非同期にでき、モデルが実行を継続するために承認データを必要とするたびに呼び出されます。 +コールバックは同期または非同期にでき、モデルが実行を続けるために承認データを必要とするたびに呼び出されます。 -### コネクターに基づく hosted サーバー +### コネクター対応のホスト型サーバー -ホスト型 MCP は OpenAI コネクターもサポートします。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。Responses API が認証を処理し、ホスト型サーバーがコネクターのツールを公開します。 +ホスト型 MCP は OpenAI コネクターもサポートしています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。 +Responses API が認証を処理し、ホスト型サーバーがコネクターのツールを公開します。 ```python import os @@ -171,12 +181,14 @@ HostedMCPTool( ) ``` -ストリーミング、承認、コネクターを含む、完全に動作するホスト型ツールのサンプルは +ストリーミング、承認、コネクターを含む、完全に動作するホスト型ツールサンプルは、 [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) にあります。 -## 2. Streamable HTTP MCP servers +## 2. Streamable HTTP MCP サーバー -ネットワーク接続を自分で管理したい場合は、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御する場合や、低レイテンシを維持しながら自分のインフラストラクチャ内でサーバーを実行したい場合に最適です。 +ネットワーク接続を自分で管理したい場合は、 +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御する場合や、 +レイテンシーを低く保ちながら自分のインフラストラクチャ内でサーバーを実行したい場合に最適です。 ```python import asyncio @@ -211,19 +223,19 @@ 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) を参照）。 -- `require_approval` は、ローカル MCP ツールに対して human-in-the-loop の承認ポリシーを有効にします。 +- `use_structured_content` は、テキスト出力より `tool_result.structured_content` を優先するかどうかを切り替えます。 +- `max_retry_attempts` と `retry_backoff_seconds_base` は、`list_tools()` と `call_tool()` に自動再試行を追加します。 +- `tool_filter` により、ツールのサブセットのみを公開できます（[ツールフィルタリング](#tool-filtering)を参照）。 +- `require_approval` は、ローカル MCP ツールで人間参加型の承認ポリシーを有効にします。 - `failure_error_function` は、モデルに見える MCP ツール失敗メッセージをカスタマイズします。代わりにエラーを発生させるには、`None` に設定します。 - `tool_meta_resolver` は、`call_tool()` の前に呼び出しごとの MCP `_meta` ペイロードを注入します。 ### ローカル MCP サーバーの承認ポリシー -`MCPServerStdio`、`MCPServerSse`、および `MCPServerStreamableHttp` はすべて `require_approval` を受け取ります。 +`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp` はすべて `require_approval` を受け付けます。 サポートされる形式: @@ -242,11 +254,11 @@ async with MCPServerStreamableHttp( ... ``` -完全な一時停止/再開フローについては、[Human-in-the-loop](human_in_the_loop.md) と `examples/mcp/get_all_mcp_tools_example/main.py` を参照してください。 +完全な一時停止/再開フローについては、[人間参加型](human_in_the_loop.md)および `examples/mcp/get_all_mcp_tools_example/main.py` を参照してください。 ### `tool_meta_resolver` による呼び出しごとのメタデータ -MCP サーバーが `_meta` にリクエストメタデータ（たとえばテナント ID やトレースコンテキスト）を期待する場合は、`tool_meta_resolver` を使用します。以下の例では、`Runner.run(...)` に `context` として `dict` を渡すことを想定しています。 +MCP サーバーが `_meta` 内にリクエストメタデータ（たとえば、テナント ID やトレースコンテキスト）を想定している場合は、`tool_meta_resolver` を使用します。以下の例では、`Runner.run(...)` に `context` として `dict` を渡すことを想定しています。 ```python from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext @@ -267,19 +279,20 @@ server = MCPServerStreamableHttp( ) ``` -実行コンテキストが Pydantic モデル、dataclass、またはカスタムクラスの場合は、代わりに属性アクセスでテナント ID を読み取ります。 +実行コンテキストが Pydantic モデル、dataclass、またはカスタムクラスの場合は、属性アクセスでテナント ID を読み取ってください。 ### MCP ツール出力: テキストと画像 -MCP ツールが画像コンテンツを返す場合、SDK はそれを画像ツール出力エントリに自動的にマッピングします。テキストと画像が混在したレスポンスは、出力項目のリストとして転送されるため、エージェントは通常の関数ツールからの画像出力を消費するのと同じ方法で MCP 画像実行結果を消費できます。 +MCP ツールが画像コンテンツを返すと、SDK はそれを画像ツール出力エントリーに自動的にマッピングします。テキスト/画像が混在するレスポンスは出力項目のリストとして転送されるため、エージェントは通常の関数ツールからの画像出力を利用するのと同じ方法で MCP 画像実行結果を利用できます。 -## 3. HTTP with SSE MCP servers +## 3. SSE 付き HTTP MCP サーバー !!! warning - MCP プロジェクトは Server-Sent Events トランスポートを非推奨にしました。新しい連携では Streamable HTTP または stdio を優先し、SSE はレガシーサーバーにのみ維持してください。 + MCP プロジェクトでは Server-Sent Events トランスポートが非推奨になりました。新しい統合には Streamable HTTP または stdio を優先し、SSE はレガシーサーバー向けにのみ維持してください。 -MCP サーバーが HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポートを除けば、API は Streamable HTTP サーバーと同一です。 +MCP サーバーが SSE 付き HTTP トランスポートを実装している場合は、 +[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポートを除けば、API は Streamable HTTP サーバーと同一です。 ```python @@ -306,9 +319,11 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP servers +## 4. stdio MCP サーバー -ローカルサブプロセスとして実行される MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK はプロセスを起動し、パイプを開いたままにし、コンテキストマネージャーが終了すると自動的に閉じます。このオプションは、簡単な概念実証や、サーバーがコマンドラインエントリーポイントのみを公開している場合に役立ちます。 +ローカルサブプロセスとして実行される MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK は +プロセスを起動し、パイプを開いたままにし、コンテキストマネージャーを抜けると自動的に閉じます。このオプションは、素早い概念実証や、 +サーバーがコマンドラインエントリーポイントのみを公開している場合に役立ちます。 ```python from pathlib import Path @@ -336,7 +351,8 @@ async with MCPServerStdio( ## 5. MCP サーバーマネージャー -複数の MCP サーバーがある場合は、`MCPServerManager` を使用して事前に接続し、接続済みのサブセットをエージェントに公開します。コンストラクターオプションと再接続の動作については、[MCPServerManager API リファレンス](ref/mcp/manager.md) を参照してください。 +複数の MCP サーバーがある場合は、`MCPServerManager` を使用して事前に接続し、接続済みのサブセットをエージェントに公開します。 +コンストラクターオプションと再接続の動作については、[MCPServerManager API リファレンス](ref/mcp/manager.md)を参照してください。 ```python from agents import Agent, Runner @@ -362,16 +378,17 @@ async with MCPServerManager(servers) as manager: - `active_servers` には、`drop_failed_servers=True`（デフォルト）の場合、正常に接続されたサーバーのみが含まれます。 - 失敗は `failed_servers` と `errors` で追跡されます。 - 最初の接続失敗で例外を発生させるには、`strict=True` を設定します。 -- 失敗したサーバーを再試行するには `reconnect(failed_only=True)` を、すべてのサーバーを再起動するには `reconnect(failed_only=False)` を呼び出します。 -- ライフサイクル動作を調整するには、`connect_timeout_seconds`、`cleanup_timeout_seconds`、および `connect_in_parallel` を使用します。 +- 失敗したサーバーを再試行するには `reconnect(failed_only=True)` を呼び出し、すべてのサーバーを再起動するには `reconnect(failed_only=False)` を呼び出します。 +- ライフサイクルの動作を調整するには、`connect_timeout_seconds`、`cleanup_timeout_seconds`、`connect_in_parallel` を使用します。 ## 共通のサーバー機能 -以下のセクションは、MCP サーバートランスポート全体に適用されます（正確な API サーフェスはサーバークラスに依存します）。 +以下のセクションは、MCP サーバートランスポート全体に適用されます（正確な API サーフェスはサーバークラスによって異なります）。 ## ツールフィルタリング -各 MCP サーバーはツールフィルターをサポートしているため、エージェントが必要とする関数だけを公開できます。フィルタリングは構築時、または実行ごとに動的に行えます。 +各 MCP サーバーはツールフィルターをサポートしているため、エージェントに必要な関数だけを公開できます。フィルタリングは、 +構築時にも実行ごとに動的にも行えます。 ### 静的ツールフィルタリング @@ -393,11 +410,13 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後、残りのセットからブロックされたツールを削除します。 +`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後、残ったセットから +ブロックされたツールを削除します。 ### 動的ツールフィルタリング -より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る callable を渡します。callable は同期または非同期にでき、ツールを公開すべき場合に `True` を返します。 +より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。呼び出し可能オブジェクトは +同期または非同期にでき、ツールを公開すべき場合に `True` を返します。 ```python from pathlib import Path @@ -425,10 +444,11 @@ async with MCPServerStdio( ## プロンプト -MCP サーバーは、エージェントの instructions を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、2 つのメソッドを公開します。 +MCP サーバーは、エージェントの指示を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 つの +メソッドを公開します。 - `list_prompts()` は、利用可能なプロンプトテンプレートを列挙します。 -- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きの具体的なプロンプトを取得します。 +- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。 ```python from agents import Agent @@ -448,19 +468,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 関連情報。 ![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg) -## 参考情報 +## 参考資料 - [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様と設計ガイド。 - [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP サンプル。 -- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認とコネクターを含む完全なホスト型 MCP デモ。 +- [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 90e76acd8c..c05e6b0bbb 100644 --- a/docs/ja/models/index.md +++ b/docs/ja/models/index.md @@ -4,31 +4,31 @@ search: --- # モデル -Agents SDK には、OpenAI モデルに対するすぐに使えるサポートが 2 種類あります。 +Agents SDK には、OpenAI モデルの標準サポートが 2 種類用意されています。 - **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。 - [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 ## モデル設定の選択 -設定に合う最もシンプルな方法から始めてください。 +セットアップに合う最もシンプルな方法から始めてください。 -| やりたいこと | 推奨される方法 | 詳細 | +| 実現したいこと | 推奨される方法 | 詳細 | | --- | --- | --- | -| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデルの経路で使用する | [OpenAI モデル](#openai-models) | -| websocket トランスポート経由で OpenAI Responses API を使用する | Responses モデルの経路を維持し、websocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) | +| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデルパスで使用する | [OpenAI モデル](#openai-models) | +| websocket トランスポート経由で OpenAI Responses API を使用する | Responses モデルパスを維持し、websocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) | | 1 つの非 OpenAI プロバイダーを使用する | 組み込みのプロバイダー統合ポイントから始める | [非 OpenAI モデル](#non-openai-models) | -| エージェント間でモデルやプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能の違いを確認する | [1 つのワークフローでのモデルの混在](#mixing-models-in-one-workflow) と [プロバイダー間でのモデルの混在](#mixing-models-across-providers) | -| 高度な OpenAI Responses リクエスト設定を調整する | OpenAI Responses の経路で `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) | -| 非 OpenAI または混在プロバイダーのルーティングにサードパーティアダプターを使用する | サポートされているベータ版アダプターを比較し、提供予定のプロバイダー経路を検証する | [サードパーティアダプター](#third-party-adapters) | +| エージェント間でモデルまたはプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能差を確認する | [1 つのワークフローでのモデルの混在](#mixing-models-in-one-workflow) と [プロバイダー間でのモデルの混在](#mixing-models-across-providers) | +| 高度な OpenAI Responses リクエスト設定を調整する | OpenAI Responses パスで `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) | +| 非 OpenAI または混在プロバイダーのルーティングにサードパーティアダプターを使用する | サポートされているベータ版アダプターを比較し、リリース予定のプロバイダーパスを検証する | [サードパーティアダプター](#third-party-adapters) | ## OpenAI モデル -ほとんどの OpenAI のみのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデルの経路に留まることを推奨します。 +ほとんどの OpenAI のみのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデルパスを維持する方法が推奨されます。 -`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは、低レイテンシのエージェントワークフロー向けに、`reasoning.effort="none"` と `verbosity="low"` を設定した [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) です。アクセス権がある場合は、明示的な `model_settings` を維持しつつ、より高い品質のためにエージェントを [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) に設定することを推奨します。 +`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。低レイテンシのエージェントワークフロー向けに、現在のデフォルトは [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) で、`reasoning.effort="none"` と `verbosity="low"` が設定されています。アクセス権がある場合は、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) をエージェントに設定することを推奨します。 -[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) のような他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。 +[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。 ### デフォルトモデル @@ -39,7 +39,7 @@ export OPENAI_DEFAULT_MODEL=gpt-5.5 python3 my_awesome_agent.py ``` -次に、`RunConfig` を使って実行のデフォルトモデルを設定できます。エージェントにモデルを設定していない場合、この実行のモデルが使用されます。 +次に、`RunConfig` を通じて実行のデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使用されます。 ```python from agents import Agent, RunConfig, Runner @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 モデル -この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最適に機能する設定が使用されます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。 +この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最も適切に動作する設定が適用されます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。 ```python from openai.types.shared import Reasoning @@ -74,35 +74,35 @@ my_agent = Agent( ) ``` -より低いレイテンシのためには、GPT-5 モデルで `reasoning.effort="none"` を使用することを推奨します。 +低レイテンシにするには、GPT-5 モデルで `reasoning.effort="none"` を使用することを推奨します。 #### ComputerTool のモデル選択 -エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれている場合、実際の Responses リクエストで有効なモデルにより、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込みの `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは古い `computer_use_preview` ペイロードが維持されます。 +エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込み `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードが維持されます。 -主な例外はプロンプト管理の呼び出しです。プロンプトテンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK はプロンプトがどのモデルに固定しているかを推測しないよう、プレビュー互換の computer ペイロードをデフォルトにします。このフローで GA 経路を維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。 +主な例外は、プロンプト管理の呼び出しです。プロンプトテンプレートがモデルを保持し、SDK がリクエストから `model` を省略する場合、SDK は、プロンプトが固定しているモデルを推測しないように、プレビュー互換の computer ペイロードをデフォルトにします。そのフローで GA パスを維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。 -登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名のように振る舞い続けます。 +登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名と同様に動作し続けます。 -プレビュー互換のリクエストでは `environment` と表示寸法を事前にシリアライズする必要があるため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細については [Tools](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。 +プレビュー互換のリクエストでは、`environment` と表示寸法を事前にシリアライズする必要があります。そのため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細については、[ツール](../tools.md#computertool-and-the-responses-computer-tool)を参照してください。 #### 非 GPT-5 モデル -カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意のモデルと互換性のある汎用の `ModelSettings` に戻します。 +カスタムの `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意のモデルと互換性のある汎用の `ModelSettings` に戻します。 ### Responses のみのツール検索機能 -次のツール機能は OpenAI Responses モデルでのみサポートされます。 +次のツール機能は、OpenAI Responses モデルでのみサポートされています。 - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] -- `@function_tool(defer_loading=True)` およびその他の遅延読み込み Responses ツールサーフェス +- `@function_tool(defer_loading=True)` とその他の遅延読み込み Responses ツールサーフェス -これらの機能は、Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の名前空間名や遅延専用の関数名を強制するのではなく、`auto` または `required` のツール選択によってモデルにツールを読み込ませてください。設定の詳細と現在の制約については [Tools](../tools.md#hosted-tool-search) を参照してください。 +これらの機能は、Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の名前空間名や遅延専用の関数名を強制するのではなく、`auto` または `required` のツール選択を通じてモデルにツールを読み込ませてください。セットアップの詳細と現在の制約については、[ツール](../tools.md#hosted-tool-search)を参照してください。 ### Responses WebSocket トランスポート -デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI バックのモデルを使用する場合、websocket トランスポートを選択できます。 +デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI ベースのモデルを使用する場合は、websocket トランスポートを有効にできます。 #### 基本設定 @@ -114,7 +114,7 @@ set_default_openai_responses_transport("websocket") これは、デフォルトの OpenAI プロバイダーによって解決される OpenAI Responses モデル（`"gpt-5.5"` などの文字列モデル名を含む）に影響します。 -トランスポートの選択は、SDK がモデル名をモデルインスタンスに解決するときに行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡す場合、そのトランスポートはすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は websocket を使用し、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP を使用し、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡す場合、そのプロバイダーがグローバルデフォルトの代わりにトランスポート選択を制御します。 +トランスポートの選択は、SDK がモデル名をモデルインスタンスに解決するときに行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡す場合、そのトランスポートはすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は websocket を使用し、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP を使用し、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡す場合、グローバルデフォルトではなく、そのプロバイダーがトランスポート選択を制御します。 #### プロバイダーまたは実行レベルの設定 @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -OpenAI バックのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI 設定が harness ID などのプロバイダーレベル登録メタデータを想定している場合の高度なオプションです。 +OpenAI ベースのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI の設定で harness ID などのプロバイダーレベルの登録メタデータが想定されている場合の高度なオプションです。 ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### `MultiProvider` による高度なルーティング -プレフィックスベースのモデルルーティングが必要な場合（たとえば 1 つの実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。 +プレフィックスベースのモデルルーティングが必要な場合（たとえば 1 つの実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）は、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。 -`MultiProvider` は 2 つの歴史的なデフォルトを維持しています。 +`MultiProvider` は、歴史的なデフォルトを 2 つ保持しています。 - `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。 -- 不明なプレフィックスは、そのまま渡されるのではなく `UserError` を発生させます。 +- 不明なプレフィックスは、パススルーされるのではなく `UserError` を発生させます。 -OpenAI 互換エンドポイントがリテラルな名前空間付きモデル ID を期待する場合、OpenAI プロバイダーをそのエンドポイントに向ける際は、パススルー動作を明示的に有効にしてください。websocket が有効な設定では、`MultiProvider` 上でも `openai_use_responses_websocket=True` を維持してください。 +OpenAI プロバイダーを、リテラルな名前空間付きモデル ID を想定する OpenAI 互換エンドポイントに向ける場合は、パススルー動作を明示的に有効にします。websocket が有効なセットアップでは、`MultiProvider` でも `openai_use_responses_websocket=True` を維持してください。 ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,39 +198,39 @@ result = await Runner.run( ) ``` -バックエンドがリテラルな `openai/...` 文字列を期待する場合は `openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` など、他の名前空間付きモデル ID を期待する場合は `unknown_prefix_mode="model_id"` を使用します。これらのオプションは websocket トランスポート以外の `MultiProvider` でも機能します。この例では、このセクションで説明しているトランスポート設定の一部であるため、websocket を有効のままにしています。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。 +バックエンドがリテラルな `openai/...` 文字列を想定する場合は、`openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` など、他の名前空間付きモデル ID を想定する場合は、`unknown_prefix_mode="model_id"` を使用します。これらのオプションは、websocket トランスポート外の `MultiProvider` でも機能します。この例では、このセクションで説明しているトランスポート設定の一部であるため、websocket を有効なままにしています。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。 -`MultiProvider` 経由でルーティングしながら同じプロバイダーレベル登録メタデータが必要な場合は、`openai_agent_registration=OpenAIAgentRegistrationConfig(...)` を渡すと、基盤となる OpenAI プロバイダーに転送されます。 +`MultiProvider` 経由でルーティングしながら同じプロバイダーレベルの登録メタデータが必要な場合は、`openai_agent_registration=OpenAIAgentRegistrationConfig(...)` を渡すと、基盤となる OpenAI プロバイダーに転送されます。 -カスタム OpenAI 互換エンドポイントまたはプロキシを使用する場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのような設定では、`websocket_base_url` を明示的に設定する必要がある場合があります。 +カスタムの OpenAI 互換エンドポイントまたはプロキシを使用する場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのようなセットアップでは、`websocket_base_url` を明示的に設定する必要がある場合があります。 #### 注記 -- これは websocket トランスポート経由の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や非 OpenAI プロバイダーには、Responses websocket `/responses` エンドポイントをサポートしていない限り適用されません。 +- これは websocket トランスポート上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Responses websocket `/responses` エンドポイントをサポートしていない限り、Chat Completions や非 OpenAI プロバイダーには適用されません。 - 環境でまだ利用できない場合は、`websockets` パッケージをインストールしてください。 -- websocket トランスポートを有効にした後、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。複数ターンのワークフローで、同じ websocket 接続をターン間（およびネストされた agent-as-tool 呼び出し）で再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[Running agents](../running_agents.md) ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。 -- 長い reasoning ターンやレイテンシの急増があるネットワークでは、`responses_websocket_options` で websocket keepalive の動作をカスタマイズしてください。遅延した pong フレームを許容するには `ping_timeout` を増やすか、ping を有効にしたまま heartbeat タイムアウトを無効にするには `ping_timeout=None` を設定します。websocket レイテンシよりも信頼性が重要な場合は、HTTP/SSE トランスポートを優先してください。 +- websocket トランスポートを有効にした後、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。複数ターンのワークフローで、ターン間（および入れ子の agent-as-tool 呼び出し）で同じ websocket 接続を再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[エージェントの実行](../running_agents.md)ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。 +- 長い推論ターンやレイテンシの急増があるネットワークでは、`responses_websocket_options` で websocket keepalive の動作をカスタマイズしてください。遅延した pong フレームを許容するには `ping_timeout` を増やすか、ping を有効にしたままハートビートタイムアウトを無効にするには `ping_timeout=None` を設定します。websocket レイテンシより信頼性が重要な場合は、HTTP/SSE トランスポートを優先してください。 ## 非 OpenAI モデル -非 OpenAI プロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くの設定では、サードパーティアダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 +非 OpenAI プロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くのセットアップでは、サードパーティアダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。 ### 非 OpenAI プロバイダーの統合方法 -| アプローチ | 使用する場合 | スコープ | +| アプローチ | 使用する場合 | 範囲 | | --- | --- | --- | | [`set_default_openai_client`][agents.set_default_openai_client] | 1 つの OpenAI 互換エンドポイントを、ほとんどまたはすべてのエージェントのデフォルトにしたい場合 | グローバルデフォルト | -| [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタムプロバイダーを単一の実行に適用したい場合 | 実行ごと | -| [`Agent.model`][agents.agent.Agent.model] | 異なるエージェントに異なるプロバイダーまたは具体的なモデルオブジェクトが必要な場合 | エージェントごと | -| サードパーティアダプター | 組み込みの経路では提供されない、アダプター管理のプロバイダーカバレッジまたはルーティングが必要な場合 | [サードパーティアダプター](#third-party-adapters) を参照 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタムプロバイダーを 1 回の実行に適用したい場合 | 実行ごと | +| [`Agent.model`][agents.agent.Agent.model] | 異なるエージェントに異なるプロバイダーや具体的なモデルオブジェクトが必要な場合 | エージェントごと | +| サードパーティアダプター | 組み込みパスでは提供されない、アダプター管理のプロバイダー対応範囲やルーティングが必要な場合 | [サードパーティアダプター](#third-party-adapters)を参照 | -これらの組み込み経路を使って他の LLM プロバイダーを統合できます。 +これらの組み込みパスで、他の LLM プロバイダーを統合できます。 -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) を参照してください。 +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) を参照してください。 -`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。 +`platform.openai.com` からの API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効にするか、[別のトレーシングプロセッサー](../tracing.md)を設定することを推奨します。 ``` python from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled @@ -245,11 +245,11 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API/モデルを使用しています。LLM プロバイダーが Responses をサポートしている場合は、Responses を使用することを推奨します。 + これらの例では、Chat Completions API/モデルを使用しています。多くの LLM プロバイダーは、まだ Responses API をサポートしていないためです。LLM プロバイダーが Responses API をサポートしている場合は、Responses の使用を推奨します。 ## 1 つのワークフローでのモデルの混在 -単一のワークフロー内で、各エージェントに異なるモデルを使用したい場合があります。たとえば、トリアージにはより小さく高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用できます。[`Agent`][agents.Agent] を設定するときは、次のいずれかによって特定のモデルを選択できます。 +単一のワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、トリアージには小さく高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用できます。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法で特定のモデルを選択できます。 1. モデル名を渡す。 2. 任意のモデル名と、その名前を Model インスタンスにマッピングできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。 @@ -257,7 +257,7 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしていますが、2 つの形でサポートする機能とツールのセットが異なるため、各ワークフローでは単一のモデル形を使用することを推奨します。ワークフローでモデル形を組み合わせる必要がある場合は、使用するすべての機能が両方で利用できることを確認してください。 + SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、2 つの形状でサポートされる機能とツールのセットが異なるため、各ワークフローでは単一のモデル形状を使用することを推奨します。ワークフローでモデル形状を組み合わせる必要がある場合は、使用するすべての機能が両方で利用できることを確認してください。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -293,7 +293,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 @@ -308,20 +308,20 @@ english_agent = Agent( ## 高度な OpenAI Responses 設定 -OpenAI Responses の経路を使用していて、より細かな制御が必要な場合は、`ModelSettings` から始めてください。 +OpenAI Responses パスを使用していて、より詳細な制御が必要な場合は、`ModelSettings` から始めてください。 ### 一般的な高度な `ModelSettings` オプション OpenAI Responses API を使用している場合、いくつかのリクエストフィールドにはすでに直接対応する `ModelSettings` フィールドがあるため、それらに `extra_args` は不要です。 -- `parallel_tool_calls`: 同じターン内で複数のツール呼び出しを許可または禁止します。 -- `truncation`: コンテキストがあふれる場合に失敗するのではなく、Responses API が最も古い会話アイテムを削除できるようにするには `"auto"` を設定します。 -- `store`: 生成されたレスポンスを後で取得できるようサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存するフォローアップワークフローや、`store=False` の場合にローカル入力へフォールバックする必要がある可能性のあるセッション圧縮フローに関係します。 +- `parallel_tool_calls`: 同じターン内の複数のツール呼び出しを許可または禁止します。 +- `truncation`: コンテキストがあふれる場合に失敗するのではなく、Responses API が最も古い会話アイテムを削除できるようにするには、`"auto"` を設定します。 +- `store`: 生成されたレスポンスを後で取得できるようにサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存する後続ワークフローや、`store=False` のときにローカル入力へのフォールバックが必要になる可能性があるセッション圧縮フローで重要です。 - `context_management`: `compact_threshold` を使用した Responses 圧縮など、サーバー側のコンテキスト処理を設定します。 -- `prompt_cache_retention`: たとえば `"24h"` で、キャッシュされたプロンプトプレフィックスをより長く保持します。 -- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードを要求します。 -- `top_logprobs`: 出力テキストの top-token logprobs を要求します。SDK は `message.output_text.logprobs` も自動的に追加します。 -- `retry`: モデル呼び出しに対して runner 管理のリトライ設定を有効にします。[Runner 管理のリトライ](#runner-managed-retries) を参照してください。 +- `prompt_cache_retention`: たとえば `"24h"` を使って、キャッシュされたプロンプトプレフィックスをより長く保持します。 +- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、よりリッチなレスポンスペイロードをリクエストします。 +- `top_logprobs`: 出力テキストの top-token logprobs をリクエストします。SDK は `message.output_text.logprobs` も自動的に追加します。 +- `retry`: モデル呼び出しに対する runner 管理の再試行設定を有効にします。[Runner 管理の再試行](#runner-managed-retries)を参照してください。 ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側で取得できるようには保持しません。これはステートレスまたはゼロデータ保持スタイルのフローに便利ですが、通常であればレスポンス ID を再利用する機能が、代わりにローカル管理の状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていなかった場合、デフォルトの `"auto"` 圧縮経路を入力ベースの圧縮に切り替えます。[Sessions guide](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。 +`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側から取得できるようには保持しません。これはステートレス、またはゼロデータ保持スタイルのフローに便利ですが、通常ならレスポンス ID を再利用する機能が、代わりにローカル管理の状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていない場合、デフォルトの `"auto"` 圧縮パスを入力ベースの圧縮に切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions)を参照してください。 -サーバー側圧縮は [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] とは異なります。`context_management=[{"type": "compaction", "compact_threshold": ...}]` は各 Responses API リクエストとともに送信され、レンダリングされたコンテキストがしきい値を超えると、API はレスポンスの一部として圧縮アイテムを出力できます。`OpenAIResponsesCompactionSession` はターン間でスタンドアロンの `responses.compact` エンドポイントを呼び出し、ローカルセッション履歴を書き換えます。 +サーバー側圧縮は、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] とは異なります。`context_management=[{"type": "compaction", "compact_threshold": ...}]` は各 Responses API リクエストと一緒に送信され、レンダリングされたコンテキストがしきい値を超えると、API はレスポンスの一部として圧縮アイテムを出力できます。`OpenAIResponsesCompactionSession` はターン間でスタンドアロンの `responses.compact` エンドポイントを呼び出し、ローカルセッション履歴を書き換えます。 -### `extra_args` の渡し方 +### `extra_args` の受け渡し -SDK がまだトップレベルで直接公開していない、プロバイダー固有またはより新しいリクエストフィールドが必要な場合は `extra_args` を使用します。 +プロバイダー固有、または SDK がまだトップレベルで直接公開していない新しいリクエストフィールドが必要な場合は、`extra_args` を使用します。 -また、OpenAI の Responses API を使用する場合、[その他の任意パラメーターがいくつかあります](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）。それらがトップレベルで利用できない場合も、`extra_args` を使って渡せます。同じリクエストフィールドを直接の `ModelSettings` フィールドでも設定しないでください。 +また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。それらがトップレベルで利用できない場合は、`extra_args` を使用して渡すこともできます。同じリクエストフィールドを、直接の `ModelSettings` フィールドでも同時に設定しないでください。 ```python from agents import Agent, ModelSettings @@ -365,9 +365,9 @@ english_agent = Agent( ) ``` -## Runner 管理のリトライ +## Runner 管理の再試行 -リトライはランタイム専用で、明示的に有効化する必要があります。`ModelSettings(retry=...)` を設定し、リトライポリシーがリトライを選択しない限り、SDK は一般的なモデルリクエストをリトライしません。 +再試行はランタイム専用で、明示的な有効化が必要です。`ModelSettings(retry=...)` を設定し、再試行ポリシーが再試行を選択しない限り、SDK は一般的なモデルリクエストを再試行しません。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -401,79 +401,79 @@ agent = Agent( | フィールド | 型 | 注記 | | --- | --- | --- | -| `max_retries` | `int | None` | 初回リクエスト後に許可されるリトライ試行回数。 | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずにリトライする場合のデフォルト遅延戦略。`backoff.max_delay` は、この計算された backoff 遅延のみを上限設定します。ポリシーが返す明示的な遅延や retry-after ヒントには上限を設けません。 | -| `policy` | `RetryPolicy | None` | リトライするかどうかを決定するコールバック。このフィールドはランタイム専用で、シリアライズされません。 | +| `max_retries` | `int | None` | 初回リクエスト後に許可される再試行回数。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずに再試行する場合のデフォルトの遅延戦略。`backoff.max_delay` は、この計算された backoff 遅延のみを上限設定します。ポリシーから返された明示的な遅延や retry-after ヒントには上限を設定しません。 | +| `policy` | `RetryPolicy | None` | 再試行するかどうかを決定するコールバック。このフィールドはランタイム専用で、シリアライズされません。 | -リトライポリシーは、次を含む [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。 +再試行ポリシーは、以下を含む [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。 -- `attempt` と `max_retries` により、試行回数を意識した判断ができます。 -- `stream` により、ストリーミングと非ストリーミングの動作を分岐できます。 -- raw な検査のための `error`。 -- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの正規化された事実。 -- 基盤となるモデルアダプターがリトライ指針を提供できる場合の `provider_advice`。 +- `attempt` と `max_retries`。試行回数を考慮した判断を行えます。 +- `stream`。ストリーミングと非ストリーミングの動作を分岐できます。 +- `error`。生の内容を確認できます。 +- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの正規化された情報。 +- 基盤のモデルアダプターが再試行ガイダンスを提供できる場合の `provider_advice`。 -ポリシーは次のいずれかを返せます。 +ポリシーは以下のいずれかを返せます。 -- シンプルなリトライ判断としての `True` / `False`。 -- 遅延を上書きしたり診断理由を添付したりしたい場合の [`RetryDecision`][agents.retry.RetryDecision]。 +- 単純な再試行判断のための `True` / `False`。 +- 遅延を上書きしたり、診断理由を付加したりしたい場合の [`RetryDecision`][agents.retry.RetryDecision]。 -SDK は `retry_policies` 上に既製のヘルパーをエクスポートしています。 +SDK は、`retry_policies` に既製のヘルパーをエクスポートしています。 | ヘルパー | 動作 | | --- | --- | -| `retry_policies.never()` | 常にリトライしません。 | -| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーのリトライ指針に従います。 | -| `retry_policies.network_error()` | 一時的なトランスポート障害およびタイムアウト障害に一致します。 | +| `retry_policies.never()` | 常にオプトアウトします。 | +| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーの再試行助言に従います。 | +| `retry_policies.network_error()` | 一時的なトランスポート障害とタイムアウト障害に一致します。 | | `retry_policies.http_status([...])` | 選択した HTTP ステータスコードに一致します。 | -| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使ってリトライします。このヘルパーは retry-after 値を明示的なポリシー遅延として扱うため、`backoff.max_delay` はそれを上限設定しません。 | -| `retry_policies.any(...)` | ネストされたポリシーのいずれかが有効にした場合にリトライします。 | -| `retry_policies.all(...)` | ネストされたすべてのポリシーが有効にした場合にのみリトライします。 | +| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使用して再試行します。このヘルパーは retry-after 値を明示的なポリシー遅延として扱うため、`backoff.max_delay` はそれを上限設定しません。 | +| `retry_policies.any(...)` | 入れ子のポリシーのいずれかが有効化した場合に再試行します。 | +| `retry_policies.all(...)` | 入れ子のすべてのポリシーが有効化した場合にのみ再試行します。 | -ポリシーを合成する場合、`provider_suggested()` は、プロバイダーが区別できる場合にプロバイダーの拒否や再実行安全性の承認を保持するため、最も安全な最初の構成要素です。 +ポリシーを合成する場合、`provider_suggested()` は最も安全な最初の構成要素です。プロバイダーがそれらを区別できる場合に、プロバイダーの拒否とリプレイ安全性の承認を保持するためです。 ##### 安全境界 -一部の失敗は自動的にリトライされません。 +一部の障害は自動的には再試行されません。 -- Abort エラー。 -- プロバイダーの助言が再実行を安全ではないと示すリクエスト。 -- 出力がすでに開始され、再実行が安全でなくなるような形になった後のストリーミング実行。 +- 中止エラー。 +- プロバイダーからの助言がリプレイを安全でないと示すリクエスト。 +- リプレイが安全でなくなる形で出力がすでに開始された後のストリーミング実行。 -`previous_response_id` または `conversation_id` を使用するステートフルなフォローアップリクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` などの非プロバイダー述語だけでは十分ではありません。リトライポリシーには、通常 `retry_policies.provider_suggested()` を介して、プロバイダーからの再実行安全性の承認を含める必要があります。 +`previous_response_id` または `conversation_id` を使用するステートフルな後続リクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` など、プロバイダー以外の述語だけでは十分ではありません。再試行ポリシーには、通常 `retry_policies.provider_suggested()` を通じて、プロバイダーからのリプレイ安全性の承認を含める必要があります。 ##### Runner とエージェントのマージ動作 -`retry` は runner レベルとエージェントレベルの `ModelSettings` の間でディープマージされます。 +`retry` は、runner レベルとエージェントレベルの `ModelSettings` の間でディープマージされます。 - エージェントは `retry.max_retries` だけを上書きし、runner の `policy` を継承できます。 -- エージェントは `retry.backoff` の一部だけを上書きし、runner から兄弟 backoff フィールドを保持できます。 +- エージェントは `retry.backoff` の一部だけを上書きし、runner の兄弟 backoff フィールドを維持できます。 - `policy` はランタイム専用であるため、シリアライズされた `ModelSettings` は `max_retries` と `backoff` を保持しますが、コールバック自体は省略します。 -より詳しい例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [アダプター backed リトライ例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。 +より完全な例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [アダプターベースの再試行例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)を参照してください。 ## 非 OpenAI プロバイダーのトラブルシューティング ### トレーシングクライアントエラー 401 -トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI サーバーにアップロードされるためであり、OpenAI API キーを持っていないことが原因です。これを解決するには 3 つの選択肢があります。 +トレーシングに関連するエラーが発生する場合、トレースが OpenAI サーバーにアップロードされる一方で、OpenAI API キーがないことが原因です。これを解決するには、3 つの選択肢があります。 -1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 +1. トレーシングを完全に無効にする: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものである必要があります。 -3. 非 OpenAI トレースプロセッサーを使用する。[トレーシングドキュメント](../tracing.md#custom-tracing-processors) を参照してください。 +3. 非 OpenAI トレースプロセッサーを使用する。[トレーシングドキュメント](../tracing.md#custom-tracing-processors)を参照してください。 ### Responses API のサポート -SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだこれをサポートしていません。その結果、404 などの問題が発生することがあります。解決するには 2 つの選択肢があります。 +SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだこれをサポートしていません。その結果、404 などの問題が発生する場合があります。解決するには、2 つの選択肢があります。 1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。 -2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) に例があります。 +2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)に例があります。 ### structured outputs のサポート -一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。 +一部のモデルプロバイダーは、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。 ``` @@ -481,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -これは一部のモデルプロバイダーの制約です。JSON 出力はサポートしていますが、出力に使用する `json_schema` を指定できません。現在この修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することをおすすめします。そうしないと、不正な形式の JSON によりアプリが頻繁に壊れる可能性があります。 +これは一部のモデルプロバイダーの制約です。JSON 出力はサポートしていますが、出力に使用する `json_schema` の指定は許可していません。この問題の修正に取り組んでいますが、JSON schema 出力をサポートしているプロバイダーに依存することを推奨します。そうしないと、不正な形式の JSON が原因でアプリが頻繁に壊れるためです。 ## プロバイダー間でのモデルの混在 -モデルプロバイダー間の機能差を把握しておく必要があります。そうしないとエラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホストされたファイル検索および Web 検索をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 +モデルプロバイダー間の機能差を理解しておく必要があります。そうしないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。 -- 未対応の `tools` を、それを理解しないプロバイダーに送信しないでください -- テキスト専用モデルを呼び出す前に、マルチモーダル入力を除外してください -- 構造化 JSON 出力をサポートしていないプロバイダーは、ときどき無効な JSON を生成することに注意してください。 +- サポートされていない `tools` を、それらを理解しないプロバイダーに送信しないでください +- テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外してください +- structured JSON 出力をサポートしていないプロバイダーは、無効な JSON を生成することがある点に注意してください。 ## サードパーティアダプター -SDK の組み込みプロバイダー統合ポイントでは不十分な場合にのみ、サードパーティアダプターを使用してください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 経路を優先してください。サードパーティアダプターは、OpenAI モデルを非 OpenAI プロバイダーと組み合わせる必要がある場合、または組み込み経路では提供されないアダプター管理のプロバイダーカバレッジやルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に別の互換性レイヤーを追加するため、機能サポートやリクエストのセマンティクスはプロバイダーによって異なる場合があります。SDK には現在、ベストエフォートのベータ版アダプター統合として Any-LLM と LiteLLM が含まれています。 +SDK の組み込みプロバイダー統合ポイントで十分でない場合にのみ、サードパーティアダプターを使用してください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] パスを優先してください。サードパーティアダプターは、OpenAI モデルと非 OpenAI プロバイダーを組み合わせる必要がある場合、または組み込みパスでは提供されないアダプター管理のプロバイダー対応範囲やルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に別の互換性レイヤーを追加するため、機能サポートとリクエストセマンティクスはプロバイダーによって異なる場合があります。SDK には現在、Any-LLM と LiteLLM がベストエフォートのベータ版アダプター統合として含まれています。 ### Any-LLM -Any-LLM のサポートは、Any-LLM 管理のプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。 +Any-LLM のサポートは、Any-LLM 管理のプロバイダー対応範囲やルーティングが必要な場合向けに、ベストエフォートのベータ版として含まれています。 -上流プロバイダーの経路によって、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換性レイヤーを使用する場合があります。 +上流プロバイダーパスによって、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換性レイヤーを使用する場合があります。 -Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用する、`AnyLLMModel` を直接インスタンス化する、または実行スコープで `AnyLLMProvider` を使用できます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` の構築時に `api="responses"` または `api="chat_completions"` を渡します。 +Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用するか、`AnyLLMModel` を直接インスタンス化するか、実行スコープで `AnyLLMProvider` を使用できます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` を構築するときに `api="responses"` または `api="chat_completions"` を渡します。 -Any-LLM はサードパーティアダプターレイヤーのままなので、プロバイダーの依存関係や機能のギャップは SDK ではなく上流の Any-LLM によって定義されます。上流プロバイダーが使用量メトリクスを返す場合、それらは自動的に伝播されますが、ストリーミング Chat Completions バックエンドでは、使用量チャンクを出力する前に `ModelSettings(include_usage=True)` が必要な場合があります。structured outputs、ツール呼び出し、使用量レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 +Any-LLM はサードパーティアダプターレイヤーであり続けるため、プロバイダー依存関係と機能ギャップは SDK ではなく Any-LLM によって上流で定義されます。使用状況メトリクスは、上流プロバイダーが返す場合に自動的に伝播されますが、ストリーミング Chat Completions バックエンドでは、usage chunks を出力する前に `ModelSettings(include_usage=True)` が必要になる場合があります。structured outputs、ツール呼び出し、使用状況レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 ### LiteLLM -LiteLLM のサポートは、LiteLLM 固有のプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。 +LiteLLM のサポートは、LiteLLM 固有のプロバイダー対応範囲やルーティングが必要な場合向けに、ベストエフォートのベータ版として含まれています。 LiteLLM が必要な場合は、`openai-agents[litellm]` をインストールし、[`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) または [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) から始めてください。`litellm/...` モデル名を使用するか、[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を直接インスタンス化できます。 -一部の LiteLLM バックのプロバイダーは、デフォルトでは SDK の使用量メトリクスを設定しません。使用量レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡し、structured outputs、ツール呼び出し、使用量レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 \ No newline at end of file +一部の LiteLLM ベースのプロバイダーは、デフォルトでは SDK の使用状況メトリクスを設定しません。使用状況レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡し、structured outputs、ツール呼び出し、使用状況レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 \ No newline at end of file diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md index c1437b4455..52041cd9ca 100644 --- a/docs/ja/models/litellm.md +++ b/docs/ja/models/litellm.md @@ -8,6 +8,6 @@ search: window.location.replace("../#third-party-adapters"); -このページは [Models の Third-party adapters セクション](index.md#third-party-adapters)に移動しました。 +このページは [Models のサードパーティアダプターセクション](index.md#third-party-adapters) に移動しました。 自動的にリダイレクトされない場合は、上記のリンクを使用してください。 \ No newline at end of file diff --git a/docs/ja/multi_agent.md b/docs/ja/multi_agent.md index 4d2c9665ee..3e1f149b34 100644 --- a/docs/ja/multi_agent.md +++ b/docs/ja/multi_agent.md @@ -4,61 +4,61 @@ search: --- # エージェントオーケストレーション -オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で実行され、次に何が起こるかをどのように決定するか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります。 +オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを、どの順序で実行し、次に何が起こるかをどのように決定するか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります： -1. LLM に意思決定させる: LLM の知性を使って計画・推論を行い、それに基づいてどのステップを取るかを決定します。 -2. コードでオーケストレーションする: コードによってエージェントの流れを決定します。 +1. LLM に判断を任せる：LLM の知能を使って計画と推論を行い、それに基づいて取る手順を決定します。 +2. コードによるオーケストレーション：コードでエージェントの流れを決定します。 -これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。 +これらのパターンは組み合わせることができます。それぞれにトレードオフがあり、以下で説明します。 ## LLM によるオーケストレーション -エージェントは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM はそのタスクへの取り組み方を自律的に計画でき、tools を使ってアクションを実行しデータを取得し、ハンドオフを使ってサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のようなツールを備えられます。 +エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、自由度の高いタスクが与えられた場合、LLM は、tools を使ってアクションを実行しデータを取得し、ハンドオフを使ってサブエージェントにタスクを委任しながら、そのタスクへの取り組み方を自律的に計画できます。たとえば、リサーチエージェントには次のようなツールを備えられます： -- オンライン情報を見つけるための Web 検索 +- オンラインで情報を見つけるための Web 検索 - 独自データや接続先を検索するためのファイル検索と取得 -- コンピュータ上でアクションを実行するためのコンピュータ操作 +- コンピューター上でアクションを実行するためのコンピュータ操作 - データ分析を行うためのコード実行 -- 計画、レポート作成などに優れた専門エージェントへのハンドオフ +- 計画、レポート作成などに優れた専門エージェントへのハンドオフ。 -### SDK の中核パターン +### コア SDK パターン -Python SDK では、次の 2 つのオーケストレーションパターンが最もよく使われます。 +Python SDK では、次の 2 つのオーケストレーションパターンが最もよく登場します： -| パターン | 仕組み | 最適な場面 | +| パターン | 仕組み | 最適な場合 | | --- | --- | --- | -| Agents as tools | マネージャーエージェントが会話の制御を維持し、`Agent.as_tool()` を通じて専門エージェントを呼び出します。 | 1 つのエージェントに最終回答を担わせたい、複数の専門家の出力を統合したい、または共通のガードレールを 1 か所で適用したい場合。 | -| ハンドオフ | トリアージエージェントが会話を専門エージェントへ振り分け、その専門エージェントがそのターンの残りでアクティブなエージェントになります。 | 専門エージェントに直接応答させたい、プロンプトを集中させたい、またはマネージャーが結果を説明せずに instructions を切り替えたい場合。 | +| Agents as tools | マネージャーエージェントが会話の制御を維持し、`Agent.as_tool()` を通じて専門エージェントを呼び出します。 | 1 つのエージェントに最終回答を担わせたい場合、複数の専門エージェントからの出力を統合したい場合、または共通のガードレールを 1 か所で適用したい場合。 | +| ハンドオフ | トリアージエージェントが会話を専門エージェントにルーティングし、その専門エージェントがそのターンの残りでアクティブなエージェントになります。 | 専門エージェントに直接応答させたい場合、プロンプトを焦点の絞られた状態に保ちたい場合、またはマネージャーが結果を説明することなく instructions を切り替えたい場合。 | -専門エージェントが限定的なサブタスクを支援すべきで、ユーザー向け会話を引き継ぐべきではない場合は **agents as tools** を使います。ルーティング自体がワークフローの一部であり、選ばれた専門エージェントに次のやり取りを担わせたい場合は **handoffs** を使います。 +専門エージェントが範囲の限定されたサブタスクを支援するべきだが、ユーザー向けの会話を引き継ぐべきではない場合は、 **agents as tools** を使用します。ルーティング自体がワークフローの一部であり、選ばれた専門エージェントにインタラクションの次の部分を担わせたい場合は、 **ハンドオフ** を使用します。 -2 つを組み合わせることもできます。トリアージエージェントが専門エージェントにハンドオフし、その専門エージェントがさらに限定的なサブタスクのために他のエージェントをツールとして呼び出すことも可能です。 +この 2 つを組み合わせることもできます。トリアージエージェントが専門エージェントにハンドオフし、その専門エージェントがさらに狭いサブタスクのために他のエージェントをツールとして呼び出すこともできます。 -このパターンは、タスクがオープンエンドで、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) に投資します。これにより、エージェントをトレーニングして改善し、タスクの遂行能力を高めることができます。 -このスタイルのオーケストレーションを支える SDK の基本コンポーネントを確認したい場合は、[tools](tools.md)、[handoffs](handoffs.md)、[running agents](running_agents.md) から始めてください。 +このスタイルのオーケストレーションを支えるコア SDK の基本コンポーネントを知りたい場合は、[ツール](tools.md)、[ハンドオフ](handoffs.md)、[エージェントの実行](running_agents.md) から始めてください。 ## コードによるオーケストレーション -LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の面でタスクをより決定的で予測可能にします。ここで一般的なパターンは次のとおりです。 +LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度、コスト、パフォーマンスの観点でタスクをより決定論的で予測可能にします。ここでの一般的なパターンは次のとおりです： -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使い、コードで検査可能な適切な形式のデータを生成する。たとえば、タスクをいくつかのカテゴリーに分類するようエージェントに求め、そのカテゴリーに基づいて次のエージェントを選択できます。 -- 1 つの出力を次の入力に変換して複数エージェントを連結する。ブログ記事執筆のようなタスクを、リサーチ、アウトライン作成、記事執筆、批評、改善という一連のステップに分解できます。 -- 評価とフィードバックを行うエージェントと組み合わせて、タスク実行エージェントを `while` ループで実行し、評価側が出力が特定の基準を満たしたと言うまで続ける。 -- 複数エージェントを並列実行する。たとえば `asyncio.gather` のような Python の基本機能を使います。これは、相互依存しない複数タスクがある場合の高速化に有用です。 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成します。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択できます。 +- 複数のエージェントをチェーンし、あるエージェントの出力を次のエージェントの入力に変換します。ブログ記事を書くようなタスクを一連のステップに分解できます - リサーチする、アウトラインを書く、ブログ記事を書く、批評し、それから改善します。 +- タスクを実行するエージェントを `while` ループ内で、評価してフィードバックを提供するエージェントと一緒に実行し、評価者が出力が特定の基準を満たしたと言うまで続けます。 +- 複数のエージェントを並列に実行します。たとえば、`asyncio.gather` のような Python の基本コンポーネントを使います。これは、互いに依存しない複数のタスクがある場合に高速化に役立ちます。 -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数のコード例があります。 +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には多数のコード例があります。 ## 関連ガイド -- 構成パターンとエージェント設定については [Agents](agents.md)。 -- `Agent.as_tool()` とマネージャースタイルのオーケストレーションについては [Tools](tools.md#agents-as-tools)。 -- 専門エージェント間の委譲については [Handoffs](handoffs.md)。 -- 実行ごとのオーケストレーション制御と会話状態については [Running agents](running_agents.md)。 -- 最小のエンドツーエンドなハンドオフ例については [Quickstart](quickstart.md)。 \ No newline at end of file +- 構成パターンとエージェント設定については、[エージェント](agents.md) を参照してください。 +- `Agent.as_tool()` とマネージャースタイルのオーケストレーションについては、[ツール](tools.md#agents-as-tools) を参照してください。 +- 専門エージェント間の委任については、[ハンドオフ](handoffs.md) を参照してください。 +- 実行ごとのオーケストレーション制御と会話状態については、[エージェントの実行](running_agents.md) を参照してください。 +- 最小限のエンドツーエンドのハンドオフ例については、[クイックスタート](quickstart.md) を参照してください。 \ No newline at end of file diff --git a/docs/ja/quickstart.md b/docs/ja/quickstart.md index 49e83d440a..5de90e7264 100644 --- a/docs/ja/quickstart.md +++ b/docs/ja/quickstart.md @@ -16,7 +16,7 @@ python -m venv .venv ### 仮想環境の有効化 -新しいターミナルセッションを開始するたびに行います。 +新しいターミナルセッションを開始するたびに行ってください。 macOS または Linux の場合: @@ -40,7 +40,7 @@ pip install openai-agents # or `uv add openai-agents`, etc まだ持っていない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。 -これらのコマンドは、現在のターミナルセッションにキーを設定します。 +以下のコマンドは、現在のターミナルセッションにキーを設定します。 macOS または Linux の場合: @@ -54,7 +54,7 @@ Windows PowerShell の場合: $env:OPENAI_API_KEY = "sk-..." ``` -Windows Command Prompt の場合: +Windows コマンドプロンプトの場合: ```cmd set "OPENAI_API_KEY=sk-..." @@ -62,7 +62,7 @@ set "OPENAI_API_KEY=sk-..." ## 最初のエージェントの作成 -エージェントは、instructions、名前、特定のモデルなどの任意の設定で定義されます。 +エージェントは、instructions、名前、および特定のモデルなどの任意の設定で定義します。 ```python from agents import Agent @@ -75,7 +75,7 @@ agent = Agent( ## 最初のエージェントの実行 -[`Runner`][agents.run.Runner] を使用してエージェントを実行し、[`RunResult`][agents.result.RunResult] を受け取ります。 +[`Runner`][agents.run.Runner] を使用してエージェントを実行し、[`RunResult`][agents.result.RunResult] を取得します。 ```python import asyncio @@ -94,23 +94,23 @@ if __name__ == "__main__": asyncio.run(main()) ``` -2 ターン目では、`result.to_input_list()` を `Runner.run(...)` に渡し戻すか、[session](sessions/index.md) をアタッチするか、`conversation_id` / `previous_response_id` で OpenAI のサーバー管理状態を再利用できます。[エージェントの実行](running_agents.md)ガイドでは、これらのアプローチを比較しています。 +2 回目のターンでは、`result.to_input_list()` を `Runner.run(...)` に戻して渡すか、[セッション](sessions/index.md)をアタッチするか、`conversation_id` / `previous_response_id` で OpenAI によりサーバー側で管理される状態を再利用できます。[エージェントの実行](running_agents.md)ガイドでは、これらのアプローチを比較しています。 -目安として、次のルールを使用してください。 +次の目安を使ってください: -| したいこと... | まず使うもの... | +| 実現したいこと... | まず使うもの... | | --- | --- | | 完全な手動制御とプロバイダー非依存の履歴 | `result.to_input_list()` | | SDK に履歴の読み込みと保存を任せる | [`session=...`](sessions/index.md) | -| OpenAI が管理するサーバー側の継続 | `previous_response_id` または `conversation_id` | +| OpenAI 管理のサーバー側継続 | `previous_response_id` または `conversation_id` | -トレードオフと正確な動作については、[エージェントの実行](running_agents.md#choose-a-memory-strategy)を参照してください。 +トレードオフと正確な挙動については、[エージェントの実行](running_agents.md#choose-a-memory-strategy)を参照してください。 -タスクが主にプロンプト、ツール、会話状態で完結する場合は、通常の `Agent` と `Runner` を使用してください。エージェントが分離されたワークスペース内の実ファイルを検査または変更する必要がある場合は、[Sandbox エージェントクイックスタート](sandbox_agents.md)に進んでください。 +タスクが主にプロンプト、ツール、会話状態で完結する場合は、シンプルな `Agent` と `Runner` を使います。エージェントが分離されたワークスペース内の実ファイルを検査または変更する必要がある場合は、[Sandbox エージェントのクイックスタート](sandbox_agents.md)に進んでください。 ## エージェントへのツールの付与 -エージェントにツールを与えて、情報を検索したりアクションを実行したりできます。 +エージェントにツールを与えることで、情報を調べたりアクションを実行したりできます。 ```python import asyncio @@ -144,14 +144,14 @@ if __name__ == "__main__": ## さらにいくつかのエージェントの追加 -マルチエージェントパターンを選ぶ前に、最終回答を誰が担当すべきかを決めます。 +マルチエージェントパターンを選ぶ前に、最終回答の主導権を誰が持つべきかを決めてください。 -- **ハンドオフ**: スペシャリストがそのターンの該当部分について会話を引き継ぎます。 +- **ハンドオフ**: スペシャリストが、そのターンの該当部分について会話を引き継ぎます。 - **Agents as tools**: オーケストレーターが制御を維持し、スペシャリストをツールとして呼び出します。 -このクイックスタートでは、最初の例として最も短い **ハンドオフ** を続けます。マネージャースタイルのパターンについては、[エージェントオーケストレーション](multi_agent.md) と [ツール: Agents as tools](tools.md#agents-as-tools) を参照してください。 +このクイックスタートでは、最初の例として最も短いため、 **ハンドオフ** で続けます。マネージャースタイルのパターンについては、[エージェントオーケストレーション](multi_agent.md)と[ツール: agents as tools](tools.md#agents-as-tools)を参照してください。 -追加のエージェントも同じ方法で定義できます。`handoff_description` は、ルーティングエージェントに委任すべきタイミングについて追加のコンテキストを提供します。 +追加のエージェントも同じ方法で定義できます。`handoff_description` は、いつ委譲すべきかについて、ルーティングエージェントに追加のコンテキストを提供します。 ```python from agents import Agent @@ -171,7 +171,7 @@ math_tutor_agent = Agent( ## ハンドオフの定義 -エージェントでは、タスクの解決中に選択できる送信ハンドオフオプションの一覧を定義できます。 +エージェントには、タスクを解決する際に選択できるハンドオフ先の選択肢の一覧を定義できます。 ```python triage_agent = Agent( @@ -183,7 +183,7 @@ triage_agent = Agent( ## エージェントオーケストレーションの実行 -Runner は、個々のエージェントの実行、ハンドオフ、およびツール呼び出しを処理します。 +ランナーは、個々のエージェントの実行、すべてのハンドオフ、すべてのツール呼び出しを処理します。 ```python import asyncio @@ -205,21 +205,21 @@ if __name__ == "__main__": ## 参考コード例 -リポジトリには、同じ中核パターンの完全なスクリプトが含まれています。 +このリポジトリには、同じ主要パターンに対応する完全なスクリプトが含まれています: -- [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) は最初の実行用です。 -- [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) は関数ツール用です。 -- [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) はマルチエージェントルーティング用です。 +- [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) は最初の実行の例です。 +- [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) は関数ツールの例です。 +- [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) はマルチエージェントルーティングの例です。 ## トレースの表示 -エージェントの実行中に何が起きたかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces)に移動して、エージェント実行のトレースを表示します。 +エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードのトレースビューアー](https://platform.openai.com/traces)に移動して、エージェント実行のトレースを表示してください。 ## 次のステップ -より複雑なエージェント的フローを構築する方法を学びます。 +より複雑なエージェント型フローの構築方法を学びましょう: - [エージェント](agents.md)の設定方法について学びます。 -- [エージェントの実行](running_agents.md)と [sessions](sessions/index.md) について学びます。 +- [エージェントの実行](running_agents.md)と[セッション](sessions/index.md)について学びます。 - 作業を実際のワークスペース内で行う必要がある場合は、[Sandbox エージェント](sandbox_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 07ab752ed5..324ad556cb 100644 --- a/docs/ja/realtime/guide.md +++ b/docs/ja/realtime/guide.md @@ -4,52 +4,52 @@ search: --- # リアルタイムエージェントガイド -このガイドでは、OpenAI Agents SDK のリアルタイムレイヤーが OpenAI Realtime API にどのように対応するか、また Python SDK がその上に追加する挙動について説明します。 +このガイドでは、OpenAI Agents SDK のリアルタイムレイヤーが OpenAI Realtime API にどのように対応するか、また Python SDK がその上にどのような追加動作を提供するかを説明します。 !!! warning "ベータ機能" - リアルタイムエージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 + リアルタイムエージェントはベータ版です。実装を改善する中で、破壊的変更が入る可能性があります。 -!!! note "最初に読むもの" +!!! note "はじめに" - デフォルトの Python パスを使いたい場合は、まず [クイックスタート](quickstart.md) を読んでください。アプリでサーバーサイド WebSocket と SIP のどちらを使うべきかを検討している場合は、[リアルタイムトランスポート](transport.md) を読んでください。ブラウザーの WebRTC トランスポートは Python SDK の一部ではありません。 + デフォルトの Python パスを使いたい場合は、まず [クイックスタート](quickstart.md) を読んでください。アプリでサーバー側 WebSocket と SIP のどちらを使用すべきか判断している場合は、[Realtime トランスポート](transport.md) を読んでください。ブラウザーの WebRTC トランスポートは Python SDK の一部ではありません。 ## 概要 -リアルタイムエージェントは Realtime API への長時間接続を維持し、モデルがテキストと音声を段階的に処理し、音声出力をストリーミングし、ツールを呼び出し、各ターンで新しいリクエストを再開することなく割り込みを処理できるようにします。 +リアルタイムエージェントは、モデルがテキストと音声を段階的に処理し、音声出力をストリーミングし、ツールを呼び出し、各ターンで新しいリクエストを再開始することなく中断を処理できるように、Realtime API への長時間接続を開いたままにします。 -主な SDK コンポーネントは次のとおりです。 +主な SDK コンポーネントは次のとおりです： -- **RealtimeAgent**: 1 つのリアルタイム専門エージェント向けの instructions、ツール、出力ガードレール、ハンドオフ +- **RealtimeAgent**: 1 つのリアルタイム専門エージェントに対する instructions、tools、出力ガードレール、ハンドオフ - **RealtimeRunner**: 開始エージェントをリアルタイムトランスポートに接続するセッションファクトリー - **RealtimeSession**: 入力を送信し、イベントを受信し、履歴を追跡し、ツールを実行するライブセッション -- **RealtimeModel**: トランスポート抽象化です。デフォルトは OpenAI のサーバーサイド WebSocket 実装です。 +- **RealtimeModel**: トランスポート抽象化。デフォルトは OpenAI のサーバー側 WebSocket 実装です。 ## セッションライフサイクル -典型的なリアルタイムセッションは次のようになります。 +一般的なリアルタイムセッションは次のようになります： -1. 1 つ以上の `RealtimeAgent` を作成します。 -2. 開始エージェントで `RealtimeRunner` を作成します。 +1. `RealtimeAgent` を 1 つ以上作成します。 +2. 開始エージェントを指定して `RealtimeRunner` を作成します。 3. `await runner.run()` を呼び出して `RealtimeSession` を取得します。 4. `async with session:` または `await session.enter()` でセッションに入ります。 5. `send_message()` または `send_audio()` でユーザー入力を送信します。 6. 会話が終了するまでセッションイベントを反復処理します。 -テキストのみの実行とは異なり、`runner.run()` は最終的な実行結果をすぐには生成しません。ローカル履歴、バックグラウンドのツール実行、ガードレール状態、アクティブなエージェント設定をトランスポート層と同期し続けるライブセッションオブジェクトを返します。 +テキストのみの実行とは異なり、`runner.run()` はすぐに最終的な実行結果を生成しません。ローカル履歴、バックグラウンドのツール実行、ガードレール状態、アクティブなエージェント設定をトランスポート層と同期し続けるライブセッションオブジェクトを返します。 -デフォルトでは、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用するため、デフォルトの Python パスは Realtime API へのサーバーサイド WebSocket 接続です。別の `RealtimeModel` を渡した場合でも、同じセッションライフサイクルとエージェント機能が適用されますが、接続の仕組みは変わる場合があります。 +デフォルトでは、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用するため、デフォルトの Python パスは Realtime API へのサーバー側 WebSocket 接続です。別の `RealtimeModel` を渡した場合でも、同じセッションライフサイクルとエージェント機能が適用され、接続の仕組みだけが変わることがあります。 -## エージェントとセッション設定 +## エージェントとセッションの設定 -`RealtimeAgent` は、通常の `Agent` 型より意図的に範囲が狭くなっています。 +`RealtimeAgent` は、通常の `Agent` 型より意図的に範囲が絞られています： -- モデル選択はエージェントごとではなく、セッションレベルで設定します。 -- structured outputs はサポートされていません。 -- 音声は設定できますが、セッションがすでに発話音声を生成した後に変更することはできません。 +- モデルの選択はエージェント単位ではなく、セッションレベルで設定します。 +- Structured outputs はサポートされていません。 +- 音声は設定できますが、セッションがすでに音声出力を生成した後は変更できません。 - instructions、関数ツール、ハンドオフ、フック、出力ガードレールはすべて引き続き機能します。 -`RealtimeSessionModelSettings` は、新しいネストされた `audio` 設定と古いフラットなエイリアスの両方をサポートします。新しいコードではネストされた形を優先し、新しいリアルタイムエージェントでは `gpt-realtime-2` から始めてください。 +`RealtimeSessionModelSettings` は、新しいネストされた `audio` 設定と、従来のフラットなエイリアスの両方をサポートします。新しいコードではネストされた形を推奨し、新しいリアルタイムエージェントでは `gpt-realtime-2` から始めてください： ```python runner = RealtimeRunner( @@ -71,7 +71,7 @@ runner = RealtimeRunner( ) ``` -便利なセッションレベル設定には次のものがあります。 +有用なセッションレベル設定には次のものがあります： - `audio.input.format`, `audio.output.format` - `audio.input.transcription` @@ -83,7 +83,7 @@ runner = RealtimeRunner( - `prompt` - `tracing` -`RealtimeRunner(config=...)` の便利な実行レベル設定には次のものがあります。 +`RealtimeRunner(config=...)` の有用な実行レベル設定には次のものがあります： - `async_tool_calls` - `output_guardrails` @@ -91,13 +91,13 @@ runner = RealtimeRunner( - `tool_error_formatter` - `tracing_disabled` -型付きの全体仕様については、[`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。 +型付きで利用できる全体のインターフェイスについては、[`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。 ## 入力と出力 ### テキストと構造化されたユーザーメッセージ -プレーンテキストまたは構造化されたリアルタイムメッセージには [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。 +プレーンテキストまたは構造化されたリアルタイムメッセージには、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。 ```python from agents.realtime import RealtimeUserInputMessage @@ -115,31 +115,31 @@ message: RealtimeUserInputMessage = { await session.send_message(message) ``` -構造化メッセージは、リアルタイム会話に画像入力を含める主な方法です。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) の Web デモ例は、この方法で `input_image` メッセージを転送します。 +構造化メッセージは、リアルタイム会話に画像入力を含めるための主な方法です。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) のサンプル Web デモでは、この方法で `input_image` メッセージを転送しています。 ### 音声入力 -raw 音声バイトをストリーミングするには [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用します。 +未加工の音声バイトをストリーミングするには、[`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用します： ```python await session.send_audio(audio_bytes) ``` -サーバーサイドのターン検出が無効になっている場合は、ターン境界を示す責任があります。高レベルの便利な方法は次のとおりです。 +サーバー側のターン検出が無効な場合、ターン境界をマークする責任はあなたにあります。高レベルの便利な方法は次のとおりです： ```python await session.send_audio(audio_bytes, commit=True) ``` -より低レベルの制御が必要な場合は、基盤となるモデル トランスポートを通じて `input_audio_buffer.commit` などの raw クライアントイベントを送信することもできます。 +より低レベルの制御が必要な場合は、基盤となるモデルトランスポートを通じて `input_audio_buffer.commit` などの raw クライアントイベントを送信することもできます。 ### 手動レスポンス制御 -`session.send_message()` は高レベルのパスを使ってユーザー入力を送信し、レスポンスを開始します。raw 音声バッファリングは、すべての設定で **自動的に** 同じことを行うわけではありません。 +`session.send_message()` は高レベルのパスを使ってユーザー入力を送信し、レスポンスを開始します。raw 音声バッファリングは、すべての設定で同じことを自動的に行う **わけではありません**。 -Realtime API レベルでは、手動ターン制御とは raw `session.update` で `turn_detection` をクリアし、その後 `input_audio_buffer.commit` と `response.create` を自分で送信することを意味します。 +Realtime API レベルでは、手動ターン制御とは、raw の `session.update` で `turn_detection` をクリアし、その後 `input_audio_buffer.commit` と `response.create` を自分で送信することを意味します。 -ターンを手動で管理している場合は、モデル トランスポートを通じて raw クライアントイベントを送信できます。 +ターンを手動で管理している場合は、モデルトランスポートを通じて raw クライアントイベントを送信できます： ```python from agents.realtime.model_inputs import RealtimeModelSendRawMessage @@ -153,19 +153,19 @@ await session.model.send_event( ) ``` -このパターンは次の場合に便利です。 +このパターンは次の場合に有用です： - `turn_detection` が無効で、モデルがいつ応答すべきかを自分で決めたい場合 -- レスポンスをトリガーする前にユーザー入力を検査またはゲートしたい場合 -- アウトオブバンドレスポンス用にカスタムプロンプトが必要な場合 +- レスポンスをトリガーする前に、ユーザー入力を検査したり制御したりしたい場合 +- 帯域外レスポンス用のカスタムプロンプトが必要な場合 -[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) の SIP 例では、開始時のあいさつを強制するために raw `response.create` を使用しています。 +[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) の SIP 例では、冒頭の挨拶を強制するために raw の `response.create` を使用しています。 -## イベント、履歴、割り込み +## イベント、履歴、中断 -`RealtimeSession` は、必要に応じて raw モデルイベントも転送しながら、より高レベルの SDK イベントを発行します。 +`RealtimeSession` は、必要に応じて raw モデルイベントも転送しつつ、より高レベルの SDK イベントを発行します。 -価値の高いセッションイベントには次のものがあります。 +特に有用なセッションイベントには次のものがあります： - `audio`, `audio_end`, `audio_interrupted` - `agent_start`, `agent_end` @@ -177,13 +177,13 @@ await session.model.send_event( - `error` - `raw_model_event` -UI 状態に最も役立つイベントは通常、`history_added` と `history_updated` です。これらは、ユーザーメッセージ、アシスタントメッセージ、ツール呼び出しを含む `RealtimeItem` オブジェクトとして、セッションのローカル履歴を公開します。 +UI 状態に最も有用なイベントは通常 `history_added` と `history_updated` です。これらは、ユーザーメッセージ、アシスタントメッセージ、ツール呼び出しを含む、セッションのローカル履歴を `RealtimeItem` オブジェクトとして公開します。 -### 割り込みと再生トラッキング +### 中断と再生追跡 -ユーザーがアシスタントに割り込むと、セッションは `audio_interrupted` を発行し、サーバーサイドの会話がユーザーが実際に聞いた内容と一致するように履歴を更新します。 +ユーザーがアシスタントを中断すると、セッションは `audio_interrupted` を発行し、サーバー側の会話がユーザーが実際に聞いた内容と一致するように履歴を更新します。 -低レイテンシのローカル再生では、デフォルトの再生トラッカーで十分なことが多いです。リモート再生や遅延再生のシナリオ、特に電話では、生成された音声がすべてすでに聞かれたと仮定するのではなく、実際の再生進行に基づいて割り込み時の切り詰めが行われるように [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker] を使用してください。 +低遅延のローカル再生では、デフォルトの再生トラッカーで十分なことが多いです。リモート再生や遅延のある再生シナリオ、特にテレフォニーでは、生成された音声がすべてすでに聞かれたと仮定するのではなく、実際の再生進捗に基づいて中断時の切り詰めが行われるように [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker] を使用してください。 [`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) の Twilio 例は、このパターンを示しています。 @@ -191,7 +191,7 @@ UI 状態に最も役立つイベントは通常、`history_added` と `history_ ### 関数ツール -リアルタイムエージェントは、ライブ会話中に関数ツールをサポートします。 +リアルタイムエージェントは、ライブ会話中に関数ツールをサポートします： ```python from agents import function_tool @@ -212,7 +212,7 @@ agent = RealtimeAgent( ### ツール承認 -関数ツールは、実行前に人間の承認を必要とする場合があります。その場合、セッションは `tool_approval_required` を発行し、`approve_tool_call()` または `reject_tool_call()` を呼び出すまでツール実行を一時停止します。 +関数ツールは、実行前に人間による承認を必要とする場合があります。その場合、セッションは `tool_approval_required` を発行し、`approve_tool_call()` または `reject_tool_call()` を呼び出すまでツール実行を一時停止します。 ```python async for event in session: @@ -220,11 +220,11 @@ async for event in session: await session.approve_tool_call(event.call_id) ``` -具体的なサーバーサイドの承認ループについては、[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) を参照してください。Human-in-the-loop のドキュメントも、[Human in the loop](../human_in_the_loop.md) でこのフローを参照しています。 +具体的なサーバー側の承認ループについては、[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) を参照してください。ヒューマンインザループのドキュメントでも、[ヒューマンインザループ](../human_in_the_loop.md) でこのフローを参照しています。 ### ハンドオフ -リアルタイムハンドオフにより、あるエージェントがライブ会話を別の専門エージェントに転送できます。 +リアルタイムハンドオフにより、あるエージェントがライブ会話を別の専門エージェントへ転送できます： ```python from agents.realtime import RealtimeAgent, realtime_handoff @@ -241,11 +241,11 @@ main_agent = RealtimeAgent( ) ``` -素の `RealtimeAgent` ハンドオフは自動的にラップされ、`realtime_handoff(...)` を使うと名前、説明、検証、コールバック、可用性をカスタマイズできます。リアルタイムハンドオフは、通常のハンドオフ `input_filter` をサポートして **いません**。 +`RealtimeAgent` をそのまま渡すハンドオフは自動的にラップされ、`realtime_handoff(...)` を使うと名前、説明、検証、コールバック、利用可否をカスタマイズできます。リアルタイムハンドオフは通常のハンドオフの `input_filter` をサポートしていません。 ### ガードレール -リアルタイムエージェントでは出力ガードレールのみがサポートされています。これらは部分トークンごとではなく、デバウンスされたトランスクリプト蓄積に対して実行され、例外を発生させる代わりに `guardrail_tripped` を発行します。 +リアルタイムエージェントでサポートされるのは出力ガードレールのみです。これらは部分トークンごとではなく、デバウンスされたトランスクリプトの蓄積に対して実行され、例外を発生させる代わりに `guardrail_tripped` を発行します。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -265,15 +265,17 @@ agent = RealtimeAgent( ) ``` -リアルタイム出力ガードレールが作動すると、セッションはアクティブなレスポンスに割り込み、 -`response.cancel` を強制し、`guardrail_tripped` を発行し、トリガーされたガードレールの名前を含むフォローアップのユーザーメッセージを送信して、モデルが代替レスポンスを生成できるようにします。音声プレーヤーは引き続き -`audio_interrupted` をリッスンし、ローカル再生をただちに停止する必要があります。これは、ガードレールがデバウンスされたトランスクリプトテキストに対して実行され、トリップワイヤーが発火した時点で一部の音声がすでにバッファリングされている可能性があるためです。 +リアルタイム出力ガードレールがトリップすると、セッションはアクティブなレスポンスを中断し、 +`response.cancel` を強制し、`guardrail_tripped` を発行し、トリガーされた +ガードレールの名前を含むフォローアップのユーザーメッセージを送信するため、モデルは代替レスポンスを生成できます。音声プレイヤーは引き続き +`audio_interrupted` をリッスンしてローカル再生を即座に停止する必要があります。これは、ガードレールが +デバウンスされたトランスクリプトテキストに対して実行され、トリップワイヤーが発火した時点で一部の音声がすでにバッファリングされている可能性があるためです。 -## SIP と電話 +## SIP とテレフォニー Python SDK には、[`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] によるファーストクラスの SIP アタッチフローが含まれています。 -Realtime Calls API 経由で通話が到着し、結果として得られる `call_id` にエージェントセッションをアタッチしたい場合に使用します。 +Realtime Calls API 経由で着信があり、生成された `call_id` にエージェントセッションをアタッチしたい場合に使用します： ```python from agents.realtime import RealtimeRunner @@ -290,20 +292,20 @@ async with await runner.run( ... ``` -最初に通話を受け入れる必要があり、受け入れペイロードをエージェント由来のセッション設定と一致させたい場合は、`OpenAIRealtimeSIPModel.build_initial_session_payload(...)` を使用してください。完全なフローは [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) に示されています。 +最初に通話を受け入れる必要があり、accept ペイロードをエージェントから導出されたセッション設定と一致させたい場合は、`OpenAIRealtimeSIPModel.build_initial_session_payload(...)` を使用してください。完全なフローは [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) に示されています。 ## 低レベルアクセスとカスタムエンドポイント `session.model` を通じて基盤となるトランスポートオブジェクトにアクセスできます。 -これは次の場合に使用します。 +次が必要な場合に使用します： - `session.model.add_listener(...)` によるカスタムリスナー - `response.create` や `session.update` などの raw クライアントイベント -- `model_config` を通じたカスタム `url`、`headers`、または `api_key` の処理 +- `model_config` を通じたカスタムの `url`、`headers`、`api_key` 処理 - 既存のリアルタイム通話への `call_id` アタッチ -`RealtimeModelConfig` は次をサポートします。 +`RealtimeModelConfig` は次をサポートします： - `api_key` - `url` @@ -312,9 +314,9 @@ async with await runner.run( - `playback_tracker` - `call_id` -このリポジトリに同梱されている `call_id` 例は SIP です。より広範な Realtime API でも、一部のサーバーサイド制御フローで `call_id` を使用しますが、それらはここでは Python 例としてパッケージ化されていません。 +このリポジトリに同梱されている `call_id` の例は SIP です。より広範な Realtime API でも、一部のサーバー側制御フローで `call_id` が使用されますが、ここではそれらは Python のコード例としてパッケージ化されていません。 -Azure OpenAI に接続する場合は、GA Realtime エンドポイント URL と明示的なヘッダーを渡します。例: +Azure OpenAI に接続する場合は、GA Realtime エンドポイント URL と明示的なヘッダーを渡してください。例： ```python session = await runner.run( @@ -325,7 +327,7 @@ session = await runner.run( ) ``` -トークンベース認証では、`headers` に bearer トークンを使用します。 +トークンベースの認証では、`headers` にベアラートークンを使用します： ```python session = await runner.run( @@ -336,12 +338,12 @@ session = await runner.run( ) ``` -`headers` を渡した場合、SDK は `Authorization` を自動的に追加しません。リアルタイムエージェントでは、レガシーのベータパス (`/openai/realtime?api-version=...`) を避けてください。 +`headers` を渡した場合、SDK は `Authorization` を自動的に追加しません。リアルタイムエージェントでは、従来のベータパス（`/openai/realtime?api-version=...`）を避けてください。 -## 関連資料 +## 参考資料 -- [リアルタイムトランスポート](transport.md) +- [Realtime トランスポート](transport.md) - [クイックスタート](quickstart.md) - [OpenAI Realtime 会話](https://developers.openai.com/api/docs/guides/realtime-conversations/) -- [OpenAI Realtime サーバーサイド制御](https://developers.openai.com/api/docs/guides/realtime-server-controls/) +- [OpenAI Realtime サーバー側制御](https://developers.openai.com/api/docs/guides/realtime-server-controls/) - [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) \ No newline at end of file diff --git a/docs/ja/realtime/quickstart.md b/docs/ja/realtime/quickstart.md index cca5137017..88cb9478ab 100644 --- a/docs/ja/realtime/quickstart.md +++ b/docs/ja/realtime/quickstart.md @@ -4,33 +4,33 @@ search: --- # クイックスタート -Python SDK の Realtime エージェントは、WebSocket トランスポート上の OpenAI Realtime API を基盤とした、サーバー側の低レイテンシーなエージェントです。 +Python SDK のリアルタイムエージェントは、 WebSocket トランスポート経由の OpenAI Realtime API を基盤とする、サーバー側の低レイテンシエージェントです。 !!! warning "ベータ機能" - Realtime エージェントはベータ版です。実装の改善に伴い、破壊的変更が発生する可能性があります。 + リアルタイムエージェントはベータ版です。実装を改善していく中で、破壊的変更が発生する可能性があります。 !!! note "Python SDK の範囲" - Python SDK はブラウザー WebRTC トランスポートを提供 **しません**。このページでは、サーバー側 WebSocket による Python 管理の Realtime セッションのみを扱います。この SDK は、サーバー側のオーケストレーション、ツール、承認、電話連携に使用してください。[Realtime トランスポート](transport.md)も参照してください。 + Python SDK はブラウザー向け WebRTC トランスポートを **提供しません** 。このページでは、サーバー側 WebSocket 上で Python が管理するリアルタイムセッションのみを扱います。この SDK は、サーバー側のオーケストレーション、ツール、承認、テレフォニー連携に使用してください。[リアルタイムトランスポート](transport.md) も参照してください。 ## 前提条件 - Python 3.10 以上 - OpenAI API キー -- OpenAI Agents SDK の基本的な知識 +- OpenAI Agents SDK に関する基本的な知識 ## インストール -まだの場合は、OpenAI Agents SDK をインストールしてください。 +まだの場合は、 OpenAI Agents SDK をインストールしてください: ```bash pip install openai-agents ``` -## サーバー側 Realtime セッションの作成 +## サーバー側リアルタイムセッションの作成 -### 1. Realtime コンポーネントのインポート +### 1. リアルタイムコンポーネントのインポート ```python import asyncio @@ -38,7 +38,7 @@ import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner ``` -### 2. 開始エージェントの定義 +### 2. 開始時のエージェントの定義 ```python agent = RealtimeAgent( @@ -47,9 +47,9 @@ agent = RealtimeAgent( ) ``` -### 3. runner の設定 +### 3. ランナーの設定 -新しいコードでは、ネストされた `audio.input` / `audio.output` セッション設定形式を使用することを推奨します。新しい Realtime エージェントでは、`gpt-realtime-2` から始めてください。 +新しいコードでは、ネストされた `audio.input` / `audio.output` のセッション設定形式を推奨します。新しいリアルタイムエージェントでは、 `gpt-realtime-2` から始めてください。 ```python runner = RealtimeRunner( @@ -104,59 +104,59 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`session.send_message()` はプレーンな文字列、または構造化された Realtime メッセージのいずれかを受け取ります。raw 音声チャンクには、[`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用してください。 +`session.send_message()` は、プレーンな文字列または構造化されたリアルタイムメッセージを受け付けます。未加工の音声チャンクには、 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用してください。 ## このクイックスタートに含まれない内容 -- マイク入力とスピーカー再生のコード。[`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) の Realtime コード例を参照してください。 -- SIP / 電話のアタッチフロー。[Realtime トランスポート](transport.md)および [SIP セクション](guide.md#sip-and-telephony)を参照してください。 +- マイクキャプチャとスピーカー再生のコード。リアルタイムのコード例については、 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。 +- SIP / テレフォニーのアタッチフロー。[リアルタイムトランスポート](transport.md) と [SIP セクション](guide.md#sip-and-telephony) を参照してください。 ## 主要設定 -基本的なセッションが動作したら、多くの人が次に扱う設定は次のとおりです。 +基本的なセッションが動作したら、多くの方が次に利用する設定は次のとおりです: - `model_name` - `audio.input.format`, `audio.output.format` - `audio.input.transcription` - `audio.input.noise_reduction` -- 自動ターン検出のための `audio.input.turn_detection` +- 自動ターン検出用の `audio.input.turn_detection` - `audio.output.voice` - `tool_choice`, `prompt`, `tracing` - `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter` -`input_audio_format`, `output_audio_format`, `input_audio_transcription`, `turn_detection` などの古いフラットなエイリアスも引き続き動作しますが、新しいコードではネストされた `audio` 設定が推奨されます。 +`input_audio_format`、`output_audio_format`、`input_audio_transcription`、`turn_detection` などの古いフラットなエイリアスも引き続き機能しますが、新しいコードではネストされた `audio` 設定を推奨します。 -手動でターンを制御するには、[Realtime エージェントガイド](guide.md#manual-response-control)で説明されている raw の `session.update` / `input_audio_buffer.commit` / `response.create` フローを使用してください。 +手動のターン制御では、 [リアルタイムエージェントガイド](guide.md#manual-response-control) で説明されているように、 raw な `session.update` / `input_audio_buffer.commit` / `response.create` フローを使用してください。 -完全なスキーマについては、[`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] および [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。 +完全なスキーマについては、 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。 ## 接続オプション -API キーを環境に設定します。 +環境で API キーを設定します: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -または、セッション開始時に直接渡します。 +または、セッションの開始時に直接渡します: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) ``` -`model_config` は次もサポートします。 +`model_config` は以下もサポートしています: - `url`: カスタム WebSocket エンドポイント - `headers`: カスタムリクエストヘッダー -- `call_id`: 既存の Realtime 呼び出しにアタッチします。このリポジトリでは、文書化されているアタッチフローは SIP です。 -- `playback_tracker`: ユーザーが実際に聞いた音声量を報告します +- `call_id`: 既存のリアルタイム通話にアタッチします。このリポジトリでは、ドキュメント化されているアタッチフローは SIP です。 +- `playback_tracker`: ユーザーが実際に聞いた音声の量を報告します -`headers` を明示的に渡した場合、SDK は `Authorization` ヘッダーを自動で注入 **しません**。 +`headers` を明示的に渡す場合、 SDK は `Authorization` ヘッダーを **挿入しません** 。 -Azure OpenAI に接続する場合は、`model_config["url"]` に GA Realtime エンドポイント URL と明示的なヘッダーを渡してください。Realtime エージェントでは、従来のベータパス（`/openai/realtime?api-version=...`）は避けてください。詳細は [Realtime エージェントガイド](guide.md#low-level-access-and-custom-endpoints)を参照してください。 +Azure OpenAI に接続する場合は、 `model_config["url"]` に GA Realtime エンドポイント URL を指定し、ヘッダーを明示的に渡してください。リアルタイムエージェントでは、レガシーのベータパス (`/openai/realtime?api-version=...`) は避けてください。詳細は [リアルタイムエージェントガイド](guide.md#low-level-access-and-custom-endpoints) を参照してください。 ## 次のステップ -- [Realtime トランスポート](transport.md)を読み、サーバー側 WebSocket と SIP のどちらを使用するかを選択してください。 -- ライフサイクル、構造化入力、承認、ハンドオフ、ガードレール、低レベル制御については、[Realtime エージェントガイド](guide.md)を読んでください。 +- サーバー側 WebSocket と SIP のどちらを選ぶかについては、 [リアルタイムトランスポート](transport.md) をお読みください。 +- ライフサイクル、構造化入力、承認、ハンドオフ、ガードレール、低レベル制御については、 [リアルタイムエージェントガイド](guide.md) をお読みください。 - [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) のコード例を参照してください。 \ No newline at end of file diff --git a/docs/ja/realtime/transport.md b/docs/ja/realtime/transport.md index 39f665124b..520995c08a 100644 --- a/docs/ja/realtime/transport.md +++ b/docs/ja/realtime/transport.md @@ -4,32 +4,32 @@ search: --- # Realtime トランスポート -このページは、realtime エージェントを Python アプリケーションにどのように組み込むかを判断するために使用します。 +このページは、realtime エージェントを Python アプリケーションにどのように組み込むかを判断するために使用してください。 !!! note "Python SDK の境界" - Python SDK にはブラウザー WebRTC トランスポートは **含まれていません** 。このページは Python SDK のトランスポート選択、つまりサーバーサイド WebSocket と SIP アタッチフローのみを対象としています。ブラウザー WebRTC は別のプラットフォームトピックであり、公式の [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) ガイドに記載されています。 + Python SDK には、ブラウザー WebRTC トランスポートは含まれて **いません**。このページは、Python SDK のトランスポート選択肢であるサーバー側 WebSocket と SIP アタッチフローのみを扱います。ブラウザー WebRTC は別のプラットフォームトピックであり、公式の [WebRTC による Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) ガイドに記載されています。 ## 判断ガイド -| Goal | Start with | Why | +| 目的 | はじめに | 理由 | | --- | --- | --- | -| サーバー管理の realtime アプリを構築する | [Quickstart](quickstart.md) | デフォルトの Python パスは、`RealtimeRunner` で管理されるサーバーサイド WebSocket セッションです。 | -| どのトランスポートとデプロイ形状を選ぶべきか理解する | このページ | トランスポートやデプロイ形状を確定する前に、このページを使用してください。 | -| エージェントを電話または SIP 通話にアタッチする | [Realtime guide](guide.md) と [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | このリポジトリには、`call_id` で駆動する SIP アタッチフローが含まれています。 | +| サーバー管理の realtime アプリを構築する | [クイックスタート](quickstart.md) | デフォルトの Python パスは、`RealtimeRunner` によって管理されるサーバー側 WebSocket セッションです。 | +| 選択すべきトランスポートとデプロイ形態を理解する | このページ | トランスポートやデプロイ形態を決定する前に使用してください。 | +| エージェントを電話または SIP 通話にアタッチする | [Realtime ガイド](guide.md) と [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | このリポジトリには、`call_id` によって駆動される SIP アタッチフローが含まれています。 | -## サーバーサイド WebSocket というデフォルトの Python パス +## デフォルトの Python パスであるサーバー側 WebSocket -`RealtimeRunner` は、カスタム `RealtimeModel` を渡さない限り `OpenAIRealtimeWebSocketModel` を使用します。 +カスタム `RealtimeModel` を渡さない限り、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用します。 つまり、標準的な Python トポロジーは次のようになります。 1. Python サービスが `RealtimeRunner` を作成します。 -2. `await runner.run()` は `RealtimeSession` を返します。 +2. `await runner.run()` が `RealtimeSession` を返します。 3. セッションに入り、テキスト、構造化メッセージ、または音声を送信します。 4. `RealtimeSessionEvent` 項目を消費し、音声またはトランスクリプトをアプリケーションに転送します。 -このトポロジーは、コアデモアプリ、CLI 例、Twilio Media Streams 例で使用されています。 +これは、コアデモアプリ、CLI の例、Twilio Media Streams の例で使用されているトポロジーです。 - [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app) - [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli) @@ -37,40 +37,40 @@ search: サーバーが音声パイプライン、ツール実行、承認フロー、履歴処理を管理する場合は、このパスを使用してください。 -## SIP アタッチというテレフォニーパス +## テレフォニー向けパスとしての SIP アタッチ -このリポジトリで文書化されているテレフォニーフローでは、Python SDK は `call_id` を介して既存の realtime 通話にアタッチします。 +このリポジトリで説明されているテレフォニーフローでは、Python SDK は `call_id` を介して既存の realtime 通話にアタッチします。 このトポロジーは次のようになります。 1. OpenAI が `realtime.call.incoming` などの webhook をサービスに送信します。 -2. サービスが Realtime Calls API を通じて通話を受け付けます。 +2. サービスが Realtime Calls API を通じて通話を受け入れます。 3. Python サービスが `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())` を開始します。 4. セッションは `model_config={"call_id": ...}` で接続し、その後は他の realtime セッションと同様にイベントを処理します。 -これは [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) で示されているトポロジーです。 +これは [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) に示されているトポロジーです。 -より広い Realtime API でも一部のサーバーサイド制御パターンで `call_id` を使用しますが、このリポジトリで提供されているアタッチ例は SIP です。 +より広範な Realtime API でも、一部のサーバー側制御パターンで `call_id` を使用しますが、このリポジトリに含まれるアタッチ例は SIP です。 -## この SDK の対象外であるブラウザー WebRTC +## この SDK の範囲外であるブラウザー WebRTC -アプリの主要クライアントが Realtime WebRTC を使用するブラウザーである場合: +アプリの主なクライアントが Realtime WebRTC を使用するブラウザーである場合: -- このリポジトリの Python SDK ドキュメントの対象外として扱ってください。 -- クライアントサイドフローとイベントモデルについては、公式の [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) と [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) のドキュメントを使用してください。 -- ブラウザー WebRTC クライアントに加えてサイドバンドのサーバー接続が必要な場合は、公式の [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) ガイドを使用してください。 -- このリポジトリがブラウザーサイド `RTCPeerConnection` 抽象化や、すぐに使えるブラウザー WebRTC サンプルを提供することは期待しないでください。 +- このリポジトリの Python SDK ドキュメントの範囲外として扱ってください。 +- クライアント側のフローとイベントモデルについては、公式の [WebRTC による Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) および [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) ドキュメントを使用してください。 +- ブラウザー WebRTC クライアントの上にサイドバンドのサーバー接続が必要な場合は、公式の [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) ガイドを使用してください。 +- このリポジトリが、ブラウザー側の `RTCPeerConnection` 抽象化や、すぐに使えるブラウザー WebRTC サンプルを提供することは期待しないでください。 -このリポジトリには現在、ブラウザー WebRTC と Python サイドバンドを組み合わせた例も含まれていません。 +このリポジトリには、現在、ブラウザー WebRTC と Python サイドバンドを組み合わせた例も含まれていません。 ## カスタムエンドポイントとアタッチポイント -[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] のトランスポート設定インターフェースにより、デフォルトパスを調整できます。 +[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] のトランスポート設定サーフェスを使用すると、デフォルトのパスを調整できます。 - `url`: WebSocket エンドポイントを上書きします -- `headers`: Azure 認証ヘッダーなどの明示的なヘッダーを提供します +- `headers`: Azure 認証ヘッダーなどの明示的なヘッダーを指定します - `api_key`: API キーを直接、またはコールバック経由で渡します -- `call_id`: 既存の realtime 通話にアタッチします。このリポジトリで文書化されている例は SIP です。 -- `playback_tracker`: 割り込み処理のために実際の再生進行を報告します +- `call_id`: 既存の realtime 通話にアタッチします。このリポジトリで記載されている例は SIP です。 +- `playback_tracker`: 割り込み処理のために実際の再生進捗を報告します -トポロジーを選択した後の詳細なライフサイクルと機能インターフェースについては、[Realtime agents guide](guide.md) を参照してください。 \ No newline at end of file +トポロジーを選択した後の詳細なライフサイクルと機能サーフェスについては、[Realtime エージェントガイド](guide.md) を参照してください。 \ No newline at end of file diff --git a/docs/ja/release.md b/docs/ja/release.md index 43100be96e..0dca5c12cb 100644 --- a/docs/ja/release.md +++ b/docs/ja/release.md @@ -4,30 +4,30 @@ search: --- # リリースプロセス / 変更履歴 -このプロジェクトは、`0.Y.Z` という形式を用いた、セマンティックバージョニングを少し変更した方式に従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各コンポーネントは次のように増やします。 +このプロジェクトは、形式 `0.Y.Z` を使用するセマンティックバージョニングを少し修正したものに従います。先頭の `0` は、SDK がまだ急速に進化中であることを示します。各構成要素は次のように増加させます: -## マイナー（`Y`）バージョン +## マイナー (`Y`) バージョン -beta としてマークされていない公開インターフェイスに対する **破壊的変更** がある場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には、破壊的変更が含まれる可能性があります。 +ベータとしてマークされていない公開インターフェイスに対する **破壊的変更** の場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる可能性があります。 -破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することを推奨します。 +破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。 -## パッチ（`Z`）バージョン +## パッチ (`Z`) バージョン -非破壊的な変更では `Z` を増やします。 +非破壊的変更の場合は `Z` を増やします: -- バグ修正 -- 新機能 -- private インターフェイスへの変更 -- beta 機能の更新 +- バグ修正 +- 新機能 +- 非公開インターフェイスの変更 +- ベータ機能の更新 ## 破壊的変更の変更履歴 ### 0.17.0 -このバージョンでは、sandbox のローカルソースの materialization において、ソースパスが `Manifest.extra_path_grants` で対象に含まれていない限り、`LocalFile.src` と `LocalDir.src` は materialization の `base_dir` 内に保持されます。`base_dir` は manifest が適用されるときの SDK プロセスの現在の作業ディレクトリです。相対ローカルソースはそのディレクトリから解決され、一方で絶対ローカルソースは、すでにその中にあるか、明示的な grant の配下にある必要があります。これによりローカル artifact の境界に関する問題は解消されますが、そのベースディレクトリの外にある信頼済みのホストファイルやディレクトリを sandbox ワークスペースへ意図的にコピーするアプリケーションに影響する可能性があります。 +このバージョンでは、サンドボックスのローカルソースの実体化において、ソースパスが `Manifest.extra_path_grants` によってカバーされていない限り、`LocalFile.src` と `LocalDir.src` は実体化時の `base_dir` 内に収められます。`base_dir` は、マニフェストが適用される時点での SDK プロセスの現在の作業ディレクトリです。相対ローカルソースはそのディレクトリから解決され、絶対ローカルソースはすでにそのディレクトリ内にあるか、明示的な許可の配下にある必要があります。これによりローカルアーティファクトの境界に関する問題は解消されますが、そのベースディレクトリ外から信頼済みホストのファイルまたはディレクトリをサンドボックスワークスペースへ意図的にコピーするアプリケーションに影響する可能性があります。 -移行するには、manifest レベルで `SandboxPathGrant` を使って信頼済みのホスト root を許可してください。sandbox がそれらのファイルを読み取るだけでよい場合は、読み取り専用にすることが望ましいです。 +移行するには、信頼済みホストルートをマニフェストレベルで `SandboxPathGrant` により許可してください。サンドボックスがそれらのファイルを読み取るだけでよい場合は、読み取り専用にすることをおすすめします: ```python from pathlib import Path @@ -54,28 +54,28 @@ manifest = Manifest( ) ``` -`extra_path_grants` は、信頼済みのアプリケーション設定として扱ってください。アプリケーションがそれらのホストパスをすでに承認していない限り、モデル出力やその他の信頼できない manifest 入力から grant を設定しないでください。 +`extra_path_grants` は信頼済みアプリケーション設定として扱ってください。アプリケーションがそれらのホストパスをすでに承認していない限り、モデル出力やその他の信頼できないマニフェスト入力から許可を設定しないでください。 ### 0.16.0 -このバージョンでは、SDK のデフォルトモデルが `gpt-4.1` ではなく `gpt-5.4-mini` になりました。これは、モデルを明示的に設定していないエージェントと run に影響します。新しいデフォルトは GPT-5 モデルであるため、暗黙のデフォルトモデル設定には `reasoning.effort="none"` や `verbosity="low"` などの GPT-5 のデフォルトが含まれるようになりました。 +このバージョンでは、SDK のデフォルトモデルが `gpt-4.1` ではなく `gpt-5.4-mini` になりました。これは、モデルを明示的に設定していないエージェントと実行に影響します。新しいデフォルトは GPT-5 モデルであるため、暗黙的なデフォルトモデル設定には `reasoning.effort="none"` や `verbosity="low"` などの GPT-5 デフォルトが含まれるようになりました。 -以前のデフォルトモデルの挙動を維持する必要がある場合は、エージェントまたは run config にモデルを明示的に設定するか、`OPENAI_DEFAULT_MODEL` 環境変数を設定してください。 +以前のデフォルトモデルの挙動を維持する必要がある場合は、エージェントまたは実行設定でモデルを明示的に設定するか、`OPENAI_DEFAULT_MODEL` 環境変数を設定してください: ```python agent = Agent(name="Assistant", model="gpt-4.1") ``` -ハイライト: +主な変更点: -- `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` は、ターン制限を無効化するために `max_turns=None` を受け付けるようになりました。 -- sandbox ワークスペースの hydration は、ローカル、Docker、およびプロバイダーが支援する sandbox 実装全体で、絶対 symlink ターゲットを含め、アーカイブ root の外を指す symlink を含む tar アーカイブを拒否するようになりました。 +- `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` は、ターン制限を無効にするために `max_turns=None` を受け取れるようになりました。 +- サンドボックスワークスペースのハイドレーションは、ローカル、Docker、およびプロバイダーがバックするサンドボックス実装全体で、絶対シンボリックリンクターゲットを含む、アーカイブルートの外部を指すシンボリックリンクを含む tar アーカイブを拒否するようになりました。 ### 0.15.0 -このバージョンでは、モデルの拒否が、空のテキスト出力として扱われたり、structured outputs の場合に `MaxTurnsExceeded` になるまで run ループでリトライされるのではなく、`ModelRefusalError` として明示的に表面化されるようになりました。 +このバージョンでは、モデルの拒否応答は、空のテキスト出力として扱われたり、structured outputs の場合に実行ループが `MaxTurnsExceeded` まで再試行したりするのではなく、`ModelRefusalError` として明示的に表面化されるようになりました。 -これは、以前は拒否のみのモデル応答が `final_output == ""` で完了することを期待していたコードに影響します。例外を発生させずに拒否を処理するには、`model_refusal` run error handler を提供してください。 +これは、以前に拒否のみのモデル応答が `final_output == ""` で完了することを期待していたコードに影響します。例外を発生させずに拒否を処理するには、`model_refusal` 実行エラーハンドラーを提供してください: ```python result = Runner.run_sync( @@ -85,81 +85,81 @@ result = Runner.run_sync( ) ``` -structured-output エージェントでは、handler はエージェントの出力スキーマに一致する値を返すことができ、SDK は他の run error handler の最終出力と同様に検証します。 +structured-output エージェントの場合、ハンドラーはエージェントの出力スキーマに一致する値を返すことができ、SDK は他の実行エラーハンドラーの最終出力と同様に検証します。 ### 0.14.0 -このマイナーリリースでは破壊的変更は導入 **されません** が、大きな新しい beta 機能領域である Sandbox Agents と、それらをローカル、コンテナ化、ホスト環境全体で使用するために必要なランタイム、バックエンド、ドキュメントサポートが追加されています。 +このマイナーリリースでは、破壊的変更は **導入しません** が、主要な新しいベータ機能領域である Sandbox エージェントに加え、ローカル、コンテナ化、ホスト環境全体でそれらを使用するために必要なランタイム、バックエンド、ドキュメントのサポートが追加されています。 -ハイライト: +主な変更点: -- `SandboxAgent`、`Manifest`、`SandboxRunConfig` を中心とする新しい beta sandbox ランタイムサーフェスを追加し、エージェントがファイル、ディレクトリ、Git リポジトリ、マウント、スナップショット、resume サポートを備えた永続的に分離されたワークスペース内で作業できるようにしました。 -- `UnixLocalSandboxClient` と `DockerSandboxClient` によるローカルおよびコンテナ化開発向けの sandbox 実行バックエンドに加え、optional extras を通じて Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 向けのホスト型プロバイダー連携を追加しました。 -- 将来の run が過去の run から得た教訓を再利用できるようにする sandbox メモリサポートを追加しました。progressive disclosure、multi-turn grouping、設定可能な分離境界、S3 backed ワークフローを含む永続化メモリのコード例が含まれます。 -- ローカルおよび合成ワークスペースエントリ、S3/R2/GCS/Azure Blob Storage/S3 Files 向けのリモートストレージマウント、ポータブルスナップショット、`RunState`、`SandboxSessionState`、または保存済みスナップショットによる resume フローを含む、より広範なワークスペースおよび resume モデルを追加しました。 -- `examples/sandbox/` 配下に、skills、ハンドオフ、メモリ、プロバイダー固有のセットアップを用いたコーディングタスク、およびコードレビュー、dataroom QA、Web サイトクローンなどのエンドツーエンドワークフローを扱う、実質的な sandbox のコード例とチュートリアルを追加しました。 -- sandbox 対応の session 準備、capability binding、状態シリアライズ、統合トレーシング、prompt cache key のデフォルト、より安全な機密 MCP 出力の redaction により、コアランタイムとトレーシングスタックを拡張しました。 +- `SandboxAgent`、`Manifest`、`SandboxRunConfig` を中心とした新しいベータのサンドボックスランタイムサーフェスを追加しました。これにより、エージェントはファイル、ディレクトリ、Git リポジトリ、マウント、スナップショット、再開サポートを備えた永続的な隔離ワークスペース内で動作できます。 +- `UnixLocalSandboxClient` と `DockerSandboxClient` によるローカルおよびコンテナ化開発向けのサンドボックス実行バックエンドに加え、任意の extras を通じた Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 向けのホスト型プロバイダー連携を追加しました。 +- 将来の実行が以前の実行から得た知見を再利用できるように、サンドボックスメモリサポートを追加しました。段階的開示、複数ターンのグループ化、設定可能な隔離境界、および S3 バックのワークフローを含む永続化メモリのコード例が含まれます。 +- ローカルおよび合成ワークスペースエントリー、S3/R2/GCS/Azure Blob Storage/S3 Files 向けのリモートストレージマウント、移植可能なスナップショット、`RunState`、`SandboxSessionState`、または保存済みスナップショットによる再開フローを含む、より広範なワークスペースと再開モデルを追加しました。 +- `examples/sandbox/` 配下に、充実したサンドボックスのコード例とチュートリアルを追加しました。スキル、ハンドオフ、メモリを用いたコーディングタスク、プロバイダー固有のセットアップ、コードレビュー、データルーム QA、Web サイトのクローン作成などのエンドツーエンドのワークフローを扱います。 +- サンドボックス対応のセッション準備、ケイパビリティバインディング、状態のシリアライズ、統合トレーシング、プロンプトキャッシュキーのデフォルト、より安全な機密 MCP 出力のマスキングにより、コアランタイムとトレーシングスタックを拡張しました。 ### 0.13.0 -このマイナーリリースでは破壊的変更は導入 **されません** が、注目すべき Realtime のデフォルト更新に加え、新しい MCP 機能とランタイム安定性の修正が含まれています。 +このマイナーリリースでは、破壊的変更は **導入しません** が、注目すべき Realtime のデフォルト更新に加え、新しい MCP 機能とランタイム安定性の修正が含まれます。 -ハイライト: +主な変更点: -- デフォルトの websocket Realtime モデルは `gpt-realtime-1.5` になりました。これにより、新しい Realtime エージェントのセットアップでは追加設定なしでより新しいモデルが使用されます。 -- `MCPServer` は `list_resources()`、`list_resource_templates()`、`read_resource()` を公開するようになり、`MCPServerStreamableHttp` は `session_id` を公開するようになりました。これにより、streamable HTTP セッションを再接続やステートレス worker 間で再開できます。 -- Chat Completions 連携では、`should_replay_reasoning_content` によって reasoning-content replay を opt in できるようになり、LiteLLM/DeepSeek などの adapter におけるプロバイダー固有の reasoning/tool-call の継続性が改善されます。 -- `SQLAlchemySession` における同時初回書き込み、reasoning stripping 後に孤立した assistant message ID を持つ compaction request、`remove_all_tools()` が MCP/reasoning item を残す問題、関数ツール batch executor の race など、いくつかのランタイムと session の edge case を修正しました。 +- デフォルトの WebSocket Realtime モデルは `gpt-realtime-1.5` になりました。そのため、新しい Realtime エージェントのセットアップでは、追加設定なしで新しいモデルが使用されます。 +- `MCPServer` は `list_resources()`、`list_resource_templates()`、`read_resource()` を公開するようになりました。また、`MCPServerStreamableHttp` は `session_id` を公開するようになったため、ストリーム可能な HTTP セッションを再接続やステートレスワーカーをまたいで再開できます。 +- Chat Completions 連携は、`should_replay_reasoning_content` によって推論コンテンツの再生をオプトインできるようになりました。これにより、LiteLLM/DeepSeek などのアダプターで、プロバイダー固有の推論 / ツール呼び出しの連続性が向上します。 +- `SQLAlchemySession` における初回書き込みの同時実行、推論の除去後に孤立した assistant メッセージ ID を持つ圧縮リクエスト、`remove_all_tools()` が MCP/reasoning 項目を残す問題、関数ツールバッチ実行器の競合など、複数のランタイムおよびセッションのエッジケースを修正しました。 ### 0.12.0 -このマイナーリリースでは破壊的変更は導入 **されません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)を確認してください。 +このマイナーリリースでは、破壊的変更は **導入しません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)を確認してください。 ### 0.11.0 -このマイナーリリースでは破壊的変更は導入 **されません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)を確認してください。 +このマイナーリリースでは、破壊的変更は **導入しません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)を確認してください。 ### 0.10.0 -このマイナーリリースでは破壊的変更は導入 **されません** が、OpenAI Responses ユーザー向けの重要な新機能領域である、Responses API の websocket transport サポートが含まれています。 +このマイナーリリースでは、破壊的変更は **導入しません** が、OpenAI Responses ユーザー向けの重要な新機能領域である Responses API の WebSocket トランスポートサポートが含まれます。 -ハイライト: +主な変更点: -- OpenAI Responses モデル向けの websocket transport サポートを追加しました（opt-in。HTTP は引き続きデフォルトの transport です）。 -- 共有の websocket 対応プロバイダーと `RunConfig` を複数ターンの run で再利用するための `responses_websocket_session()` helper / `ResponsesWebSocketSession` を追加しました。 -- ストリーミング、ツール、承認、フォローアップターンを扱う新しい websocket ストリーミングコード例（`examples/basic/stream_ws.py`）を追加しました。 +- OpenAI Responses モデル向けの WebSocket トランスポートサポートを追加しました（オプトインです。HTTP は引き続きデフォルトのトランスポートです）。 +- 複数ターンの実行全体で共有の WebSocket 対応プロバイダーと `RunConfig` を再利用するための `responses_websocket_session()` ヘルパー / `ResponsesWebSocketSession` を追加しました。 +- ストリーミング、ツール、承認、フォローアップターンを扱う新しい WebSocket ストリーミングコード例（`examples/basic/stream_ws.py`）を追加しました。 ### 0.9.0 -このバージョンでは、Python 3.9 はサポートされなくなりました。このメジャーバージョンは 3 か月前に EOL に達したためです。より新しいランタイムバージョンへアップグレードしてください。 +このバージョンでは、このメジャーバージョンが 3 か月前に EOL に達したため、Python 3.9 はサポートされなくなりました。より新しいランタイムバージョンへアップグレードしてください。 -さらに、`Agent#as_tool()` メソッドから返される値の型ヒントが、`Tool` から `FunctionTool` に狭められました。この変更は通常、破壊的な問題を引き起こすことはありませんが、コードがより広い union 型に依存している場合は、側でいくつか調整が必要になる場合があります。 +さらに、`Agent#as_tool()` メソッドから返される値の型ヒントが、`Tool` から `FunctionTool` へ狭められました。この変更は通常、破壊的な問題を引き起こすことはありませんが、コードがより広い Union 型に依存している場合は、側でいくつか調整が必要になる可能性があります。 ### 0.8.0 -このバージョンでは、2 つのランタイム挙動の変更により、移行作業が必要になる場合があります。 +このバージョンでは、2 つのランタイム挙動の変更により、移行作業が必要になる可能性があります: -- **同期** Python callable をラップする関数ツールは、イベントループスレッド上で実行されるのではなく、`asyncio.to_thread(...)` を介して worker thread 上で実行されるようになりました。ツールロジックが thread-local state や thread-affine resource に依存している場合は、async tool 実装へ移行するか、ツールコード内で thread affinity を明示してください。 -- ローカル MCP ツールの失敗処理は設定可能になり、デフォルトの挙動では run 全体を失敗させる代わりに、モデルから見えるエラー出力を返す場合があります。fail-fast semantics に依存している場合は、`mcp_config={"failure_error_function": None}` を設定してください。サーバーレベルの `failure_error_function` 値はエージェントレベルの設定を上書きするため、明示的な handler を持つ各ローカル MCP サーバーで `failure_error_function=None` を設定してください。 +- **同期** Python 呼び出し可能オブジェクトをラップする関数ツールは、イベントループスレッドで実行されるのではなく、`asyncio.to_thread(...)` を介してワーカースレッドで実行されるようになりました。ツールのロジックがスレッドローカル状態やスレッドアフィンなリソースに依存している場合は、async ツール実装へ移行するか、ツールコード内でスレッドアフィニティを明示してください。 +- ローカル MCP ツールの失敗処理は設定可能になり、デフォルトの挙動では実行全体を失敗させる代わりに、モデルから見えるエラー出力を返す場合があります。フェイルファストのセマンティクスに依存している場合は、`mcp_config={"failure_error_function": None}` を設定してください。サーバーレベルの `failure_error_function` 値はエージェントレベルの設定を上書きするため、明示的なハンドラーを持つ各ローカル MCP サーバーで `failure_error_function=None` を設定してください。 ### 0.7.0 -このバージョンでは、既存のアプリケーションに影響する可能性がある挙動変更がいくつかありました。 +このバージョンでは、既存のアプリケーションに影響する可能性がある挙動の変更がいくつかありました: -- ネストされたハンドオフ履歴は **opt-in**（デフォルトでは無効）になりました。v0.6.x のデフォルトのネスト挙動に依存していた場合は、`RunConfig(nest_handoff_history=True)` を明示的に設定してください。 -- `gpt-5.1` / `gpt-5.2` のデフォルトの `reasoning.effort` が `"none"` に変更されました（以前は SDK のデフォルトで設定された `"low"` がデフォルトでした）。プロンプトや品質 / コストプロファイルが `"low"` に依存していた場合は、`model_settings` で明示的に設定してください。 +- ネストされたハンドオフ履歴は **オプトイン** になりました（デフォルトでは無効）。v0.6.x のデフォルトのネスト挙動に依存していた場合は、`RunConfig(nest_handoff_history=True)` を明示的に設定してください。 +- `gpt-5.1` / `gpt-5.2` のデフォルトの `reasoning.effort` は、`"none"` に変更されました（SDK デフォルトで設定されていた以前のデフォルト `"low"` からの変更です）。プロンプトや品質 / コストのプロファイルが `"low"` に依存していた場合は、`model_settings` で明示的に設定してください。 ### 0.6.0 -このバージョンでは、デフォルトのハンドオフ履歴は raw のユーザー / assistant ターンを公開するのではなく、単一の assistant メッセージにまとめられるようになり、下流のエージェントに簡潔で予測可能な要約を提供します -- 既存の単一メッセージのハンドオフ transcript は、デフォルトで `` ブロックの前に "For context, here is the conversation so far between the user and the previous agent:" で始まるようになり、下流のエージェントに明確にラベル付けされた要約を提供します +このバージョンでは、デフォルトのハンドオフ履歴は、生のユーザー / アシスタントターンを公開するのではなく、単一の assistant メッセージにまとめられるようになり、後続のエージェントに簡潔で予測可能な要約を提供します +- 既存の単一メッセージのハンドオフトランスクリプトは、デフォルトで `` ブロックの前に "For context, here is the conversation so far between the user and the previous agent:" で始まるようになったため、後続のエージェントは明確なラベル付きの要約を受け取れます ### 0.5.0 -このバージョンでは目に見える破壊的変更は導入されませんが、新機能と内部のいくつかの重要な更新が含まれています。 +このバージョンでは、目に見える破壊的変更は導入されませんが、新機能と内部のいくつかの重要な更新が含まれます: -- [SIP protocol connections](https://platform.openai.com/docs/guides/realtime-sip) を処理するための `RealtimeRunner` のサポートを追加しました -- Python 3.14 互換性のために `Runner#run_sync` の内部ロジックを大幅に改訂しました +- `RealtimeRunner` が [SIP プロトコル接続](https://platform.openai.com/docs/guides/realtime-sip)を処理するためのサポートを追加しました +- Python 3.14 互換性のために、`Runner#run_sync` の内部ロジックを大幅に改訂しました ### 0.4.0 @@ -167,12 +167,12 @@ structured-output エージェントでは、handler はエージェントの出 ### 0.3.0 -このバージョンでは、Realtime API サポートが gpt-realtime モデルとその API インターフェイス（GA バージョン）へ移行します。 +このバージョンでは、Realtime API サポートは gpt-realtime モデルとその API インターフェイス（GA バージョン）へ移行します。 ### 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] に 2 つの新しい params、`run_context` と `agent` が追加されました。`MCPServer` をサブクラス化するすべてのクラスに、これらの params を追加する必要があります。 \ No newline at end of file +このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` という 2 つの新しいパラメーターが追加されました。`MCPServer` をサブクラス化しているすべてのクラスに、これらのパラメーターを追加する必要があります。 \ No newline at end of file diff --git a/docs/ja/repl.md b/docs/ja/repl.md index 38ea9d35b2..bab1d5ac8f 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 @@ -19,6 +19,6 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成されたモデル出力をストリーミングします。上記の例を実行すると、`run_demo_loop` は対話型のチャットセッションを開始します。入力を継続的に求め、これまでの会話履歴全体を保持することで（エージェントが何について話したかを把握できます）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。 +`run_demo_loop` はループ内でユーザー入力を求め、ターン間の会話履歴を保持します。デフォルトでは、生成されるモデル出力をストリーミングします。上記の例を実行すると、run_demo_loop は対話型チャットセッションを開始します。入力を継続的に求め、ターン間の会話履歴全体を記憶し（そのためエージェントはこれまでに話し合われた内容を把握できます）、エージェントの応答が生成されるとリアルタイムで自動的にストリーミングします。 -このチャットセッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボードショートカットを使用します。 \ No newline at end of file +このチャットセッションを終了するには、単に `quit` または `exit` と入力して Enter キーを押すか、`Ctrl-D` キーボードショートカットを使用します。 \ No newline at end of file diff --git a/docs/ja/results.md b/docs/ja/results.md index 56113f44a7..1ea67846df 100644 --- a/docs/ja/results.md +++ b/docs/ja/results.md @@ -4,81 +4,81 @@ search: --- # 実行結果 -`Runner.run` メソッドを呼び出すと、2 種類の実行結果タイプのいずれかを受け取ります。 +`Runner.run` メソッドを呼び出すと、次の 2 つの実行結果型のいずれかを受け取ります。 -- [`RunResult`][agents.result.RunResult]（`Runner.run(...)` または `Runner.run_sync(...)` から） -- [`RunResultStreaming`][agents.result.RunResultStreaming]（`Runner.run_streamed(...)` から） +- `Runner.run(...)` または `Runner.run_sync(...)` からの [`RunResult`][agents.result.RunResult] +- `Runner.run_streamed(...)` からの [`RunResultStreaming`][agents.result.RunResultStreaming] どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、`final_output`、`new_items`、`last_agent`、`raw_responses`、`to_state()` などの共通の実行結果サーフェスを公開します。 -`RunResultStreaming` は、[`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete]、[`cancel(...)`][agents.result.RunResultStreaming.cancel] など、ストリーミング固有の制御を追加します。 +`RunResultStreaming` は、[`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete]、[`cancel(...)`][agents.result.RunResultStreaming.cancel] など、ストリーミング固有の制御機能を追加します。 ## 適切な実行結果サーフェスの選択 -ほとんどのアプリケーションでは、いくつかの実行結果プロパティまたはヘルパーだけが必要です。 +ほとんどのアプリケーションでは、いくつかの実行結果プロパティまたはヘルパーだけで十分です。 -| 必要なもの | 使用するもの | +| 必要なもの... | 使用するもの | | --- | --- | | ユーザーに表示する最終回答 | `final_output` | -| 完全なローカルトランスクリプトを含む、再生可能な次ターン入力リスト | `to_input_list()` | -| エージェント、ツール、ハンドオフ、承認メタデータを含む豊富な実行項目 | `new_items` | +| 完全なローカルトランスクリプトを含む、リプレイ可能な次ターン入力リスト | `to_input_list()` | +| エージェント、ツール、ハンドオフ、承認メタデータを含む詳細な実行項目 | `new_items` | | 通常、次のユーザーターンを処理すべきエージェント | `last_agent` | -| `previous_response_id` による OpenAI Responses API のチェーン | `last_response_id` | -| 保留中の承認と再開可能なスナップショット | `interruptions` と `to_state()` | +| `previous_response_id` による OpenAI Responses API チェーン | `last_response_id` | +| 保留中の承認と再開可能なスナップショット | `interruptions` and `to_state()` | | 現在のネストされた `Agent.as_tool()` 呼び出しに関するメタデータ | `agent_tool_invocation` | -| raw モデル呼び出しまたはガードレール診断 | `raw_responses` とガードレール実行結果配列 | +| raw モデル呼び出しまたはガードレール診断 | `raw_responses` and the guardrail result arrays | ## 最終出力 [`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。 -- 最後のエージェントに `output_type` が定義されていなかった場合は `str` -- 最後のエージェントに出力タイプが定義されていた場合は `last_agent.output_type` 型のオブジェクト -- たとえば承認中断で一時停止したために、最終出力が生成される前に実行が停止した場合は `None` +- 最後のエージェントに `output_type` が定義されていなかった場合は `str` +- 最後のエージェントに出力型が定義されていた場合は `last_agent.output_type` 型のオブジェクト +- 承認中断で一時停止した場合など、最終出力が生成される前に実行が停止した場合は `None` !!! note - `final_output` は `Any` として型付けされています。ハンドオフによってどのエージェントが実行を終了するかが変わる可能性があるため、SDK は取り得る出力タイプの完全な集合を静的に知ることはできません。 + `final_output` は `Any` として型付けされています。ハンドオフによって、どのエージェントが実行を終了するかが変わる可能性があるため、SDK は考えられる出力型の全体集合を静的に把握できません。 -ストリーミングモードでは、ストリームの処理が完了するまで `final_output` は `None` のままです。イベントごとのフローについては [ストリーミング](streaming.md) を参照してください。 +ストリーミングモードでは、ストリームの処理が完了するまで `final_output` は `None` のままです。イベントごとのフローについては、[ストリーミング](streaming.md)を参照してください。 ## 入力、次ターン履歴、新規項目 -これらのサーフェスは異なる問いに答えます。 +これらのサーフェスは、それぞれ異なる問いに対応します。 -| プロパティまたはヘルパー | 含まれるもの | 最適な用途 | +| プロパティまたはヘルパー | 含まれる内容 | 最適な用途 | | --- | --- | --- | -| [`input`][agents.result.RunResultBase.input] | この実行セグメントのベース入力です。ハンドオフ入力フィルターが履歴を書き換えた場合、実行が継続したフィルター済み入力が反映されます。 | この実行が実際に入力として使用した内容の監査 | -| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 実行の入力項目ビューです。デフォルトの `mode="preserve_all"` は、`new_items` から変換された完全な履歴を保持します。`mode="normalized"` は、ハンドオフフィルタリングによってモデル履歴が書き換えられる場合、正規の継続入力を優先します。 | 手動のチャットループ、クライアント管理の会話状態、プレーン項目履歴の確認 | -| [`new_items`][agents.result.RunResultBase.new_items] | エージェント、ツール、ハンドオフ、承認メタデータを含む豊富な [`RunItem`][agents.items.RunItem] ラッパーです。 | ログ、UI、監査、デバッグ | +| [`input`][agents.result.RunResultBase.input] | この実行セグメントの基本入力です。ハンドオフ入力フィルターが履歴を書き換えた場合、実行が継続されたフィルター済み入力がここに反映されます。 | この実行が実際に入力として使用した内容の監査 | +| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 実行を入力項目として見たビューです。デフォルトの `mode="preserve_all"` は、`new_items` から変換された完全な履歴を保持します。`mode="normalized"` は、ハンドオフフィルタリングによってモデル履歴が書き換えられた場合に、正規の継続入力を優先します。 | 手動のチャットループ、クライアント管理の会話状態、プレーンな項目履歴の確認 | +| [`new_items`][agents.result.RunResultBase.new_items] | エージェント、ツール、ハンドオフ、承認メタデータを含む詳細な [`RunItem`][agents.items.RunItem] ラッパーです。 | ログ、UI、監査、デバッグ | | [`raw_responses`][agents.result.RunResultBase.raw_responses] | 実行内の各モデル呼び出しからの raw [`ModelResponse`][agents.items.ModelResponse] オブジェクトです。 | プロバイダーレベルの診断または raw レスポンスの確認 | -実際には、次のように使います。 +実際には、次のように使い分けます。 -- プレーンな入力項目ビューが必要な場合は `to_input_list()` を使用します。 -- ハンドオフフィルタリングまたはネストされたハンドオフ履歴の書き換え後、次の `Runner.run(..., input=...)` 呼び出しのための正規のローカル入力が必要な場合は、`to_input_list(mode="normalized")` を使用します。 -- SDK に履歴の読み込みと保存を任せたい場合は、[`session=...`](sessions/index.md) を使用します。 -- `conversation_id` または `previous_response_id` で OpenAI サーバー管理状態を使用している場合は、通常、`to_input_list()` を再送するのではなく、新しいユーザー入力のみを渡して保存済み ID を再利用します。 -- ログ、UI、監査のために変換済みの完全な履歴が必要な場合は、デフォルトの `to_input_list()` モードまたは `new_items` を使用します。 +- 実行のプレーンな入力項目ビューが必要な場合は、`to_input_list()` を使用します。 +- ハンドオフフィルタリングまたはネストされたハンドオフ履歴の書き換え後に、次の `Runner.run(..., input=...)` 呼び出しに渡す正規のローカル入力が必要な場合は、`to_input_list(mode="normalized")` を使用します。 +- SDK に履歴の読み込みと保存を任せたい場合は、[`session=...`](sessions/index.md) を使用します。 +- `conversation_id` または `previous_response_id` を使って OpenAI のサーバー管理状態を使用している場合、通常は `to_input_list()` を再送信する代わりに、新しいユーザー入力のみを渡して保存済み ID を再利用します。 +- ログ、UI、監査向けに完全な変換済み履歴が必要な場合は、デフォルトの `to_input_list()` モードまたは `new_items` を使用します。 -JavaScript SDK とは異なり、Python ではモデル形状の差分のみを表す個別の `output` プロパティは公開されません。SDK メタデータが必要な場合は `new_items` を使用し、raw モデルペイロードが必要な場合は `raw_responses` を確認してください。 +JavaScript SDK とは異なり、Python ではモデル形式の差分のみを表す個別の `output` プロパティは公開されません。SDK メタデータが必要な場合は `new_items` を使用し、raw モデルペイロードが必要な場合は `raw_responses` を確認してください。 -コンピュータツールの再生は、raw Responses ペイロードの形状に従います。プレビューモデルの `computer_call` 項目は単一の `action` を保持しますが、`gpt-5.5` のコンピュータ呼び出しはバッチ化された `actions[]` を保持できます。[`to_input_list()`][agents.result.RunResultBase.to_input_list] と [`RunState`][agents.run_state.RunState] はモデルが生成した形状をそのまま保持するため、手動再生、一時停止/再開フロー、保存済みトランスクリプトは、プレビュー版と GA のコンピュータツール呼び出しの両方で引き続き機能します。ローカルの実行結果は、引き続き `new_items` 内の `computer_call_output` 項目として表示されます。 +コンピュータツールのリプレイは、raw Responses ペイロードの形状に従います。プレビューモデルの `computer_call` 項目は単一の `action` を保持しますが、`gpt-5.5` のコンピュータ呼び出しではバッチ化された `actions[]` を保持できます。[`to_input_list()`][agents.result.RunResultBase.to_input_list] と [`RunState`][agents.run_state.RunState] は、モデルが生成した形状をそのまま保持するため、手動リプレイ、一時停止/再開フロー、保存済みトランスクリプトは、プレビュー版と GA 版の両方のコンピュータツール呼び出しで引き続き機能します。ローカル実行結果は引き続き `new_items` 内の `computer_call_output` 項目として表示されます。 ### 新規項目 -[`new_items`][agents.result.RunResultBase.new_items] は、実行中に起きたことを最も豊富に確認できるビューを提供します。一般的な項目タイプは次のとおりです。 +[`new_items`][agents.result.RunResultBase.new_items] は、実行中に何が起きたかを最も詳細に確認できるビューです。一般的な項目型は次のとおりです。 -- アシスタントメッセージの [`MessageOutputItem`][agents.items.MessageOutputItem] -- 推論項目の [`ReasoningItem`][agents.items.ReasoningItem] -- Responses ツール検索リクエストと読み込まれたツール検索結果の [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] および [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem] -- ツール呼び出しとその実行結果の [`ToolCallItem`][agents.items.ToolCallItem] および [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] -- 承認のために一時停止したツール呼び出しの [`ToolApprovalItem`][agents.items.ToolApprovalItem] -- ハンドオフリクエストと完了した転送の [`HandoffCallItem`][agents.items.HandoffCallItem] および [`HandoffOutputItem`][agents.items.HandoffOutputItem] +- アシスタントメッセージ用の [`MessageOutputItem`][agents.items.MessageOutputItem] +- 推論項目用の [`ReasoningItem`][agents.items.ReasoningItem] +- Responses のツール検索リクエストと、ロードされたツール検索の実行結果用の [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] および [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem] +- ツール呼び出しとその実行結果用の [`ToolCallItem`][agents.items.ToolCallItem] および [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] +- 承認待ちで一時停止したツール呼び出し用の [`ToolApprovalItem`][agents.items.ToolApprovalItem] +- ハンドオフリクエストと完了済みの引き継ぎ用の [`HandoffCallItem`][agents.items.HandoffCallItem] および [`HandoffOutputItem`][agents.items.HandoffOutputItem] -エージェントの関連付け、ツール出力、ハンドオフ境界、または承認境界が必要な場合は、常に `to_input_list()` よりも `new_items` を選択してください。 +エージェントの関連付け、ツール出力、ハンドオフの境界、承認の境界が必要な場合は、常に `to_input_list()` よりも `new_items` を選択してください。 -ホスト型ツール検索を使用する場合は、`ToolSearchCallItem.raw_item` を確認してモデルが発行した検索リクエストを確認し、`ToolSearchOutputItem.raw_item` を確認してそのターンで読み込まれた名前空間、関数、またはホスト型 MCP サーバーを確認してください。 +ホスト型ツール検索を使用する場合、モデルが生成した検索リクエストを確認するには `ToolSearchCallItem.raw_item` を確認し、そのターンでどの名前空間、関数、またはホスト型 MCP サーバーがロードされたかを確認するには `ToolSearchOutputItem.raw_item` を確認してください。 ## 会話の継続または再開 @@ -86,13 +86,13 @@ JavaScript SDK とは異なり、Python ではモデル形状の差分のみを [`last_agent`][agents.result.RunResultBase.last_agent] には、最後に実行されたエージェントが含まれます。これは多くの場合、ハンドオフ後の次のユーザーターンで再利用するのに最適なエージェントです。 -ストリーミングモードでは、実行の進行に応じて [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] が更新されるため、ストリームが完了する前にハンドオフを観察できます。 +ストリーミングモードでは、[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] が実行の進行に合わせて更新されるため、ストリームが終了する前にハンドオフを観察できます。 ### 中断と実行状態 -ツールに承認が必要な場合、保留中の承認は [`RunResult.interruptions`][agents.result.RunResult.interruptions] または [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。これには、直接ツールによって発生した承認、ハンドオフ後に到達したツールによって発生した承認、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行によって発生した承認が含まれる場合があります。 +ツールに承認が必要な場合、保留中の承認は [`RunResult.interruptions`][agents.result.RunResult.interruptions] または [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。これには、直接呼び出されたツール、ハンドオフ後に到達したツール、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行によって発生した承認が含まれることがあります。 -[`to_state()`][agents.result.RunResult.to_state] を呼び出して、再開可能な [`RunState`][agents.run_state.RunState] を取得し、保留中の項目を承認または却下してから、`Runner.run(...)` または `Runner.run_streamed(...)` で再開します。 +[`to_state()`][agents.result.RunResult.to_state] を呼び出して、再開可能な [`RunState`][agents.run_state.RunState] を取得し、保留中の項目を承認または拒否してから、`Runner.run(...)` または `Runner.run_streamed(...)` で再開します。 ```python from agents import Agent, Runner @@ -107,59 +107,59 @@ if result.interruptions: result = await Runner.run(agent, state) ``` -ストリーミング実行では、まず [`stream_events()`][agents.result.RunResultStreaming.stream_events] の消費を完了し、その後 `result.interruptions` を確認して `result.to_state()` から再開します。完全な承認フローについては、[Human-in-the-loop](human_in_the_loop.md) を参照してください。 +ストリーミング実行では、まず [`stream_events()`][agents.result.RunResultStreaming.stream_events] の消費を完了してから `result.interruptions` を確認し、`result.to_state()` から再開してください。承認フロー全体については、[ヒューマンインザループ](human_in_the_loop.md)を参照してください。 ### サーバー管理の継続 -[`last_response_id`][agents.result.RunResultBase.last_response_id] は、実行から得られた最新のモデルレスポンス ID です。OpenAI Responses API チェーンを継続したい場合は、次のターンで `previous_response_id` として渡します。 +[`last_response_id`][agents.result.RunResultBase.last_response_id] は、実行から得られた最新のモデルレスポンス ID です。OpenAI Responses API チェーンを継続したい場合は、次のターンで `previous_response_id` として渡してください。 -すでに `to_input_list()`、`session`、または `conversation_id` で会話を継続している場合、通常 `last_response_id` は必要ありません。複数ステップの実行からすべてのモデルレスポンスが必要な場合は、代わりに `raw_responses` を確認してください。 +すでに `to_input_list()`、`session`、または `conversation_id` で会話を継続している場合、通常は `last_response_id` は不要です。複数ステップの実行におけるすべてのモデルレスポンスが必要な場合は、代わりに `raw_responses` を確認してください。 -## Agent-as-tool メタデータ +## ツールとしてのエージェントのメタデータ -ネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行から実行結果が返される場合、[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] は外側のツール呼び出しに関する不変のメタデータを公開します。 +実行結果がネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に由来する場合、[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] は外側のツール呼び出しに関する変更不可のメタデータを公開します。 -- `tool_name` -- `tool_call_id` -- `tool_arguments` +- `tool_name` +- `tool_call_id` +- `tool_arguments` 通常のトップレベル実行では、`agent_tool_invocation` は `None` です。 -これは、ネストされた実行結果を後処理する際に外側のツール名、呼び出し ID、または raw 引数が必要になることがある `custom_output_extractor` 内で特に有用です。周辺の `Agent.as_tool()` パターンについては、[ツール](tools.md) を参照してください。 +これは、ネストされた実行結果を後処理する際に、外側のツール名、呼び出し ID、または生の引数が必要になることがある `custom_output_extractor` 内で特に便利です。関連する `Agent.as_tool()` パターンについては、[ツール](tools.md)を参照してください。 -そのネストされた実行の解析済み structured input も必要な場合は、`context_wrapper.tool_input` を読み取ります。これは [`RunState`][agents.run_state.RunState] がネストされたツール入力として汎用的にシリアライズするフィールドであり、`agent_tool_invocation` は現在のネストされた呼び出しに対するライブ実行結果アクセサーです。 +そのネストされた実行のパース済み構造化入力も必要な場合は、`context_wrapper.tool_input` を読み取ってください。これは、ネストされたツール入力に対して [`RunState`][agents.run_state.RunState] が汎用的にシリアライズするフィールドです。一方、`agent_tool_invocation` は、現在のネストされた呼び出しに対するライブの実行結果アクセサーです。 ## ストリーミングのライフサイクルと診断 -[`RunResultStreaming`][agents.result.RunResultStreaming] は上記と同じ実行結果サーフェスを継承しますが、ストリーミング固有の制御を追加します。 +[`RunResultStreaming`][agents.result.RunResultStreaming] は、上記と同じ実行結果サーフェスを継承しますが、ストリーミング固有の制御機能を追加します。 -- セマンティックなストリームイベントを消費する [`stream_events()`][agents.result.RunResultStreaming.stream_events] -- 実行中のアクティブなエージェントを追跡する [`current_agent`][agents.result.RunResultStreaming.current_agent] -- ストリーミング実行が完全に終了したかどうかを確認する [`is_complete`][agents.result.RunResultStreaming.is_complete] -- 現在のターンの直後または即座に実行を停止する [`cancel(...)`][agents.result.RunResultStreaming.cancel] +- セマンティックなストリームイベントを消費するための [`stream_events()`][agents.result.RunResultStreaming.stream_events] +- 実行途中でアクティブなエージェントを追跡するための [`current_agent`][agents.result.RunResultStreaming.current_agent] +- ストリーミング実行が完全に終了したかどうかを確認するための [`is_complete`][agents.result.RunResultStreaming.is_complete] +- 実行を即時または現在のターン後に停止するための [`cancel(...)`][agents.result.RunResultStreaming.cancel] -非同期イテレーターが終了するまで `stream_events()` を消費し続けてください。ストリーミング実行は、そのイテレーターが終了するまで完了していません。また、`final_output`、`interruptions`、`raw_responses`、セッション永続化の副作用などのサマリープロパティは、最後に見えるトークンが到着した後もまだ確定中の場合があります。 +非同期イテレーターが終了するまで `stream_events()` を消費し続けてください。そのイテレーターが終了するまで、ストリーミング実行は完了していません。また、`final_output`、`interruptions`、`raw_responses` などの要約プロパティや、セッション永続化の副作用は、目に見える最後のトークンが到着した後もまだ確定中の場合があります。 -`cancel()` を呼び出した場合は、キャンセルとクリーンアップが正しく完了できるように、`stream_events()` の消費を続けてください。 +`cancel()` を呼び出した場合は、キャンセルとクリーンアップが正しく完了できるように、`stream_events()` を消費し続けてください。 -Python では、ストリーミングされた個別の `completed` promise や `error` プロパティは公開されません。終端的なストリーミング失敗は `stream_events()` から例外を送出することで表面化し、`is_complete` は実行が終端状態に到達したかどうかを反映します。 +Python では、ストリーミング用の個別の `completed` プロミスや `error` プロパティは公開されません。終端的なストリーミング失敗は `stream_events()` から例外が送出されることで表面化し、`is_complete` は実行が終端状態に到達したかどうかを反映します。 -### Raw レスポンス +### raw レスポンス -[`raw_responses`][agents.result.RunResultBase.raw_responses] には、実行中に収集された raw モデルレスポンスが含まれます。複数ステップの実行では、たとえばハンドオフや、モデル/ツール/モデルのサイクルの繰り返しをまたいで、複数のレスポンスが生成される場合があります。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] には、実行中に収集された raw モデルレスポンスが含まれます。複数ステップの実行では、ハンドオフをまたいだり、モデル/ツール/モデルのサイクルが繰り返されたりする場合など、複数のレスポンスが生成されることがあります。 -[`last_response_id`][agents.result.RunResultBase.last_response_id] は、`raw_responses` の最後のエントリーからの ID にすぎません。 +[`last_response_id`][agents.result.RunResultBase.last_response_id] は、`raw_responses` の最後のエントリの ID にすぎません。 -### ガードレール実行結果 +### ガードレールの実行結果 エージェントレベルのガードレールは、[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] として公開されます。 -ツールのガードレールは、[`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] および [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] として別途公開されます。 +ツールガードレールは、[`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] および [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] として個別に公開されます。 -これらの配列は実行全体を通じて蓄積されるため、判断のログ記録、追加のガードレールメタデータの保存、または実行がブロックされた理由のデバッグに役立ちます。 +これらの配列は実行全体で蓄積されるため、判定のログ記録、追加のガードレールメタデータの保存、または実行がブロックされた理由のデバッグに役立ちます。 ### コンテキストと使用量 -[`context_wrapper`][agents.result.RunResultBase.context_wrapper] は、承認、使用量、ネストされた `tool_input` など、SDK 管理のランタイムメタデータとともにアプリのコンテキストを公開します。 +[`context_wrapper`][agents.result.RunResultBase.context_wrapper] は、アプリのコンテキストと、承認、使用量、ネストされた `tool_input` など SDK が管理するランタイムメタデータを公開します。 -使用量は `context_wrapper.usage` で追跡されます。ストリーミング実行では、ストリームの最後のチャンクが処理されるまで使用量の合計が遅れることがあります。完全なラッパー形状と永続化に関する注意事項については、[コンテキスト管理](context.md) を参照してください。 \ No newline at end of file +使用量は `context_wrapper.usage` で追跡されます。ストリーミング実行では、ストリームの最終チャンクが処理されるまで、使用量の合計値が遅れて反映される場合があります。ラッパーの完全な形状と永続化に関する注意事項については、[コンテキスト管理](context.md)を参照してください。 \ No newline at end of file diff --git a/docs/ja/running_agents.md b/docs/ja/running_agents.md index d2eeaaecd5..4071d69f61 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] は async で実行され、[`RunResult`][agents.result.RunResult] を返します。 -2. [`Runner.run_sync()`][agents.run.Runner.run_sync] は sync メソッドで、内部的には単に `.run()` を実行します。 -3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] は async で実行され、[`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,17 +23,17 @@ async def main(): # Infinite loop's dance ``` -詳しくは [実行結果ガイド](results.md) をお読みください。 +詳細は [実行結果ガイド](results.md) を参照してください。 ## Runner のライフサイクルと設定 ### エージェントループ -`Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力には次を指定できます。 +`Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力には以下を指定できます。 -- 文字列（ユーザーメッセージとして扱われます）、 -- OpenAI Responses API 形式の入力アイテムのリスト、または -- 中断された実行を再開する場合の [`RunState`][agents.run_state.RunState]。 +- 文字列（ユーザーメッセージとして扱われます） +- OpenAI Responses API 形式の入力項目のリスト +- 中断された実行を再開する場合の [`RunState`][agents.run_state.RunState] その後、runner はループを実行します。 @@ -46,23 +46,23 @@ async def main(): !!! note - LLM 出力が「最終出力」と見なされるかどうかのルールは、目的の型のテキスト出力を生成し、ツール呼び出しがないことです。 + LLM の出力が「最終出力」と見なされるルールは、目的の型のテキスト出力が生成され、ツール呼び出しがないことです。 ### ストリーミング -ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受信できます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む、実行に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳しくは [ストリーミングガイド](streaming.md) をお読みください。 +ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳細は [ストリーミングガイド](streaming.md) を参照してください。 #### Responses WebSocket トランスポート（任意のヘルパー） -OpenAI Responses websocket トランスポートを有効にしても、通常の `Runner` API を引き続き使用できます。接続の再利用には websocket セッションヘルパーが推奨されますが、必須ではありません。 +OpenAI Responses WebSocket トランスポートを有効にしても、通常の `Runner` API を引き続き使用できます。WebSocket セッションヘルパーは接続の再利用に推奨されますが、必須ではありません。 -これは websocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。 +これは WebSocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。 -トランスポート選択ルールや、具体的なモデルオブジェクトまたはカスタムプロバイダーに関する注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。 +具体的なモデルオブジェクトやカスタムプロバイダーに関するトランスポート選択ルールと注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。 ##### パターン 1: セッションヘルパーなし（動作します） -websocket トランスポートだけが必要で、SDK に共有プロバイダー / セッションを管理させる必要がない場合に使用します。 +WebSocket トランスポートだけを使用したく、SDK に共有プロバイダー / セッションを管理させる必要がない場合に使用します。 ```python import asyncio @@ -87,9 +87,9 @@ asyncio.run(main()) このパターンは単発の実行には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼び出す場合、同じ `RunConfig` / プロバイダーインスタンスを手動で再利用しない限り、各実行で再接続される可能性があります。 -##### パターン 2: `responses_websocket_session()` の使用（複数ターンでの再利用に推奨） +##### パターン 2: `responses_websocket_session()` の使用（複数ターンの再利用に推奨） -複数の実行（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含む）で共有の websocket 対応プロバイダーと `RunConfig` が必要な場合は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用します。 +複数の実行にわたって共有の WebSocket 対応プロバイダーと `RunConfig` を使用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用します（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含みます）。 ```python import asyncio @@ -119,55 +119,55 @@ async def main(): asyncio.run(main()) ``` -コンテキストを抜ける前に、ストリーミングされた実行結果の消費を完了してください。websocket リクエストがまだ実行中の間にコンテキストを抜けると、共有接続が強制的に閉じられる可能性があります。 +コンテキストを抜ける前に、ストリーミングされた実行結果の消費を完了してください。WebSocket リクエストがまだ実行中の状態でコンテキストを抜けると、共有接続が強制的に閉じられる可能性があります。 -長い推論ターンで websocket keepalive タイムアウトが発生する場合は、`ping_timeout` を増やすか、`ping_timeout=None` を設定して heartbeat タイムアウトを無効にしてください。websocket のレイテンシーより信頼性が重要な実行では、HTTP/SSE トランスポートを使用してください。 +長い推論ターンで WebSocket の keepalive タイムアウトに達する場合は、`ping_timeout` を増やすか、`ping_timeout=None` を設定してハートビートタイムアウトを無効にしてください。WebSocket のレイテンシより信頼性が重要な実行では、HTTP/SSE トランスポートを使用してください。 ### 実行設定 -`run_config` パラメーターを使用すると、エージェント実行の一部のグローバル設定を構成できます。 +`run_config` パラメーターを使用すると、エージェント実行に関するいくつかのグローバル設定を構成できます。 #### 一般的な実行設定カテゴリー -各エージェント定義を変更せずに、単一の実行の動作を上書きするには `RunConfig` を使用します。 +各エージェント定義を変更せずに単一の実行の動作を上書きするには、`RunConfig` を使用します。 ##### モデル、プロバイダー、セッションのデフォルト -- [`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` を設定できます。 +- [`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` を設定できます。 - [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際のセッションレベルのデフォルト（たとえば `SessionSettings(limit=...)`）を上書きします。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions を使用するとき、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは sync または async にできます。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions を使用する際、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは同期でも非同期でもかまいません。 ##### ガードレール、ハンドオフ、モデル入力の整形 - [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力ガードレールのリストです。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフにすでにフィルターがない場合に、すべてのハンドオフに適用するグローバル入力フィルターです。入力フィルターを使用すると、新しいエージェントに送信される入力を編集できます。詳細については、[`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前の transcript を単一の assistant メッセージに折りたたむ opt-in beta です。ネストされたハンドオフを安定化する間、これはデフォルトで無効です。有効にするには `True` に設定し、raw transcript をそのまま渡すには `False` のままにします。[Runner methods][agents.run.Runner] は `RunConfig` を渡さない場合に自動的に作成するため、クイックスタートとコード例ではデフォルトがオフのままになり、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個別のハンドオフでは、[`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を介してこの設定を上書きできます。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` に opt in したときに、正規化済み transcript（履歴 + ハンドオフアイテム）を受け取る任意の callable です。次のエージェントに転送する入力アイテムの正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込み summary を置き換えられます。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力アイテム）を編集する hook です。たとえば、履歴を trim したり、システムプロンプトを注入したりできます。 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換するとき、reasoning item ID を保持するか省略するかを制御します。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフにまだ入力フィルターがない場合に、すべてのハンドオフに適用するグローバル入力フィルターです。入力フィルターを使用すると、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前のトランスクリプトを単一のアシスタントメッセージに折りたたむオプトインのベータ機能です。ネストされたハンドオフを安定化させている間、この機能はデフォルトで無効です。有効にするには `True` に設定し、未加工のトランスクリプトをそのまま渡すには `False` のままにします。すべての [Runner メソッド][agents.run.Runner] は、渡されない場合に自動的に `RunConfig` を作成するため、クイックスタートとコード例ではデフォルトでオフのままになり、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個別のハンドオフは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を通じてこの設定を上書きできます。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` にオプトインした場合に、正規化されたトランスクリプト（履歴 + ハンドオフ項目）を受け取る任意の callable です。次のエージェントに転送する入力項目の正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込みの要約を置き換えられます。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力項目）を編集するフックです。たとえば、履歴をトリミングしたり、システムプロンプトを挿入したりできます。 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換するときに、推論項目 ID を保持するか省略するかを制御します。 ##### トレーシングと可観測性 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体の [トレーシング](tracing.md) を無効にできます。 -- [`tracing`][agents.run.RunConfig.tracing]: 実行ごとのトレーシング API キーなど、trace export 設定を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入力 / 出力など、機密の可能性があるデータを trace に含めるかどうかを構成します。 -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` を設定することをお勧めします。group ID は、複数の実行にわたって trace をリンクできる任意フィールドです。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべての trace に含めるメタデータです。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体で [トレーシング](tracing.md) を無効にできます。 +- [`tracing`][agents.run.RunConfig.tracing]: 実行ごとのトレーシング API キーなど、トレースエクスポート設定を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。 +- [`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]: すべてのトレースに含めるメタデータです。 -##### ツール実行、承認、ツールエラー動作 +##### ツール実行、承認、ツールエラーの動作 -- [`tool_execution`][agents.run.RunConfig.tool_execution]: 同時に実行する関数ツールの数を制限するなど、ローカルツール呼び出しに対する SDK 側の実行動作を構成します。 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに見えるメッセージをカスタマイズします。 +- [`tool_execution`][agents.run.RunConfig.tool_execution]: 一度に実行する関数ツール数を制限するなど、ローカルツール呼び出しに対する SDK 側の実行動作を設定します。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに表示されるメッセージをカスタマイズします。 -ネストされたハンドオフは opt-in beta として利用できます。折りたたまれた transcript の動作を有効にするには `RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフで有効にするために `handoff(..., nest_handoff_history=True)` を設定します。raw transcript（デフォルト）を保持したい場合は、フラグを未設定のままにするか、必要どおりに会話を正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を提供します。カスタム mapper を書かずに、生成される summary で使用される wrapper text を変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（デフォルトを復元するには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出します。 +ネストされたハンドオフは、オプトインのベータ機能として利用できます。`RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフで `handoff(..., nest_handoff_history=True)` を設定すると、折りたたみトランスクリプト動作を有効にできます。未加工のトランスクリプトを保持したい場合（デフォルト）は、フラグを未設定のままにするか、必要に応じて会話を正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定します。カスタムマッパーを書かずに、生成される要約で使用されるラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] を呼び出します（デフォルトに戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 #### 実行設定の詳細 ##### `tool_execution` -実行に対して SDK にローカル関数ツールの同時実行数を制限させたい場合は、`tool_execution` を使用します。 +実行に対してローカル関数ツールの同時実行数を SDK に制限させたい場合は、`tool_execution` を使用します。 ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,22 +183,22 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None` はデフォルトの動作を維持します。モデルが 1 ターンで複数の関数ツール呼び出しを出力した場合、SDK は出力されたすべてのローカル関数ツール呼び出しを開始します。同時に実行されるローカル関数ツールの数に上限を設けるには、整数値を設定します。 +`max_function_tool_concurrency=None` はデフォルトの動作を維持します。モデルが 1 ターンで複数の関数ツール呼び出しを生成した場合、SDK は生成されたすべてのローカル関数ツール呼び出しを開始します。整数値を設定すると、それらのローカル関数ツールのうち同時に実行される数に上限を設けられます。 -これはプロバイダー側の [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] とは別です。`parallel_tool_calls` は、モデルが 1 つのレスポンスで複数のツール呼び出しを出力してよいかどうかを制御します。`tool_execution.max_function_tool_concurrency` は、モデルが出力した後に SDK がローカル関数ツール呼び出しをどのように実行するかを制御します。 +これはプロバイダー側の [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] とは別のものです。`parallel_tool_calls` は、モデルが 1 つのレスポンスで複数のツール呼び出しを生成できるかどうかを制御します。`tool_execution.max_function_tool_concurrency` は、モデルがそれらを生成した後に、SDK がローカル関数ツール呼び出しをどのように実行するかを制御します。 ##### `tool_error_formatter` 承認フローでツール呼び出しが拒否されたときにモデルへ返されるメッセージをカスタマイズするには、`tool_error_formatter` を使用します。 -formatter は [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取り、内容は次のとおりです。 +フォーマッターは、以下を含む [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取ります。 -- `kind`: エラーカテゴリーです。現時点では `"approval_rejected"` です。 +- `kind`: エラーカテゴリーです。現在は `"approval_rejected"` です。 - `tool_type`: ツールランタイム（`"function"`、`"computer"`、`"shell"`、`"apply_patch"`、または `"custom"`）です。 - `tool_name`: ツール名です。 - `call_id`: ツール呼び出し ID です。 -- `default_message`: SDK のデフォルトの、モデルに見えるメッセージです。 -- `run_context`: アクティブな実行コンテキスト wrapper です。 +- `default_message`: SDK のデフォルトのモデル表示メッセージです。 +- `run_context`: アクティブな実行コンテキストラッパーです。 メッセージを置き換えるには文字列を返し、SDK のデフォルトを使用するには `None` を返します。 @@ -225,56 +225,56 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` は、runner が履歴を次へ引き継ぐとき（たとえば `RunResult.to_input_list()` やセッションに基づく実行を使用する場合）に、reasoning item を次ターンのモデル入力へどのように変換するかを制御します。 +`reasoning_item_id_policy` は、runner が履歴を引き継ぐとき（たとえば `RunResult.to_input_list()` やセッションに基づく実行を使用する場合）に、推論項目を次ターンのモデル入力へどのように変換するかを制御します。 -- `None` または `"preserve"`（デフォルト）: reasoning item ID を保持します。 -- `"omit"`: 生成される次ターン入力から reasoning item ID を取り除きます。 +- `None` または `"preserve"`（デフォルト）: 推論項目 ID を保持します。 +- `"omit"`: 生成される次ターンの入力から推論項目 ID を取り除きます。 -`"omit"` は主に、reasoning item が `id` とともに送信されているものの、必須の後続アイテムがない場合（たとえば `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）に発生する Responses API 400 エラーのクラスに対する opt-in 緩和策として使用します。 +`"omit"` は主に、推論項目が `id` 付きで送信されているものの、必須の後続項目がない場合に発生する Responses API 400 エラーの一群に対する、オプトインの緩和策として使用します（例: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 -これは、SDK が以前の出力から follow-up 入力を構築する複数ターンのエージェント実行（セッション永続化、サーバー管理の会話差分、ストリーミング / 非ストリーミングの follow-up ターン、resume paths を含む）で、reasoning item ID が保持されている一方、プロバイダーがその ID を対応する後続アイテムとペアのままにすることを要求する場合に発生することがあります。 +これは、SDK が以前の出力からフォローアップ入力を構築するマルチターンのエージェント実行で発生する可能性があります（セッション永続化、サーバー管理の会話差分、ストリーミング / 非ストリーミングのフォローアップターン、再開パスを含みます）。推論項目 ID が保持されている一方で、プロバイダーがその ID を対応する後続項目とペアのままにすることを要求する場合です。 -`reasoning_item_id_policy="omit"` を設定すると、reasoning content は保持しつつ reasoning item の `id` を取り除くため、SDK が生成する follow-up 入力でその API invariant をトリガーするのを回避できます。 +`reasoning_item_id_policy="omit"` を設定すると、推論コンテンツは保持したまま推論項目の `id` を取り除くため、SDK が生成するフォローアップ入力でその API 不変条件がトリガーされることを回避できます。 -スコープに関する注意: +スコープに関する注記: -- これは、SDK が follow-up 入力を構築するときに SDK によって生成 / 転送される reasoning items のみを変更します。 -- ユーザーが提供した初期入力アイテムは書き換えません。 -- `call_model_input_filter` は、このポリシー適用後でも意図的に reasoning IDs を再導入できます。 +- これは、SDK がフォローアップ入力を構築するときに SDK によって生成 / 転送される推論項目のみを変更します。 +- ユーザーが指定した初期入力項目は書き換えません。 +- `call_model_input_filter` は、このポリシー適用後でも意図的に推論 ID を再導入できます。 ## 状態と会話管理 -### メモリー戦略の選択 +### メモリ戦略の選択 状態を次のターンへ引き継ぐ一般的な方法は 4 つあります。 -| 戦略 | 状態の所在 | 最適な用途 | 次のターンで渡すもの | +| 戦略 | 状態の保存場所 | 最適な用途 | 次のターンで渡すもの | | --- | --- | --- | --- | -| `result.to_input_list()` | アプリのメモリー | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` からのリストと次のユーザーメッセージ | +| `result.to_input_list()` | アプリのメモリ | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` からのリストに次のユーザーメッセージを加えたもの | | `session` | ストレージと SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別のインスタンス | | `conversation_id` | OpenAI Conversations API | ワーカーやサービス間で共有したい名前付きのサーバー側会話 | 同じ `conversation_id` と新しいユーザーターンのみ | -| `previous_response_id` | OpenAI Responses API | 会話リソースを作成せずに行う軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ | +| `previous_response_id` | OpenAI Responses API | 会話リソースを作成しない、軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ | -`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理であり、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選択します。両方のレイヤーを意図的に照合しているのでない限り、クライアント管理の履歴と OpenAI 管理の状態を混在させると、コンテキストが重複する可能性があります。 +`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理で、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選択します。意図的に両方のレイヤーを調整している場合を除き、クライアント管理の履歴と OpenAI 管理の状態を混在させると、コンテキストが重複する可能性があります。 !!! note - セッション永続化は、サーバー管理の会話設定 + セッション永続化は、同じ実行内でサーバー管理の会話設定 （`conversation_id`、`previous_response_id`、または `auto_previous_response_id`）と - 同じ実行内で組み合わせることはできません。呼び出しごとに 1 つのアプローチを選択してください。 + 組み合わせることはできません。呼び出しごとに 1 つのアプローチを選択してください。 ### 会話 / チャットスレッド -いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）可能性がありますが、チャット会話における単一の論理ターンを表します。例: +いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）場合がありますが、チャット会話における単一の論理ターンを表します。例: 1. ユーザーターン: ユーザーがテキストを入力します -2. Runner run: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行してから出力を生成します。 +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(): @@ -296,7 +296,7 @@ async def main(): #### セッションによる自動会話管理 -よりシンプルな方法として、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動的に処理できます。 +より簡単な方法として、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動的に処理できます。 ```python from agents import Agent, Runner, SQLiteSession @@ -320,24 +320,24 @@ async def main(): # California ``` -Sessions は自動的に次を行います。 +Sessions は自動的に以下を行います。 - 各実行の前に会話履歴を取得します - 各実行の後に新しいメッセージを保存します - 異なるセッション ID ごとに別々の会話を維持します -詳細については、[Sessions ドキュメント](sessions/index.md) を参照してください。 +詳細は [Sessions ドキュメント](sessions/index.md) を参照してください。 #### サーバー管理の会話 -`to_input_list()` や `Sessions` でローカルに処理する代わりに、OpenAI の会話状態機能にサーバー側で会話状態を管理させることもできます。これにより、過去のすべてのメッセージを手動で再送信することなく、会話履歴を保持できます。以下のいずれのサーバー管理アプローチでも、各リクエストでは新しいターンの入力のみを渡し、保存された ID を再利用します。詳細については、[OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 +`to_input_list()` や `Sessions` でローカルに処理する代わりに、OpenAI の会話状態機能にサーバー側で会話状態を管理させることもできます。これにより、過去のすべてのメッセージを手動で再送信することなく、会話履歴を保持できます。以下のどちらのサーバー管理アプローチでも、各リクエストでは新しいターンの入力だけを渡し、保存した ID を再利用します。詳細は [OpenAI Conversation state ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。 -OpenAI はターン間で状態を追跡する 2 つの方法を提供しています。 +OpenAI は、ターン間で状態を追跡する 2 つの方法を提供しています。 ##### 1. `conversation_id` の使用 -まず OpenAI Conversations API を使用して会話を作成し、その ID を以降のすべての呼び出しで再利用します。 +まず OpenAI Conversations API を使用して会話を作成し、その後のすべての呼び出しでその ID を再利用します。 ```python from agents import Agent, Runner @@ -360,7 +360,7 @@ async def main(): ##### 2. `previous_response_id` の使用 -もう 1 つの選択肢は **response chaining** で、各ターンが前のターンの response ID に明示的にリンクされます。 +もう 1 つの選択肢は **レスポンスチェーン** で、各ターンを前のターンのレスポンス ID に明示的にリンクします。 ```python from agents import Agent, Runner @@ -385,31 +385,31 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -実行が承認のために一時停止し、[`RunState`][agents.run_state.RunState] から再開する場合、 +実行が承認のために一時停止し、[`RunState`][agents.run_state.RunState] から再開した場合、 SDK は保存された `conversation_id` / `previous_response_id` / `auto_previous_response_id` -設定を保持するため、再開されたターンは同じサーバー管理の会話で継続します。 +設定を保持するため、再開されたターンは同じサーバー管理の会話で続行されます。 -`conversation_id` と `previous_response_id` は相互に排他的です。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用します。あるターンから次のターンへ最も軽量な Responses API の継続プリミティブが必要な場合は `previous_response_id` を使用します。 +`conversation_id` と `previous_response_id` は同時に使用できません。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用します。あるターンから次のターンへ最も軽量な Responses API の継続基本コンポーネントが必要な場合は `previous_response_id` を使用します。 !!! note - SDK は `conversation_locked` エラーを backoff 付きで自動的に retry します。サーバー管理の - 会話実行では、同じ準備済みアイテムをきれいに再送できるように、retry 前に内部の conversation-tracker 入力を巻き戻します。 + SDK は `conversation_locked` エラーをバックオフ付きで自動的に再試行します。サーバー管理の + 会話実行では、再試行前に内部の会話トラッカー入力を巻き戻し、同じ準備済み項目を + クリーンに再送信できるようにします。 ローカルセッションベースの実行（`conversation_id`、 - `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）では、SDK は retry 後の重複した履歴エントリーを減らすため、 - 最近永続化された入力アイテムの best-effort - rollback も実行します。 + `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）では、SDK は再試行後の重複した履歴エントリを減らすために、 + 直近に永続化された入力項目のベストエフォートなロールバックも実行します。 - この互換性 retry は、`ModelSettings.retry` を構成していない場合でも発生します。モデルリクエストに対する、より広範な opt-in retry 動作については、[Runner 管理の retry](models/index.md#runner-managed-retries) を参照してください。 + この互換性再試行は、`ModelSettings.retry` を設定していない場合でも発生します。モデルリクエストに対するより広範なオプトインの再試行動作については、[Runner 管理の再試行](models/index.md#runner-managed-retries) を参照してください。 ## フックとカスタマイズ ### モデル呼び出し入力フィルター -モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。この hook は、現在のエージェント、context、および結合された入力アイテム（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。 +モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。このフックは現在のエージェント、コンテキスト、結合された入力項目（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。 -戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力アイテムのリストでなければなりません。それ以外の形を返すと `UserError` が発生します。 +戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力項目のリストでなければなりません。それ以外の形状を返すと `UserError` が発生します。 ```python from agents import Agent, Runner, RunConfig @@ -428,19 +428,19 @@ result = Runner.run_sync( ) ``` -runner は準備済み入力リストのコピーを hook に渡すため、呼び出し元の元のリストをその場で変更せずに、trim、置換、並べ替えができます。 +runner は準備済み入力リストのコピーをフックに渡すため、呼び出し元の元のリストをその場で変更することなく、トリミング、置換、並べ替えができます。 -セッションを使用している場合、`call_model_input_filter` はセッション履歴がすでにロードされ、現在のターンとマージされた後に実行されます。その前のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。 +セッションを使用している場合、`call_model_input_filter` はセッション履歴がすでに読み込まれ、現在のターンとマージされた後に実行されます。その前段のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用してください。 -`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使用した OpenAI サーバー管理の会話状態を使用している場合、hook は次の Responses API 呼び出しのために準備された payload に対して実行されます。その payload は、以前の履歴全体の再生ではなく、すでに新しいターンの差分のみを表している場合があります。返したアイテムだけが、そのサーバー管理の継続に対して送信済みとしてマークされます。 +`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使用して OpenAI のサーバー管理の会話状態を使用している場合、このフックは次の Responses API 呼び出し用に準備されたペイロード上で実行されます。そのペイロードは、以前の履歴全体の再生ではなく、すでに新しいターンの差分のみを表している場合があります。返した項目だけが、そのサーバー管理の継続に対して送信済みとしてマークされます。 -機密データを redact したり、長い履歴を trim したり、追加のシステムガイダンスを注入したりするには、`run_config` 経由で実行ごとに hook を設定します。 +機密データの編集、長い履歴のトリミング、追加のシステムガイダンスの挿入を行うには、実行ごとに `run_config` でこのフックを設定します。 ## エラーと復旧 ### エラーハンドラー -すべての `Runner` エントリーポイントは `error_handlers` を受け入れます。これはエラー種別をキーとする dict です。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。 +すべての `Runner` エントリーポイントは、エラー種別をキーとする dict である `error_handlers` を受け取ります。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。 ```python from agents import ( @@ -469,9 +469,9 @@ result = Runner.run_sync( print(result.final_output) ``` -fallback 出力を会話履歴に追加したくない場合は、`include_in_history=False` を設定します。 +フォールバック出力を会話履歴に追加したくない場合は、`include_in_history=False` を設定します。 -モデル拒否で `ModelRefusalError` により実行を終了する代わりに、アプリケーション固有の fallback を生成したい場合は `"model_refusal"` を使用します。 +モデル拒否が `ModelRefusalError` で実行を終了するのではなく、アプリケーション固有のフォールバックを生成すべき場合は、`"model_refusal"` を使用します。 ```python from pydantic import BaseModel @@ -503,37 +503,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## Durable execution 統合と human-in-the-loop +## 耐久実行インテグレーションと human-in-the-loop -ツール承認の pause/resume パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 -以下の統合は、実行が長い待機、retry、またはプロセス再起動にまたがる可能性がある場合の durable orchestration のためのものです。 +ツール承認の一時停止 / 再開パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。 +以下のインテグレーションは、実行が長い待機、再試行、またはプロセス再起動をまたぐ可能性がある場合の耐久性のあるオーケストレーション向けです。 ### Dapr -Agents SDK の [Dapr](https://dapr.io) Diagrid 統合を使用して、人間参加型のサポートにより障害から自動的に復旧する、durable で長時間実行されるエージェントを実行できます。Dapr はベンダー中立の [CNCF](https://cncf.io) workflow orchestrator です。Dapr と OpenAI エージェントの開始方法は [こちら](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai) です。 +Agents SDK の [Dapr](https://dapr.io) Diagrid インテグレーションを使用すると、human-in-the-loop サポート付きで障害から自動的に復旧する、耐久性のある長時間実行エージェントを実行できます。Dapr はベンダーニュートラルな [CNCF](https://cncf.io) ワークフローオーケストレーターです。Dapr と OpenAI エージェントの始め方は [こちら](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai) です。 ### Temporal -Agents SDK の [Temporal](https://temporal.io/) 統合を使用して、人間参加型タスクを含む durable で長時間実行される workflow を実行できます。長時間実行タスクを完了するために 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) です。 ### Restate -Agents SDK の [Restate](https://restate.dev/) 統合を使用して、人間の承認、ハンドオフ、セッション管理を含む軽量で durable なエージェントを利用できます。この統合は依存関係として Restate の single-binary runtime を必要とし、エージェントをプロセス / コンテナーまたはサーバーレス関数として実行することをサポートします。 -詳細については、[概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) を読むか、[ドキュメント](https://docs.restate.dev/ai) を参照してください。 +Agents SDK の [Restate](https://restate.dev/) インテグレーションを使用すると、人間による承認、ハンドオフ、セッション管理を含む、軽量で耐久性のあるエージェントを利用できます。このインテグレーションは依存関係として Restate の単一バイナリランタイムを必要とし、エージェントをプロセス / コンテナまたはサーバーレス関数として実行することをサポートします。 +詳細は [概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) を読むか、[ドキュメント](https://docs.restate.dev/ai) を参照してください。 ### DBOS -Agents SDK の [DBOS](https://dbos.dev/) 統合を使用して、障害や再起動をまたいで進行状況を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、人間参加型 workflow、ハンドオフをサポートします。sync と async の両方のメソッドをサポートします。この統合に必要なのは SQLite または Postgres データベースだけです。詳細については、統合 [repo](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。 +Agents SDK の [DBOS](https://dbos.dev/) インテグレーションを使用すると、障害や再起動をまたいで進捗を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。同期メソッドと非同期メソッドの両方をサポートします。このインテグレーションに必要なのは SQLite または Postgres データベースのみです。詳細はインテグレーションの [repo](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/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` 制限を超えたときに発生します。指定された対話ターン数内でエージェントがタスクを完了できなかったことを示します。制限を無効にするには `max_turns=None` を設定します。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成したときに発生します。これには次が含まれます。 - - 不正な JSON: モデルがツール呼び出し用、または直接出力内で不正な JSON 構造を提供した場合。特に特定の `output_type` が定義されている場合です。 - - 予期しないツール関連の失敗: モデルが期待される方法でツールを使用できなかった場合 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが構成された timeout を超え、そのツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。 -- [`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` 制限を超えた場合に発生します。エージェントが指定された相互作用ターン数内にタスクを完了できなかったことを示します。制限を無効にするには `max_turns=None` を設定します。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。これには以下が含まれる場合があります。 + - 不正な形式の JSON: モデルがツール呼び出しまたは直接出力で不正な形式の JSON 構造を提供した場合、特に特定の `output_type` が定義されている場合です。 + - 予期しないツール関連の失敗: モデルが期待どおりにツールを使用できなかった場合です +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが設定されたタイムアウトを超え、そのツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。 +- [`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/sandbox/clients.md b/docs/ja/sandbox/clients.md index ae415e8c81..ee9e831f80 100644 --- a/docs/ja/sandbox/clients.md +++ b/docs/ja/sandbox/clients.md @@ -2,13 +2,13 @@ search: exclude: true --- -# Sandbox クライアント +# サンドボックスクライアント -このページでは、 sandbox の作業をどこで実行するかを選択します。ほとんどの場合、 `SandboxAgent` の定義は同じままで、 sandbox クライアントとクライアント固有のオプションのみが [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変わります。 +このページでは、サンドボックスでの作業をどこで実行するかを選択します。ほとんどの場合、`SandboxAgent` の定義は同じままにし、サンドボックスクライアントとクライアント固有のオプションを [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変更します。 -!!! warning "Beta 機能" +!!! warning "ベータ機能" - Sandbox エージェントは beta です。一般提供前に API の詳細、デフォルト、対応機能が変更される可能性があり、時間の経過とともにより高度な機能も追加される予定です。 + サンドボックスエージェントはベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能が変更される可能性があります。また、時間とともにより高度な機能が追加される見込みです。 ## 判断ガイド @@ -16,28 +16,28 @@ search: | 目的 | まず使うもの | 理由 | | --- | --- | --- | -| macOS または Linux で最速のローカル反復 | `UnixLocalSandboxClient` | 追加インストール不要で、シンプルなローカルファイルシステム開発ができます。 | +| macOS または Linux での最速のローカル反復 | `UnixLocalSandboxClient` | 追加インストール不要で、シンプルなローカルファイルシステム開発ができます。 | | 基本的なコンテナ分離 | `DockerSandboxClient` | 特定のイメージを使って Docker 内で作業を実行します。 | -| ホスト型実行または本番環境に近い分離 | ホスト型 sandbox クライアント | ワークスペースの境界をプロバイダー管理の環境に移します。 | +| ホスト型実行または本番環境スタイルの分離 | ホスト型サンドボックスクライアント | ワークスペース境界をプロバイダー管理環境へ移します。 | ## ローカルクライアント -ほとんどのユーザーは、まず次の 2 つの sandbox クライアントのいずれかから始めてください。 +ほとんどのユーザーは、これら 2 つのサンドボックスクライアントのいずれかから始めることをおすすめします。
| クライアント | インストール | 選ぶ場面 | 例 | | --- | --- | --- | --- | -| `UnixLocalSandboxClient` | なし | macOS または Linux で最速にローカル反復したい場合。ローカル開発の良いデフォルトです。 | [Unix-local スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | -| `DockerSandboxClient` | `openai-agents[docker]` | コンテナ分離や、ローカルでの同等性のために特定のイメージが必要な場合。 | [Docker スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) | +| `UnixLocalSandboxClient` | なし | macOS または Linux で最速のローカル反復が必要な場合。ローカル開発の既定として適しています。 | [Unix-local スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | +| `DockerSandboxClient` | `openai-agents[docker]` | コンテナ分離、またはローカルで同等性を保つための特定のイメージが必要な場合。 | [Docker スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
-Unix-local は、ローカルファイルシステムを対象にした開発を始める最も簡単な方法です。より強い環境分離や本番環境に近い同等性が必要になったら、 Docker またはホスト型プロバイダーに移行してください。 +Unix-local は、ローカルファイルシステムに対して開発を始める最も簡単な方法です。より強い環境分離や本番環境スタイルの同等性が必要になったら、Docker またはホスト型プロバイダーへ移行してください。 -Unix-local から Docker に切り替えるには、エージェント定義はそのままにして、 run config のみを変更します。 +Unix-local から Docker に切り替えるには、エージェント定義は同じままにして、実行設定だけを変更します。 ```python from docker import from_env as docker_from_env @@ -54,74 +54,74 @@ run_config = RunConfig( ) ``` -これは、コンテナ分離やイメージの同等性が必要な場合に使用します。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。 +コンテナ分離またはイメージの同等性が必要な場合に使用してください。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。 ## マウントとリモートストレージ -mount エントリは公開するストレージを記述し、 mount 戦略は sandbox バックエンドがそのストレージをどのように接続するかを記述します。組み込みの mount エントリと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダーの戦略は `agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。 +マウントエントリーはどのストレージを公開するかを表し、マウント戦略はサンドボックスバックエンドがそのストレージをどのようにアタッチするかを表します。組み込みのマウントエントリーと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダーの戦略は `agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。 -一般的な mount オプション: +一般的なマウントオプション: -- `mount_path`: sandbox 内でストレージが表示される場所です。相対パスは manifest ルート配下で解決され、絶対パスはそのまま使われます。 -- `read_only`: デフォルトは `True` です。 sandbox からマウントされたストレージへ書き戻す必要がある場合にのみ `False` に設定してください。 -- `mount_strategy`: 必須です。 mount エントリと sandbox バックエンドの両方に適合する戦略を使用してください。 +- `mount_path`: ストレージがサンドボックス内で表示される場所です。相対パスはマニフェストルート配下で解決され、絶対パスはそのまま使用されます。 +- `read_only`: 既定は `True` です。サンドボックスがマウントされたストレージへ書き戻す必要がある場合にのみ `False` に設定してください。 +- `mount_strategy`: 必須です。マウントエントリーとサンドボックスバックエンドの両方に合う戦略を使用してください。 -mount は一時的なワークスペースエントリとして扱われます。スナップショットおよび永続化フローでは、マウントされたリモートストレージを保存済みワークスペースにコピーするのではなく、マウントされたパスを切り離すかスキップします。 +マウントは一時的なワークスペースエントリーとして扱われます。スナップショットと永続化のフローでは、マウントされたリモートストレージを保存済みワークスペースへコピーするのではなく、マウントされたパスをデタッチするかスキップします。 -汎用のローカル / コンテナ戦略: +汎用ローカル / コンテナ戦略:
-| 戦略またはパターン | 使用する場面 | 注記 | +| 戦略またはパターン | 使用する場面 | 備考 | | --- | --- | --- | -| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | sandbox イメージで `rclone` を実行できる場合。 | S3 、 GCS 、 R2 、 Azure Blob 、 Box をサポートします。`RcloneMountPattern` は `fuse` モードまたは `nfs` モードで実行できます。 | -| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` があり、 Mountpoint スタイルの S3 または S3 互換アクセスを使いたい場合。 | `S3Mount` と `GCSMount` をサポートします。 | -| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` と FUSE サポートがある場合。 | `AzureBlobMount` をサポートします。 | -| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` があり、既存の S3 Files mount ターゲットに到達できる場合。 | `S3FilesMount` をサポートします。 | -| `DockerVolumeMountStrategy(driver=...)` | コンテナ起動前に Docker が volume-driver ベースの mount を接続すべき場合。 | Docker 専用です。 S3 、 GCS 、 R2 、 Azure Blob 、 Box は `rclone` をサポートし、 S3 と GCS は `mountpoint` もサポートします。 | +| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | サンドボックスイメージで `rclone` を実行できる場合。 | S3、GCS、R2、Azure Blob、Box をサポートします。`RcloneMountPattern` は `fuse` モードまたは `nfs` モードで実行できます。 | +| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` があり、Mountpoint スタイルの S3 または S3 互換アクセスが必要な場合。 | `S3Mount` と `GCSMount` をサポートします。 | +| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` があり、FUSE サポートがある場合。 | `AzureBlobMount` をサポートします。 | +| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` があり、既存の S3 Files マウントターゲットに到達できる場合。 | `S3FilesMount` をサポートします。 | +| `DockerVolumeMountStrategy(driver=...)` | Docker がコンテナ起動前にボリュームドライバー対応のマウントをアタッチする必要がある場合。 | Docker のみです。`rclone` は S3、GCS、R2、Azure Blob、Box をサポートし、`mountpoint` は S3 と GCS もサポートします。 |
-## 対応するホスト型プラットフォーム +## サポートされるホスト型プラットフォーム -ホスト型環境が必要な場合でも、通常は同じ `SandboxAgent` 定義をそのまま使え、 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で sandbox クライアントのみを変更します。 +ホスト型環境が必要な場合、通常は同じ `SandboxAgent` 定義をそのまま引き継ぎ、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] でサンドボックスクライアントだけを変更します。 -このリポジトリのチェックアウト版ではなく公開済み SDK を使っている場合は、対応するパッケージ extra を通じて sandbox-client 依存関係をインストールしてください。 +このリポジトリのチェックアウトではなく公開されている SDK を使用している場合は、対応するパッケージ extra を通じてサンドボックスクライアントの依存関係をインストールしてください。 -プロバイダー固有のセットアップに関する注意点や、リポジトリに含まれる拡張の例へのリンクについては、 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md) を参照してください。 +プロバイダー固有のセットアップメモと、チェックイン済みの拡張コード例へのリンクについては、[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md) を参照してください。
| クライアント | インストール | 例 | | --- | --- | --- | -| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) | -| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) | -| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) | -| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) | -| `ModalSandboxClient` | `openai-agents[modal]` | [Modal runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) | -| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) | -| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) | +| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) | +| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) | +| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) | +| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) | +| `ModalSandboxClient` | `openai-agents[modal]` | [Modal ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) | +| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) | +| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
-ホスト型 sandbox クライアントは、プロバイダー固有の mount 戦略を公開しています。ストレージプロバイダーに最も適したバックエンドと mount 戦略を選択してください。 +ホスト型サンドボックスクライアントは、プロバイダー固有のマウント戦略を公開します。ストレージプロバイダーに最も合うバックエンドとマウント戦略を選択してください。
-| バックエンド | mount に関する注記 | +| バックエンド | マウントに関する注記 | | --- | --- | -| Docker | `S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` 、 `S3FilesMount` を、 `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略でサポートします。 | -| `ModalSandboxClient` | `S3Mount` 、 `R2Mount` 、 HMAC 認証された `GCSMount` に対して、 `ModalCloudBucketMountStrategy` による Modal cloud bucket mount をサポートします。インライン認証情報または名前付き Modal Secret を使用できます。 | -| `CloudflareSandboxClient` | `S3Mount` 、 `R2Mount` 、 HMAC 認証された `GCSMount` に対して、 `CloudflareBucketMountStrategy` による Cloudflare bucket mount をサポートします。 | -| `BlaxelSandboxClient` | `S3Mount` 、 `R2Mount` 、 `GCSMount` に対して、 `BlaxelCloudBucketMountStrategy` による cloud bucket mount をサポートします。また、 `agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` による永続的な Blaxel Drive もサポートします。 | -| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 | -| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 | -| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 | -| `VercelSandboxClient` | 現時点ではホスト型固有の mount 戦略は公開されていません。代わりに manifest ファイル、リポジトリ、またはその他のワークスペース入力を使用してください。 | +| Docker | `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略で、`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` をサポートします。 | +| `ModalSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`ModalCloudBucketMountStrategy` による Modal のクラウドバケットマウントをサポートします。インライン認証情報、または名前付きの Modal Secret を使用できます。 | +| `CloudflareSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`CloudflareBucketMountStrategy` による Cloudflare バケットマウントをサポートします。 | +| `BlaxelSandboxClient` | `S3Mount`、`R2Mount`、`GCSMount` で、`BlaxelCloudBucketMountStrategy` によるクラウドバケットマウントをサポートします。`agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` による永続的な Blaxel Drives もサポートします。 | +| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 | +| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 | +| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 | +| `VercelSandboxClient` | 現時点ではホスト型固有のマウント戦略は公開されていません。代わりにマニフェストファイル、リポジトリ、またはその他のワークスペース入力を使用してください。 |
-以下の表は、各バックエンドがどのリモートストレージエントリを直接マウントできるかをまとめたものです。 +以下の表は、各バックエンドが直接マウントできるリモートストレージエントリーをまとめたものです。
@@ -138,4 +138,4 @@ mount は一時的なワークスペースエントリとして扱われます
-さらに実行可能な例については、ローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターンは [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox) を、ホスト型 sandbox クライアントについては [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions) を参照してください。 \ No newline at end of file +実行可能なコード例をさらに見るには、ローカル、コーディング、メモリ、ハンドオフ、エージェント合成パターンについては [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox) を、ホスト型サンドボックスクライアントについては [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions) を参照してください。 \ No newline at end of file diff --git a/docs/ja/sandbox/guide.md b/docs/ja/sandbox/guide.md index 01005905cb..4380711468 100644 --- a/docs/ja/sandbox/guide.md +++ b/docs/ja/sandbox/guide.md @@ -6,35 +6,35 @@ search: !!! warning "ベータ機能" - サンドボックスエージェントはベータ版です。一般提供までに API の詳細、デフォルト、サポートされる機能が変更される可能性があり、今後より高度な機能が追加される見込みです。 + サンドボックスエージェントはベータ版です。一般提供前に API の詳細、デフォルト、サポートされる機能が変更される可能性があります。また、時間の経過とともにより高度な機能が追加される予定です。 -現代的なエージェントは、ファイルシステム上の実際のファイルを操作できると最も効果的に機能します。**サンドボックスエージェント**は、専用ツールやシェルコマンドを利用して、大規模なドキュメントセットの検索や操作、ファイル編集、成果物生成、コマンド実行を行えます。サンドボックスは、エージェントがユーザーの代わりに作業するために使える永続的なワークスペースをモデルに提供します。Agents SDK のサンドボックスエージェントを使うと、サンドボックス環境と組み合わせたエージェントを簡単に実行でき、ファイルシステム上に適切なファイルを配置し、サンドボックスをオーケストレーションして、大規模なタスクの開始、停止、再開を容易にできます。 +現代的なエージェントは、ファイルシステム上の実ファイルを操作できるときに最も効果的に動作します。**サンドボックスエージェント** は、専用ツールとシェルコマンドを使用して、大規模なドキュメントセットの検索や操作、ファイルの編集、成果物の生成、コマンドの実行を行えます。サンドボックスは、エージェントがユーザーの代わりに作業するために利用できる永続的なワークスペースをモデルに提供します。Agents SDK のサンドボックスエージェントは、サンドボックス環境と組み合わせたエージェントを簡単に実行できるようにし、ファイルシステム上に適切なファイルを配置し、サンドボックスをオーケストレーションして、タスクを大規模に開始、停止、再開しやすくします。 -エージェントが必要とするデータを中心にワークスペースを定義します。GitHub リポジトリ、ローカルファイルとディレクトリ、合成タスクファイル、S3 や Azure Blob Storage などのリモートファイルシステム、およびユーザーが提供するその他のサンドボックス入力から開始できます。 +エージェントが必要とするデータを中心にワークスペースを定義します。ワークスペースは、GitHub リポジトリ、ローカルファイルとディレクトリ、合成タスクファイル、S3 や Azure Blob Storage などのリモートファイルシステム、その他提供するサンドボックス入力から開始できます。
-![コンピュート付きサンドボックスエージェントハーネス](../assets/images/harness_with_compute.png) +![コンピュートを備えたサンドボックスエージェントハーネス](../assets/images/harness_with_compute.png)
-`SandboxAgent` は引き続き `Agent` です。`instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、ガードレール、フックといった通常のエージェントサーフェスを保持し、通常の `Runner` API を通じて実行されます。変わるのは実行境界です。 +`SandboxAgent` は引き続き `Agent` です。`instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、ガードレール、フックなど、通常のエージェントのインターフェイスを保持し、通常の `Runner` API を通じて実行されます。変わるのは実行境界です。 -- `SandboxAgent` はエージェント自体を定義します。通常のエージェント設定に加えて、`default_manifest`、`base_instructions`、`run_as` のようなサンドボックス固有のデフォルト、およびファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションなどの機能を定義します。 -- `Manifest` は、新しいサンドボックスワークスペースの開始時に必要な内容とレイアウトを宣言します。ファイル、リポジトリ、マウント、環境などが含まれます。 -- サンドボックスセッションは、コマンドが実行されファイルが変更される、稼働中の分離環境です。 -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、その実行がどのようにサンドボックスセッションを取得するかを決定します。たとえば、直接注入する、シリアライズされたサンドボックスセッション状態から再接続する、またはサンドボックスクライアントを通じて新しいサンドボックスセッションを作成する、といった方法です。 -- 保存されたサンドボックス状態とスナップショットにより、後続の実行が以前の作業に再接続したり、保存済み内容から新しいサンドボックスセッションを初期化したりできます。 +- `SandboxAgent` はエージェント自体を定義します。通常のエージェント設定に加えて、`default_manifest`、`base_instructions`、`run_as` などのサンドボックス固有のデフォルト、ファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションなどの機能を含みます。 +- `Manifest` は、ファイル、リポジトリ、マウント、環境など、新規サンドボックスワークスペースの望ましい初期内容とレイアウトを宣言します。 +- サンドボックスセッションは、コマンドが実行されファイルが変更される、ライブの隔離環境です。 +- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、実行がサンドボックスセッションをどのように取得するかを決定します。たとえば、直接注入する、シリアライズ済みのサンドボックスセッション状態から再接続する、またはサンドボックスクライアントを通じて新規サンドボックスセッションを作成する、といった方法があります。 +- 保存済みのサンドボックス状態とスナップショットにより、後続の実行は以前の作業に再接続したり、保存済みの内容から新規サンドボックスセッションを初期化したりできます。 -`Manifest` は、新規セッションのワークスペース契約であり、すべての稼働中サンドボックスに対する完全な信頼できる情報源ではありません。実行時の有効なワークスペースは、再利用されたサンドボックスセッション、シリアライズされたサンドボックスセッション状態、または実行時に選択されたスナップショットに由来する場合もあります。 +`Manifest` は新規セッションのワークスペース契約であり、すべてのライブサンドボックスに対する完全な唯一の情報源ではありません。実行の有効なワークスペースは、再利用されたサンドボックスセッション、シリアライズ済みのサンドボックスセッション状態、または実行時に選択されたスナップショットから取得される場合があります。 -このページ全体で「サンドボックスセッション」とは、サンドボックスクライアントによって管理される稼働中の実行環境を意味します。これは、[Sessions](../sessions/index.md) で説明されている SDK の会話用 [`Session`][agents.memory.session.Session] インターフェイスとは異なります。 +このページ全体で、「サンドボックスセッション」とはサンドボックスクライアントによって管理されるライブ実行環境を意味します。これは、[Sessions](../sessions/index.md) で説明されている SDK の会話型 [`Session`][agents.memory.session.Session] インターフェイスとは異なります。 -外側のランタイムは引き続き、承認、トレーシング、ハンドオフ、再開のための記録管理を所有します。サンドボックスセッションは、コマンド、ファイル変更、環境分離を所有します。この分離はモデルの中核的な部分です。 +外側のランタイムは引き続き、承認、トレーシング、ハンドオフ、再開の記録管理を所有します。サンドボックスセッションは、コマンド、ファイル変更、環境隔離を所有します。この分担は、このモデルの中核です。 -### 構成要素の関係 +### 各要素の関係 -サンドボックス実行は、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。ランナーはエージェントを準備し、稼働中のサンドボックスセッションにバインドし、後続の実行のために状態を保存できます。 +サンドボックス実行は、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。Runner はエージェントを準備し、ライブのサンドボックスセッションにバインドし、後続の実行のために状態を保存できます。 ```mermaid flowchart LR @@ -50,205 +50,205 @@ flowchart LR sandbox --> saved ``` -サンドボックス固有のデフォルトは `SandboxAgent` に保持します。実行ごとのサンドボックスセッション選択は `SandboxRunConfig` に保持します。 +サンドボックス固有のデフォルトは `SandboxAgent` に保持します。実行ごとのサンドボックスセッションの選択は `SandboxRunConfig` に保持します。 -ライフサイクルは 3 つのフェーズで考えます。 +ライフサイクルは 3 つのフェーズで考えてください。 -1. `SandboxAgent`、`Manifest`、および機能を使って、エージェントと新規ワークスペース契約を定義します。 -2. サンドボックスセッションを注入、再開、または作成する `SandboxRunConfig` を `Runner` に渡して実行します。 -3. ランナー管理の `RunState`、明示的なサンドボックス `session_state`、または保存済みワークスペーススナップショットから後で続行します。 +1. `SandboxAgent`、`Manifest`、機能を使って、エージェントと新規ワークスペース契約を定義します。 +2. サンドボックスセッションを注入、再開、または作成する `SandboxRunConfig` を `Runner` に渡して、実行を行います。 +3. Runner 管理の `RunState`、明示的なサンドボックス `session_state`、または保存済みワークスペーススナップショットから、後で継続します。 -シェルアクセスがたまに使う 1 つのツールにすぎない場合は、[ツールガイド](../tools.md) のホスト型シェルから始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合は、サンドボックスエージェントを使用します。 +シェルアクセスが時々使うツールの 1 つにすぎない場合は、[ツールガイド](../tools.md) のホスト型シェルから始めてください。ワークスペースの隔離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合は、サンドボックスエージェントを選択してください。 -## 使用場面 +## 使用すべき場面 サンドボックスエージェントは、ワークスペース中心のワークフローに適しています。例: -- コーディングとデバッグ。たとえば、GitHub リポジトリ内の issue レポートに対する自動修正をオーケストレーションし、対象テストを実行する場合 -- ドキュメント処理と編集。たとえば、ユーザーの財務書類から情報を抽出し、記入済み税務フォームのドラフトを作成する場合 -- ファイルに基づくレビューまたは分析。たとえば、回答前にオンボーディング資料、生成レポート、成果物バンドルを確認する場合 -- 分離されたマルチエージェントパターン。たとえば、各レビュアーやコーディングサブエージェントに専用ワークスペースを与える場合 -- 複数ステップのワークスペースタスク。たとえば、ある実行でバグを修正し、後で回帰テストを追加する、またはスナップショットやサンドボックスセッション状態から再開する場合 +- コーディングとデバッグ。たとえば、GitHub リポジトリ内の issue レポートに対する自動修正をオーケストレーションし、対象を絞ったテストを実行する場合 +- ドキュメント処理と編集。たとえば、ユーザーの財務ドキュメントから情報を抽出し、完成済みの税務フォーム草案を作成する場合 +- ファイルに基づくレビューまたは分析。たとえば、回答前にオンボーディング資料、生成されたレポート、成果物バンドルを確認する場合 +- 隔離されたマルチエージェントパターン。たとえば、各レビュアーまたはコーディングサブエージェントに独自のワークスペースを与える場合 +- 複数ステップのワークスペースタスク。たとえば、ある実行でバグを修正し、後で回帰テストを追加する場合、またはスナップショットやサンドボックスセッション状態から再開する場合 -ファイルや稼働中のファイルシステムへのアクセスが不要な場合は、引き続き `Agent` を使用してください。シェルアクセスがたまに使う機能にすぎない場合は、ホスト型シェルを追加します。ワークスペース境界そのものが機能の一部である場合は、サンドボックスエージェントを使用します。 +ファイルや生きたファイルシステムへのアクセスが不要な場合は、`Agent` を使い続けてください。シェルアクセスが時々使う機能の 1 つにすぎない場合は、ホスト型シェルを追加してください。ワークスペース境界自体が機能の一部である場合は、サンドボックスエージェントを使用してください。 ## サンドボックスクライアントの選択 -ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ分離やイメージの同等性が必要になったら `DockerSandboxClient` に移行します。プロバイダー管理の実行が必要な場合は、ホスト型プロバイダーに移行します。 +ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ隔離やイメージの一致性が必要になったら `DockerSandboxClient` に移行してください。プロバイダー管理の実行が必要になったら、ホスト型プロバイダーに移行してください。 -ほとんどの場合、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] でサンドボックスクライアントとそのオプションを変更しても、`SandboxAgent` 定義は同じままです。ローカル、Docker、ホスト型、リモートマウントのオプションについては、[サンドボックスクライアント](clients.md) を参照してください。 +ほとんどの場合、`SandboxAgent` 定義は同じままで、サンドボックスクライアントとそのオプションを [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変更します。ローカル、Docker、ホスト型、リモートマウントのオプションについては、[サンドボックスクライアント](clients.md) を参照してください。 -## 中核要素 +## 主要な構成要素
-| レイヤー | 主な SDK 要素 | 答える内容 | +| レイヤー | 主な SDK 構成要素 | 答える問い | | --- | --- | --- | -| エージェント定義 | `SandboxAgent`、`Manifest`、機能 | どのエージェントが実行され、新規セッションのワークスペース契約として何から開始するべきですか? | -| サンドボックス実行 | `SandboxRunConfig`、サンドボックスクライアント、稼働中のサンドボックスセッション | この実行はどのように稼働中のサンドボックスセッションを取得し、どこで作業を実行しますか? | -| 保存済みサンドボックス状態 | `RunState` サンドボックスペイロード、`session_state`、スナップショット | このワークフローはどのように以前のサンドボックス作業へ再接続するか、または保存済み内容から新しいサンドボックスセッションを初期化しますか? | +| エージェント定義 | `SandboxAgent`, `Manifest`, capabilities | どのエージェントを実行し、新規セッションのワークスペース契約を何から開始すべきですか？ | +| サンドボックス実行 | `SandboxRunConfig`、サンドボックスクライアント、ライブサンドボックスセッション | この実行はライブサンドボックスセッションをどのように取得し、作業はどこで実行されますか？ | +| 保存済みサンドボックス状態 | `RunState` サンドボックスペイロード、`session_state`、スナップショット | このワークフローは以前のサンドボックス作業にどのように再接続するか、または保存済み内容から新規サンドボックスセッションをどのように初期化しますか？ |
-主な SDK 要素は、次のようにこれらのレイヤーに対応します。 +主な SDK 構成要素は、これらのレイヤーに次のように対応します。
-| 要素 | 所有するもの | 問うべき質問 | +| 構成要素 | 管理するもの | 問うべきこと | | --- | --- | --- | -| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | エージェント定義 | このエージェントは何を行うべきで、どのデフォルトを一緒に持たせるべきですか? | -| [`Manifest`][agents.sandbox.manifest.Manifest] | 新規セッションのワークスペースファイルとフォルダー | 実行開始時に、ファイルシステム上にどのファイルとフォルダーが存在するべきですか? | -| [`Capability`][agents.sandbox.capabilities.capability.Capability] | サンドボックスネイティブの動作 | このエージェントにどのツール、指示断片、またはランタイム動作を付与するべきですか? | -| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 実行ごとのサンドボックスクライアントとサンドボックスセッションソース | この実行はサンドボックスセッションを注入、再開、または作成するべきですか? | -| [`RunState`][agents.run_state.RunState] | ランナー管理の保存済みサンドボックス状態 | 以前のランナー管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継ぎますか? | -| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 明示的にシリアライズされたサンドボックスセッション状態 | `RunState` の外で既にシリアライズしたサンドボックス状態から再開したいですか? | -| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 新しいサンドボックスセッション用の保存済みワークスペース内容 | 新しいサンドボックスセッションを保存済みファイルと成果物から開始するべきですか? | +| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | エージェント定義 | このエージェントは何を行うべきで、どのデフォルトを一緒に持ち運ぶべきですか？ | +| [`Manifest`][agents.sandbox.manifest.Manifest] | 新規セッションのワークスペースファイルとフォルダー | 実行開始時に、ファイルシステム上にどのファイルとフォルダーが存在すべきですか？ | +| [`Capability`][agents.sandbox.capabilities.capability.Capability] | サンドボックスネイティブな挙動 | どのツール、指示の断片、またはランタイム挙動をこのエージェントに付与すべきですか？ | +| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 実行ごとのサンドボックスクライアントとサンドボックスセッションの取得元 | この実行ではサンドボックスセッションを注入、再開、または作成すべきですか？ | +| [`RunState`][agents.run_state.RunState] | Runner が管理する保存済みサンドボックス状態 | 以前の Runner 管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継いでいますか？ | +| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 明示的なシリアライズ済みサンドボックスセッション状態 | `RunState` の外部で既にシリアライズしたサンドボックス状態から再開したいですか？ | +| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 新規サンドボックスセッション用の保存済みワークスペース内容 | 新規サンドボックスセッションを保存済みファイルや成果物から開始すべきですか？ |
-実用的な設計順序は次のとおりです。 +実践的な設計順序は次のとおりです。 1. `Manifest` で新規セッションのワークスペース契約を定義します。 2. `SandboxAgent` でエージェントを定義します。 -3. 組み込みまたはカスタム機能を追加します。 -4. `RunConfig(sandbox=SandboxRunConfig(...))` で、各実行がどのようにサンドボックスセッションを取得するかを決定します。 +3. 組み込みまたはカスタムの機能を追加します。 +4. 各実行がサンドボックスセッションをどのように取得するかを `RunConfig(sandbox=SandboxRunConfig(...))` で決定します。 ## サンドボックス実行の準備 -実行時、ランナーはその定義を具体的なサンドボックス対応実行に変換します。 +実行時に、Runner はその定義を具体的なサンドボックス backed の実行に変換します。 1. `SandboxRunConfig` からサンドボックスセッションを解決します。 - `session=...` を渡した場合、その稼働中のサンドボックスセッションを再利用します。 - そうでない場合は、`client=...` を使って作成または再開します。 + `session=...` を渡すと、そのライブサンドボックスセッションを再利用します。 + それ以外の場合は、`client=...` を使用して作成または再開します。 2. 実行の有効なワークスペース入力を決定します。 実行がサンドボックスセッションを注入または再開する場合、その既存のサンドボックス状態が優先されます。 - それ以外の場合、ランナーは一回限りのマニフェスト上書きまたは `agent.default_manifest` から開始します。 - これが、`Manifest` だけではすべての実行の最終的な稼働中ワークスペースを定義しない理由です。 -3. 機能に、結果のマニフェストを処理させます。 - これにより、最終的なエージェントが準備される前に、機能がファイル、マウント、またはその他のワークスペーススコープの動作を追加できます。 -4. 固定の順序で最終 instructions を構築します。 - SDK のデフォルトサンドボックスプロンプト、または明示的に上書きした場合は `base_instructions`、次に `instructions`、次に機能の指示断片、次にリモートマウントポリシーテキスト、次にレンダリングされたファイルシステムツリーです。 -5. 機能ツールを稼働中のサンドボックスセッションにバインドし、準備済みエージェントを通常の `Runner` API を通じて実行します。 + それ以外の場合、Runner は 1 回限りのマニフェストオーバーライド、または `agent.default_manifest` から開始します。 + そのため、`Manifest` だけでは、すべての実行における最終的なライブワークスペースは定義されません。 +3. 機能に、結果として得られたマニフェストを処理させます。 + これにより、最終的なエージェントを準備する前に、機能がファイル、マウント、またはその他のワークスペーススコープの挙動を追加できます。 +4. 固定された順序で最終的な instructions を構築します。 + SDK のデフォルトサンドボックスプロンプト、または明示的にオーバーライドした場合は `base_instructions`、次に `instructions`、次に機能の指示断片、次にリモートマウントのポリシーテキスト、最後にレンダリングされたファイルシステムツリーです。 +5. 機能ツールをライブサンドボックスセッションにバインドし、通常の `Runner` API を通じて準備済みエージェントを実行します。 -サンドボックス化によってターンの意味は変わりません。ターンは引き続きモデルのステップであり、単一のシェルコマンドやサンドボックスアクションではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。一部の作業はサンドボックス実行レイヤー内に留まる場合があり、他のアクションはツール結果、承認、または別のモデルステップを必要とするその他の状態を返す場合があります。実用上のルールとして、サンドボックス作業後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、別のターンが消費されます。 +サンドボックス化によって、ターンの意味は変わりません。ターンは引き続きモデルステップであり、単一のシェルコマンドやサンドボックスアクションではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。一部の作業はサンドボックス実行レイヤー内に留まる一方、別のアクションはツール結果、承認、または次のモデルステップを必要とするその他の状態を返す場合があります。実践上の規則として、サンドボックス作業の後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、もう 1 ターンが消費されます。 -これらの準備ステップがあるため、`SandboxAgent` を設計するときに主に考えるべきサンドボックス固有のオプションは、`default_manifest`、`instructions`、`base_instructions`、`capabilities`、`run_as` です。 +これらの準備手順があるため、`SandboxAgent` を設計するときに考えるべき主なサンドボックス固有オプションは、`default_manifest`、`instructions`、`base_instructions`、`capabilities`、`run_as` です。 -## `SandboxAgent` オプション +## `SandboxAgent` のオプション -これらは通常の `Agent` フィールドに加わるサンドボックス固有のオプションです。 +通常の `Agent` フィールドに加えて用意されている、サンドボックス固有のオプションは次のとおりです。
-| オプション | 最適な用途 | +| オプション | 主な用途 | | --- | --- | -| `default_manifest` | ランナーが作成する新しいサンドボックスセッションのデフォルトワークスペース。 | -| `instructions` | SDK サンドボックスプロンプトの後に追加される追加の役割、ワークフロー、成功基準。 | -| `base_instructions` | SDK サンドボックスプロンプトを置き換える高度なエスケープハッチ。 | -| `capabilities` | このエージェントに持たせるべきサンドボックスネイティブのツールと動作。 | +| `default_manifest` | Runner が作成する新規サンドボックスセッションのデフォルトワークスペース。 | +| `instructions` | SDK サンドボックスプロンプトの後に追加される、追加の役割、ワークフロー、成功基準。 | +| `base_instructions` | SDK サンドボックスプロンプトを置き換える高度なオーバーライド手段。 | +| `capabilities` | このエージェントと一緒に持ち運ぶべきサンドボックスネイティブなツールと挙動。 | | `run_as` | シェルコマンド、ファイル読み取り、パッチなど、モデル向けサンドボックスツールのユーザー ID。 |
-サンドボックスクライアントの選択、サンドボックスセッションの再利用、マニフェスト上書き、スナップショット選択は、エージェント上ではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。 +サンドボックスクライアントの選択、サンドボックスセッションの再利用、マニフェストオーバーライド、スナップショット選択は、エージェントではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。 ### `default_manifest` -`default_manifest` は、ランナーがこのエージェント用に新しいサンドボックスセッションを作成するときに使用するデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。エージェントが通常開始時に必要とするファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使用します。 +`default_manifest` は、Runner がこのエージェント用に新規サンドボックスセッションを作成するときに使用されるデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。エージェントが通常開始すべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使用します。 -これはデフォルトにすぎません。実行は `SandboxRunConfig(manifest=...)` で上書きでき、再利用または再開されたサンドボックスセッションは既存のワークスペース状態を保持します。 +これはデフォルトにすぎません。実行は `SandboxRunConfig(manifest=...)` でこれをオーバーライドできます。また、再利用または再開されたサンドボックスセッションは、既存のワークスペース状態を保持します。 ### `instructions` と `base_instructions` -異なるプロンプトをまたいで維持すべき短いルールには `instructions` を使用します。`SandboxAgent` では、これらの instructions は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保持しながら、独自の役割、ワークフロー、成功基準を追加できます。 +異なるプロンプトでも維持すべき短いルールには `instructions` を使用します。`SandboxAgent` では、これらの instructions は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保持しつつ、独自の役割、ワークフロー、成功基準を追加できます。 -SDK のサンドボックスベースプロンプトを置き換えたい場合にのみ、`base_instructions` を使用します。ほとんどのエージェントでは設定すべきではありません。 +SDK サンドボックスベースプロンプトを置き換えたい場合にのみ、`base_instructions` を使用してください。ほとんどのエージェントでは設定すべきではありません。
-| 入れる場所 | 用途 | 例 | +| 配置先... | 用途 | 例 | | --- | --- | --- | -| `instructions` | エージェントの安定した役割、ワークフロールール、成功基準。 | "オンボーディング文書を確認してからハンドオフしてください。"、"最終ファイルを `output/` に書き込んでください。" | +| `instructions` | エージェントの安定した役割、ワークフロールール、成功基準。 | 「オンボーディングドキュメントを調査してから、ハンドオフします。」、「最終ファイルを `output/` に書き込みます。」 | | `base_instructions` | SDK サンドボックスベースプロンプトの完全な置き換え。 | カスタムの低レベルサンドボックスラッパープロンプト。 | -| ユーザープロンプト | この実行の一回限りのリクエスト。 | "このワークスペースを要約してください。" | -| マニフェスト内のワークスペースファイル | より長いタスク仕様、リポジトリローカルの指示、または範囲を限定した参考資料。 | `repo/task.md`、ドキュメントバンドル、サンプルパケット。 | +| ユーザープロンプト | この実行の 1 回限りのリクエスト。 | 「このワークスペースを要約してください。」 | +| マニフェスト内のワークスペースファイル | より長いタスク仕様、リポジトリローカルの指示、または範囲が限定された参照資料。 | `repo/task.md`、ドキュメントバンドル、サンプルパケット。 |
-`instructions` の良い用途には次のものがあります。 +`instructions` の適切な用途には、次のようなものがあります。 -- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) は、PTY 状態が重要な場合にエージェントを 1 つの対話型プロセス内に保ちます。 +- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) は、PTY 状態が重要な場合に、エージェントを 1 つの対話型プロセス内に留めます。 - [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) は、サンドボックスレビュアーが検査後にユーザーへ直接回答することを禁止します。 - [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) は、最終的に記入済みのファイルが実際に `output/` に配置されることを要求します。 - [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) は、正確な検証コマンドを固定し、ワークスペースルート相対のパッチパスを明確にします。 -ユーザーの一回限りのタスクを `instructions` にコピーすること、マニフェストに属する長い参考資料を埋め込むこと、組み込み機能が既に注入するツールドキュメントを言い直すこと、実行時にモデルが必要としないローカルインストールメモを混ぜることは避けてください。 +ユーザーの 1 回限りのタスクを `instructions` にコピーすること、マニフェストに置くべき長い参照資料を埋め込むこと、組み込み機能が既に注入するツールドキュメントを繰り返すこと、または実行時にモデルが必要としないローカルインストールメモを混ぜることは避けてください。 -`instructions` を省略しても、SDK はデフォルトのサンドボックスプロンプトを含めます。これは低レベルラッパーには十分ですが、ほとんどのユーザー向けエージェントでは明示的な `instructions` を提供するべきです。 +`instructions` を省略しても、SDK はデフォルトのサンドボックスプロンプトを含めます。低レベルのラッパーにはそれで十分ですが、ほとんどのユーザー向けエージェントでは、明示的な `instructions` を提供すべきです。 ### `capabilities` -機能は、サンドボックスネイティブの動作を `SandboxAgent` に付与します。実行開始前にワークスペースを形成し、サンドボックス固有の instructions を追加し、稼働中のサンドボックスセッションにバインドするツールを公開し、そのエージェントのモデル動作や入力処理を調整できます。 +機能は、サンドボックスネイティブな挙動を `SandboxAgent` に付与します。実行開始前にワークスペースを形作り、サンドボックス固有の指示を追加し、ライブサンドボックスセッションにバインドされるツールを公開し、そのエージェントのモデル挙動や入力処理を調整できます。 組み込み機能には次のものがあります。
-| 機能 | 追加する場合 | 注記 | +| 機能 | 追加する場面 | 注意 | | --- | --- | --- | -| `Shell` | エージェントにシェルアクセスが必要な場合。 | `exec_command` を追加し、サンドボックスクライアントが PTY 対話をサポートする場合は `write_stdin` も追加します。 | -| `Filesystem` | エージェントがファイルを編集したりローカル画像を検査したりする必要がある場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 | -| `Skills` | サンドボックス内でスキル検出とマテリアライズを行いたい場合。 | `.agents` や `.agents/skills` を手動でマウントするよりもこちらを推奨します。`Skills` がスキルをインデックス化し、サンドボックス内にマテリアライズします。 | +| `Shell` | エージェントがシェルアクセスを必要とする場合。 | `exec_command` を追加し、サンドボックスクライアントが PTY インタラクションをサポートする場合は `write_stdin` も追加します。 | +| `Filesystem` | エージェントがファイルを編集する、またはローカル画像を検査する必要がある場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 | +| `Skills` | サンドボックス内でスキル検出とマテリアライズを行いたい場合。 | `.agents` または `.agents/skills` を手動でマウントするよりもこちらを優先してください。`Skills` はスキルのインデックス化とサンドボックスへのマテリアライズを行います。 | | `Memory` | 後続の実行でメモリ成果物を読み取る、または生成する必要がある場合。 | `Shell` が必要です。ライブ更新には `Filesystem` も必要です。 | | `Compaction` | 長時間実行されるフローで、コンパクション項目の後にコンテキストのトリミングが必要な場合。 | モデルサンプリングと入力処理を調整します。 |
-デフォルトでは、`SandboxAgent.capabilities` は `Filesystem()`、`Shell()`、`Compaction()` を含む `Capabilities.default()` を使用します。`capabilities=[...]` を渡すと、そのリストがデフォルトを置き換えるため、引き続き必要なデフォルト機能を含めてください。 +デフォルトでは、`SandboxAgent.capabilities` は `Capabilities.default()` を使用します。これには `Filesystem()`、`Shell()`、`Compaction()` が含まれます。`capabilities=[...]` を渡すと、そのリストがデフォルトを置き換えるため、引き続き必要なデフォルト機能を含めてください。 -スキルでは、どのようにマテリアライズしたいかに基づいてソースを選択します。 +スキルについては、どのようにマテリアライズしたいかに基づいてソースを選択してください。 -- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、大きめのローカルスキルディレクトリに適したデフォルトです。モデルが先にインデックスを検出し、必要なものだけを読み込めるためです。 -- `LocalDirLazySkillSource(source=LocalDir(src=...))` は、SDK プロセスが実行されているファイルシステムから読み取ります。サンドボックスイメージやワークスペース内にしか存在しないパスではなく、元のホスト側スキルディレクトリを渡してください。 +- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、大きめのローカルスキルディレクトリに適したデフォルトです。モデルがまずインデックスを発見し、必要なものだけを読み込めるためです。 +- `LocalDirLazySkillSource(source=LocalDir(src=...))` は、SDK プロセスが実行されているファイルシステムから読み取ります。サンドボックスイメージまたはワークスペース内にのみ存在するパスではなく、元のホスト側スキルディレクトリを渡してください。 - `Skills(from_=LocalDir(src=...))` は、事前にステージングしたい小さなローカルバンドルに適しています。 -- `Skills(from_=GitRepo(repo=..., ref=...))` は、スキル自体をリポジトリから取得するべき場合に適しています。 +- `Skills(from_=GitRepo(repo=..., ref=...))` は、スキル自体をリポジトリから取得すべき場合に適しています。 -`LocalDir.src` は SDK ホスト上のソースパスです。`skills_path` は、`load_skill` が呼ばれたときにスキルがステージングされる、サンドボックスワークスペース内の相対的な宛先パスです。 +`LocalDir.src` は SDK ホスト上のソースパスです。`skills_path` は、`load_skill` が呼び出されたときにスキルがステージングされる、サンドボックスワークスペース内の相対宛先パスです。 -スキルが既に `.agents/skills//SKILL.md` のような場所のディスク上にある場合は、そのソースルートを `LocalDir(...)` に指定し、それでも `Skills(...)` を使って公開してください。既存のワークスペース契約が別のサンドボックス内レイアウトに依存していない限り、デフォルトの `skills_path=".agents"` を維持してください。 +スキルが既に `.agents/skills//SKILL.md` のような場所にディスク上で存在する場合は、そのソースルートを `LocalDir(...)` に指定し、それでも `Skills(...)` を使用して公開してください。別のサンドボックス内レイアウトに依存する既存のワークスペース契約がない限り、デフォルトの `skills_path=".agents"` を維持してください。 -適合する場合は、組み込み機能を優先してください。組み込みではカバーされないサンドボックス固有のツールや指示サーフェスが必要な場合にのみ、カスタム機能を作成してください。 +適合する場合は、組み込み機能を優先してください。組み込みでカバーされないサンドボックス固有のツールや指示面が必要な場合にのみ、カスタム機能を作成してください。 ## 概念 -### Manifest +### マニフェスト -[`Manifest`][agents.sandbox.manifest.Manifest] は、新しいサンドボックスセッションのワークスペースを記述します。ワークスペース `root` の設定、ファイルとディレクトリの宣言、ローカルファイルのコピー、Git リポジトリのクローン、リモートストレージマウントの接続、環境変数の設定、ユーザーやグループの定義、ワークスペース外の特定の絶対パスへのアクセス許可を行えます。 +[`Manifest`][agents.sandbox.manifest.Manifest] は、新規サンドボックスセッションのワークスペースを記述します。ワークスペースの `root` を設定し、ファイルとディレクトリを宣言し、ローカルファイルをコピーし、Git リポジトリをクローンし、リモートストレージマウントを接続し、環境変数を設定し、ユーザーやグループを定義し、ワークスペース外の特定の絶対パスへのアクセスを許可できます。 -マニフェストエントリのパスはワークスペース相対です。絶対パスにしたり、`..` でワークスペース外へ抜けたりすることはできません。これにより、ワークスペース契約はローカル、Docker、ホスト型クライアントをまたいで移植可能になります。 +マニフェストエントリのパスはワークスペース相対です。絶対パスにすることや、`..` でワークスペース外へ抜けることはできません。これにより、ワークスペース契約はローカル、Docker、ホスト型クライアント間で移植可能になります。 -作業開始前にエージェントが必要とする素材には、マニフェストエントリを使用します。 +作業開始前にエージェントが必要とする資料には、マニフェストエントリを使用します。
| マニフェストエントリ | 用途 | | --- | --- | -| `File`、`Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 | -| `LocalFile`、`LocalDir` | サンドボックス内にマテリアライズすべきホストファイルまたはディレクトリ。 | +| `File`, `Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 | +| `LocalFile`, `LocalDir` | サンドボックスにマテリアライズすべきホストファイルまたはディレクトリ。 | | `GitRepo` | ワークスペースに取得すべきリポジトリ。 | -| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` などのマウント | サンドボックス内に表示すべき外部ストレージ。 | +| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` などのマウント | サンドボックス内に表示すべき外部ストレージ。 |
-`Dir` は、合成子要素から、または出力場所として、サンドボックスワークスペース内にディレクトリを作成します。ホストファイルシステムから読み取るわけではありません。既存のホストディレクトリをサンドボックスワークスペースにコピーする必要がある場合は、`LocalDir` を使用します。 +`Dir` は、合成子要素から、または出力場所として、サンドボックスワークスペース内にディレクトリを作成します。ホストファイルシステムから読み取るわけではありません。既存のホストディレクトリをサンドボックスワークスペースにコピーすべき場合は、`LocalDir` を使用してください。 -`LocalFile.src` と `LocalDir.src` は、デフォルトでは SDK プロセスの作業ディレクトリを基準に解決されます。ソースは、`extra_path_grants` でカバーされていない限り、そのベースディレクトリ配下に留まる必要があります。これにより、ローカルソースのマテリアライズは、サンドボックスマニフェストの他の部分と同じホストパス信頼境界内に保たれます。 +`LocalFile.src` と `LocalDir.src` は、デフォルトでは SDK プロセスの作業ディレクトリを基準に解決されます。ソースは、`extra_path_grants` でカバーされていない限り、そのベースディレクトリの下に留まる必要があります。これにより、ローカルソースのマテリアライズは、サンドボックスマニフェストの他の部分と同じホストパスの信頼境界内に保たれます。 マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどのように接続するかを記述します。マウントオプションとプロバイダーサポートについては、[サンドボックスクライアント](clients.md#mounts-and-remote-storage) を参照してください。 -良いマニフェスト設計とは通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` のようなワークスペースファイルに置き、instructions 内では `repo/task.md` や `output/report.md` のような相対ワークスペースパスを使うことです。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルートに対する相対であることに注意してください。 +適切なマニフェスト設計では通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` などのワークスペースファイルに置き、`repo/task.md` や `output/report.md` などの相対ワークスペースパスを指示で使用します。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなくサンドボックスワークスペースルートからの相対であることを忘れないでください。 -エージェントがワークスペース外の具体的な絶対パスを必要とする場合、またはマニフェストが SDK プロセスの作業ディレクトリ外の信頼済みローカルソースをコピーする必要がある場合にのみ、`extra_path_grants` を使用します。例として、一時的なツール出力用の `/tmp`、読み取り専用ランタイム用の `/opt/toolchain`、サンドボックスにマテリアライズすべき生成済みスキルディレクトリなどがあります。グラントは、ローカルソースのマテリアライズ、SDK ファイル API、およびバックエンドがファイルシステムポリシーを強制できる場合のシェル実行に適用されます。 +エージェントがワークスペース外の具体的な絶対パスを必要とする場合、または SDK プロセスの作業ディレクトリ外にある信頼済みローカルソースをマニフェストがコピーする必要がある場合にのみ、`extra_path_grants` を使用してください。例として、一時的なツール出力用の `/tmp`、読み取り専用ランタイム用の `/opt/toolchain`、サンドボックスにマテリアライズすべき生成済みスキルディレクトリなどがあります。付与は、ローカルソースのマテリアライズ、SDK ファイル API、バックエンドがファイルシステムポリシーを適用できる場合のシェル実行に適用されます。 ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -261,15 +261,15 @@ manifest = Manifest( ) ``` -`extra_path_grants` を含むマニフェストは、信頼済み設定として扱ってください。アプリケーションがそれらのホストパスを既に承認していない限り、モデル出力やその他の信頼できないペイロードからグラントを読み込まないでください。 +`extra_path_grants` を含むマニフェストは、信頼済み設定として扱ってください。アプリケーションがそれらのホストパスを既に承認していない限り、モデル出力やその他の信頼できないペイロードから付与を読み込まないでください。 -スナップショットと `persist_workspace()` は引き続きワークスペースルートのみを含みます。追加で許可されたパスはランタイムアクセスであり、永続的なワークスペース状態ではありません。 +スナップショットと `persist_workspace()` は、引き続きワークスペースルートのみを含みます。追加で許可されたパスはランタイムアクセスであり、永続的なワークスペース状態ではありません。 ### 権限 `Permissions` は、マニフェストエントリのファイルシステム権限を制御します。これはサンドボックスがマテリアライズするファイルに関するものであり、モデル権限、承認ポリシー、API 認証情報に関するものではありません。 -デフォルトでは、マニフェストエントリは所有者が読み取り/書き込み/実行可能で、グループとその他は読み取り/実行可能です。ステージングされたファイルをプライベート、読み取り専用、または実行可能にする必要がある場合は、これを上書きします。 +デフォルトでは、マニフェストエントリは所有者が読み取り/書き込み/実行可能で、グループとその他のユーザーが読み取り/実行可能です。ステージングされたファイルをプライベート、読み取り専用、または実行可能にすべき場合は、これをオーバーライドしてください。 ```python from agents.sandbox import FileMode, Permissions @@ -285,9 +285,9 @@ private_notes = File( ) ``` -`Permissions` は、所有者、グループ、その他のビット、およびエントリがディレクトリかどうかを別々に保存します。直接構築することも、`Permissions.from_str(...)` でモード文字列から解析することも、`Permissions.from_mode(...)` で OS モードから導出することもできます。 +`Permissions` は、所有者、グループ、その他のビットを個別に保持し、さらにエントリがディレクトリかどうかも保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列からパースすることも、`Permissions.from_mode(...)` で OS モードから導出することもできます。 -ユーザーは、作業を実行できるサンドボックス ID です。その ID をサンドボックス内に存在させたい場合は、マニフェストに `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行する必要がある場合は、`SandboxAgent.run_as` を設定します。`run_as` がマニフェストにまだ存在しないユーザーを指している場合、ランナーが有効なマニフェストにそのユーザーを追加します。 +ユーザーは、作業を実行できるサンドボックス ID です。その ID をサンドボックスに存在させたい場合は、マニフェストに `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行すべき場合は `SandboxAgent.run_as` を設定してください。`run_as` がマニフェスト内にまだ存在しないユーザーを指している場合、Runner は有効なマニフェストにそのユーザーを追加します。 ```python from agents import Runner @@ -339,11 +339,11 @@ result = await Runner.run( ) ``` -ファイルレベルの共有ルールも必要な場合は、ユーザーをマニフェストグループおよびエントリの `group` メタデータと組み合わせます。`run_as` ユーザーは、誰がサンドボックスネイティブアクションを実行するかを制御します。`Permissions` は、サンドボックスがワークスペースをマテリアライズした後に、そのユーザーがどのファイルを読み取り、書き込み、または実行できるかを制御します。 +ファイルレベルの共有ルールも必要な場合は、ユーザーとマニフェストグループ、エントリの `group` メタデータを組み合わせてください。`run_as` ユーザーは誰がサンドボックスネイティブなアクションを実行するかを制御し、`Permissions` はサンドボックスがワークスペースをマテリアライズした後に、そのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。 -### SnapshotSpec +### スナップショット仕様 -`SnapshotSpec` は、新しいサンドボックスセッションが保存済みワークスペース内容をどこから復元し、どこへ永続化し戻すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。 +`SnapshotSpec` は、新規サンドボックスセッションで保存済みワークスペース内容をどこから復元し、どこへ永続化して戻すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。 ローカルの永続スナップショットには `LocalSnapshotSpec` を使用し、アプリがリモートスナップショットクライアントを提供する場合は `RemoteSnapshotSpec` を使用します。ローカルスナップショットのセットアップが利用できない場合はフォールバックとして no-op スナップショットが使用され、高度な呼び出し元はワークスペーススナップショットの永続化を望まない場合に明示的に使用できます。 @@ -362,13 +362,13 @@ run_config = RunConfig( ) ``` -ランナーが新しいサンドボックスセッションを作成すると、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時、スナップショットが復元可能であれば、サンドボックスは実行を続ける前に保存済みワークスペース内容を復元します。クリーンアップ時、ランナー所有のサンドボックスセッションはワークスペースをアーカイブし、スナップショットを通じて永続化し戻します。 +Runner が新規サンドボックスセッションを作成すると、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時に、スナップショットが復元可能であれば、実行が継続する前にサンドボックスは保存済みワークスペース内容を復元します。クリーンアップ時には、Runner 所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショットを通じて永続化して戻します。 -`snapshot` を省略した場合、ランタイムは可能であればデフォルトのローカルスナップショット場所を使用しようとします。それをセットアップできない場合は、no-op スナップショットにフォールバックします。マウントされたパスと一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。 +`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット場所を使用しようとします。それをセットアップできない場合は、no-op スナップショットにフォールバックします。マウントされたパスと一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。 -### サンドボックスライフサイクル +### サンドボックスのライフサイクル -ライフサイクルモードには **SDK 所有** と **開発者所有** の 2 つがあります。 +ライフサイクルモードは 2 つあります。**SDK 所有** と **開発者所有** です。
@@ -396,7 +396,7 @@ sequenceDiagram
-サンドボックスが 1 回の実行だけ存続すればよい場合は、SDK 所有ライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、クライアント `options` を渡します。ランナーはサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット対応のワークスペース状態を永続化し、サンドボックスをシャットダウンし、クライアントにランナー所有リソースをクリーンアップさせます。 +サンドボックスが 1 回の実行の間だけ存続すればよい場合は、SDK 所有のライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、クライアント `options` を渡します。Runner はサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット backed のワークスペース状態を永続化し、サンドボックスをシャットダウンし、クライアントに Runner 所有リソースをクリーンアップさせます。 ```python result = await Runner.run( @@ -408,7 +408,7 @@ result = await Runner.run( ) ``` -サンドボックスを事前に作成したい場合、稼働中の 1 つのサンドボックスを複数の実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に決めたい場合は、開発者所有ライフサイクルを使用します。`session=...` を渡すと、ランナーはその稼働中サンドボックスを使用しますが、ユーザーの代わりに閉じることはありません。 +サンドボックスを先に作成したい場合、1 つのライブサンドボックスを複数の実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に決めたい場合は、開発者所有のライフサイクルを使用します。`session=...` を渡すと、Runner はそのライブサンドボックスを使用しますが、代わりに閉じることはありません。 ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -419,7 +419,7 @@ async with sandbox: await Runner.run(agent, "Write the final report.", run_config=run_config) ``` -通常の形はコンテキストマネージャーです。入るときにサンドボックスを開始し、抜けるときにセッションクリーンアップライフサイクルを実行します。アプリがコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出します。 +通常はコンテキストマネージャーの形を使用します。エントリ時にサンドボックスを開始し、終了時にセッションのクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使用できない場合は、ライフサイクルメソッドを直接呼び出してください。 ```python sandbox = await client.create( @@ -440,64 +440,64 @@ finally: await sandbox.aclose() ``` -`stop()` はスナップショット対応のワークスペース内容のみを永続化します。サンドボックスを破棄するわけではありません。`aclose()` は完全なセッションクリーンアップパスです。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。 +`stop()` はスナップショット backed のワークスペース内容だけを永続化し、サンドボックスを破棄しません。`aclose()` は完全なセッションクリーンアップパスです。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。 -## `SandboxRunConfig` オプション +## `SandboxRunConfig` のオプション -[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションがどこから来るか、および新しいセッションをどのように初期化するべきかを決定する実行ごとのオプションを保持します。 +[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションがどこから来るか、および新規セッションをどのように初期化すべきかを決定する、実行ごとのオプションを保持します。 -### サンドボックスソース +### サンドボックスの取得元 -これらのオプションは、ランナーがサンドボックスセッションを再利用、再開、または作成するべきかを決定します。 +これらのオプションは、Runner がサンドボックスセッションを再利用、再開、または作成すべきかを決定します。
-| オプション | 使用する場合 | 注記 | +| オプション | 使用する場面 | 注意 | | --- | --- | --- | -| `client` | ランナーにサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | 稼働中のサンドボックス `session` を提供しない限り必須です。 | -| `session` | 稼働中のサンドボックスセッションを自分で既に作成している場合。 | 呼び出し元がライフサイクルを所有します。ランナーはその稼働中のサンドボックスセッションを再利用します。 | -| `session_state` | シリアライズ済みサンドボックスセッション状態はあるが、稼働中のサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。ランナーはその明示的な状態から、所有セッションとして再開します。 | +| `client` | Runner にサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | ライブサンドボックス `session` を提供しない限り必須です。 | +| `session` | 既にライブサンドボックスセッションを自分で作成している場合。 | 呼び出し元がライフサイクルを所有します。Runner はそのライブサンドボックスセッションを再利用します。 | +| `session_state` | シリアライズ済みのサンドボックスセッション状態はあるが、ライブサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。Runner はその明示的な状態から所有セッションとして再開します。 |
-実際には、ランナーは次の順序でサンドボックスセッションを解決します。 +実際には、Runner は次の順序でサンドボックスセッションを解決します。 -1. `run_config.sandbox.session` を注入した場合、その稼働中サンドボックスセッションが直接再利用されます。 -2. それ以外で、実行が `RunState` から再開されている場合、保存されたサンドボックスセッション状態が再開されます。 -3. それ以外で、`run_config.sandbox.session_state` を渡した場合、ランナーはその明示的にシリアライズされたサンドボックスセッション状態から再開します。 -4. それ以外の場合、ランナーは新しいサンドボックスセッションを作成します。その新しいセッションでは、提供されている場合は `run_config.sandbox.manifest` を使用し、そうでなければ `agent.default_manifest` を使用します。 +1. `run_config.sandbox.session` を注入した場合、そのライブサンドボックスセッションが直接再利用されます。 +2. それ以外で、実行が `RunState` から再開される場合、保存されているサンドボックスセッション状態が再開されます。 +3. それ以外で、`run_config.sandbox.session_state` を渡した場合、Runner はその明示的なシリアライズ済みサンドボックスセッション状態から再開します。 +4. それ以外の場合、Runner は新規サンドボックスセッションを作成します。その新規セッションでは、提供されている場合は `run_config.sandbox.manifest` を使用し、そうでない場合は `agent.default_manifest` を使用します。 -### 新規セッション入力 +### 新規セッションの入力 -これらのオプションは、ランナーが新しいサンドボックスセッションを作成する場合にのみ重要です。 +これらのオプションは、Runner が新規サンドボックスセッションを作成する場合にのみ意味を持ちます。
-| オプション | 使用する場合 | 注記 | +| オプション | 使用する場面 | 注意 | | --- | --- | --- | -| `manifest` | 一回限りの新規セッションワークスペース上書きを行いたい場合。 | 省略時は `agent.default_manifest` にフォールバックします。 | -| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化するべき場合。 | 再開に似たフローやリモートスナップショットクライアントに有用です。 | +| `manifest` | 1 回限りの新規セッションワークスペースオーバーライドが必要な場合。 | 省略時は `agent.default_manifest` にフォールバックします。 | +| `snapshot` | 新規サンドボックスセッションをスナップショットから初期化すべき場合。 | 再開に似たフローやリモートスナップショットクライアントに有用です。 | | `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、Modal アプリ名、E2B テンプレート、タイムアウト、および同様のクライアント固有設定で一般的です。 |
### マテリアライズ制御 -`concurrency_limits` は、サンドボックスのマテリアライズ作業をどれだけ並列で実行できるかを制御します。大きなマニフェストやローカルディレクトリコピーでリソース制御をより厳しくする必要がある場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用します。どちらかの値を `None` に設定すると、その特定の制限を無効にできます。 +`concurrency_limits` は、サンドボックスのマテリアライズ作業をどの程度並列に実行できるかを制御します。大きなマニフェストやローカルディレクトリコピーでより厳密なリソース制御が必要な場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用してください。いずれかの値を `None` に設定すると、その特定の制限を無効にできます。 -`archive_limits` は、アーカイブ展開に関する SDK 側のリソースチェックを制御します。SDK のデフォルトしきい値を有効にするには `archive_limits=SandboxArchiveLimits()` を設定し、アーカイブにより厳しいリソース制御が必要な場合は `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` のような明示的な値を渡します。SDK アーカイブリソース制限なしのデフォルト動作を維持するには `archive_limits=None` のままにし、個別フィールドを `None` に設定するとその制限だけを無効にできます。 +`archive_limits` は、アーカイブ抽出に対する SDK 側のリソースチェックを制御します。SDK のデフォルトしきい値を有効にするには `archive_limits=SandboxArchiveLimits()` を設定します。アーカイブにより厳密なリソース制御が必要な場合は、`SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` などの明示的な値を渡してください。SDK アーカイブリソース制限なしのデフォルト動作を維持するには `archive_limits=None` のままにし、個別のフィールドだけを無効にするにはそのフィールドを `None` に設定します。 -覚えておく価値のある影響がいくつかあります。 +留意すべき点がいくつかあります。 -- 新規セッション: `manifest=` と `snapshot=` は、ランナーが新しいサンドボックスセッションを作成する場合にのみ適用されます。 -- 再開とスナップショット: `session_state=` は以前にシリアライズされたサンドボックス状態に再接続します。一方、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。 +- 新規セッション: `manifest=` と `snapshot=` は、Runner が新規サンドボックスセッションを作成する場合にのみ適用されます。 +- 再開とスナップショット: `session_state=` は以前にシリアライズされたサンドボックス状態に再接続します。一方、`snapshot=` は保存済みワークスペース内容から新規サンドボックスセッションを初期化します。 - クライアント固有オプション: `options=` はサンドボックスクライアントに依存します。Docker や多くのホスト型クライアントでは必須です。 -- 注入された稼働中セッション: 実行中のサンドボックス `session` を渡すと、機能駆動のマニフェスト更新で互換性のある非マウントエントリを追加できます。ただし、`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` を変更すること、既存エントリを削除すること、エントリタイプを置き換えること、マウントエントリを追加または変更することはできません。 -- ランナー API: `SandboxAgent` の実行は、引き続き通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使用します。 +- 注入されたライブセッション: 実行中のサンドボックス `session` を渡す場合、機能駆動のマニフェスト更新は互換性のある非マウントエントリを追加できます。`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` を変更すること、既存エントリを削除すること、エントリタイプを置き換えること、マウントエントリを追加または変更することはできません。 +- Runner API: `SandboxAgent` の実行は引き続き、通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使用します。 ## 完全な例: コーディングタスク -このコーディング形式の例は、デフォルトの出発点として適しています。 +このコーディングスタイルの例は、デフォルトの出発点として適しています。 ```python import asyncio @@ -576,17 +576,17 @@ if __name__ == "__main__": ) ``` -[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、Unix ローカル実行で決定論的に検証できるよう、小さなシェルベースのリポジトリを使用しています。実際のタスクリポジトリはもちろん、Python、JavaScript、その他何でも構いません。 +[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例は、Unix ローカル実行間で決定論的に検証できるように、小さなシェルベースのリポジトリを使用しています。実際のタスクリポジトリは、もちろん Python、JavaScript、またはその他何でもかまいません。 ## 一般的なパターン -上記の完全な例から始めてください。多くの場合、同じ `SandboxAgent` をそのまま保ち、サンドボックスクライアント、サンドボックスセッションソース、またはワークスペースソースだけを変更できます。 +上記の完全な例から始めてください。多くの場合、同じ `SandboxAgent` をそのまま維持し、サンドボックスクライアント、サンドボックスセッションの取得元、またはワークスペースの取得元だけを変更できます。 ### サンドボックスクライアントの切り替え -エージェント定義は同じままにし、実行設定だけを変更します。コンテナ分離やイメージの同等性が必要な場合は Docker を使用し、プロバイダー管理の実行が必要な場合はホスト型プロバイダーを使用します。例とプロバイダーオプションについては、[サンドボックスクライアント](clients.md) を参照してください。 +エージェント定義は同じままにし、実行設定だけを変更します。コンテナ隔離やイメージの一致性が必要な場合は Docker を使用し、プロバイダー管理の実行が必要な場合はホスト型プロバイダーを使用します。例とプロバイダーオプションについては、[サンドボックスクライアント](clients.md) を参照してください。 -### ワークスペースの上書き +### ワークスペースのオーバーライド エージェント定義は同じままにし、新規セッションのマニフェストだけを差し替えます。 @@ -608,11 +608,11 @@ run_config = RunConfig( ) ``` -同じエージェントの役割を、エージェントを再構築せずに異なるリポジトリ、パケット、タスクバンドルに対して実行したい場合に使用します。上記の検証済みコーディング例では、一回限りの上書きではなく `default_manifest` を使って同じパターンを示しています。 +同じエージェントの役割を、エージェントを再構築せずに異なるリポジトリ、パケット、またはタスクバンドルに対して実行すべき場合に使用します。上記の検証済みコーディング例では、1 回限りのオーバーライドではなく `default_manifest` で同じパターンを示しています。 ### サンドボックスセッションの注入 -明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、稼働中のサンドボックスセッションを注入します。 +明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、ライブサンドボックスセッションを注入します。 ```python from agents import Runner @@ -637,7 +637,7 @@ async with sandbox: ### セッション状態からの再開 -`RunState` の外で既にサンドボックス状態をシリアライズしている場合は、ランナーにその状態から再接続させます。 +`RunState` の外部で既にサンドボックス状態をシリアライズしている場合は、Runner にその状態から再接続させます。 ```python from agents.run import RunConfig @@ -654,11 +654,11 @@ run_config = RunConfig( ) ``` -サンドボックス状態が独自のストレージやジョブシステムにあり、`Runner` にそこから直接再開させたい場合に使用します。シリアライズ/デシリアライズのフローについては、[examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。 +サンドボックス状態が独自のストレージまたはジョブシステムに存在し、`Runner` にそこから直接再開させたい場合に使用します。シリアライズ/デシリアライズのフローについては、[examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。 ### スナップショットからの開始 -保存済みファイルと成果物から新しいサンドボックスを初期化します。 +保存済みファイルと成果物から新規サンドボックスを初期化します。 ```python from pathlib import Path @@ -675,11 +675,11 @@ run_config = RunConfig( ) ``` -新しい実行を `agent.default_manifest` だけではなく、保存済みワークスペース内容から開始するべき場合に使用します。ローカルスナップショットフローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を、リモートスナップショットクライアントについては [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。 +新規実行を `agent.default_manifest` だけではなく、保存済みワークスペース内容から開始すべき場合に使用します。ローカルスナップショットフローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を、リモートスナップショットクライアントについては [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。 ### Git からのスキル読み込み -ローカルスキルソースを、リポジトリを基盤とするものに差し替えます。 +ローカルスキルソースを、リポジトリ backed のものに差し替えます。 ```python from agents.sandbox.capabilities import Capabilities, Skills @@ -694,7 +694,7 @@ capabilities = Capabilities.default() + [ ### ツールとしての公開 -ツールエージェントは、独自のサンドボックス境界を持つことも、親実行から稼働中のサンドボックスを再利用することもできます。再利用は、高速な読み取り専用エクスプローラーエージェントに有用です。別のサンドボックスを作成、ハイドレート、またはスナップショットするコストを払わずに、親が使用している正確なワークスペースを検査できます。 +ツールエージェントは、独自のサンドボックス境界を持つことも、親実行のライブサンドボックスを再利用することもできます。再利用は、高速な読み取り専用の探索エージェントに有用です。別のサンドボックスの作成、ハイドレーション、スナップショット作成にコストをかけずに、親が使用している正確なワークスペースを検査できます。 ```python from agents import Runner @@ -776,9 +776,9 @@ async with sandbox: ) ``` -ここでは、親エージェントが `coordinator` として実行され、エクスプローラーツールエージェントが同じ稼働中サンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーに読み取り可能なので、エクスプローラーはそれらをすばやく検査できますが、書き込みビットはありません。`work/` ディレクトリはコーディネーターのユーザー/グループにのみ利用可能なため、親は最終成果物を書き込める一方で、エクスプローラーは読み取り専用のままです。 +ここでは、親エージェントは `coordinator` として実行され、探索ツールエージェントは同じライブサンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーが読み取り可能であるため、explorer はすばやく検査できますが、書き込みビットは持ちません。`work/` ディレクトリは coordinator のユーザー/グループだけが利用できるため、親は最終成果物を書き込めますが、explorer は読み取り専用のままです。 -ツールエージェントに実際の分離が必要な場合は、代わりに専用のサンドボックス `RunConfig` を与えます。 +ツールエージェントに実際の隔離が必要な場合は、代わりに独自のサンドボックス `RunConfig` を与えます。 ```python from docker import from_env as docker_from_env @@ -799,11 +799,11 @@ rollout_agent.as_tool( ) ``` -ツールエージェントが自由に変更するべき場合、信頼できないコマンドを実行するべき場合、または異なるバックエンド/イメージを使用するべき場合は、別のサンドボックスを使用します。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。 +ツールエージェントが自由に変更すべき場合、信頼できないコマンドを実行すべき場合、または異なるバックエンド/イメージを使用すべき場合は、別のサンドボックスを使用してください。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。 ### ローカルツールおよび MCP との組み合わせ -通常のツールを同じエージェントで使いながら、サンドボックスワークスペースを維持します。 +同じエージェントで通常のツールを使用しながら、サンドボックスワークスペースも維持します。 ```python from agents.sandbox import SandboxAgent @@ -822,9 +822,9 @@ agent = SandboxAgent( ## メモリ -将来のサンドボックスエージェント実行が以前の実行から学習するべき場合は、`Memory` 機能を使用します。メモリは SDK の会話用 `Session` メモリとは別物です。レッスンをサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読み取れるようにします。 +将来のサンドボックスエージェント実行が以前の実行から学習すべき場合は、`Memory` 機能を使用します。メモリは SDK の会話型 `Session` メモリとは別です。学びをサンドボックスワークスペース内のファイルに蒸留し、後続の実行がそれらのファイルを読み取れるようにします。 -セットアップ、読み取り/生成動作、マルチターン会話、レイアウト分離については、[エージェントメモリ](memory.md) を参照してください。 +セットアップ、読み取り/生成の挙動、マルチターン会話、レイアウト隔離については、[エージェントメモリ](memory.md) を参照してください。 ## 構成パターン @@ -832,32 +832,32 @@ agent = SandboxAgent( サンドボックスエージェントは、引き続き SDK の他の部分と組み合わせられます。 -- [ハンドオフ](../handoffs.md): ドキュメント量の多い作業を、非サンドボックスの取り込みエージェントからサンドボックスレビュアーへハンドオフします。 -- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しで `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自のサンドボックス境界を持つようにします。 +- [ハンドオフ](../handoffs.md): ドキュメントの多い作業を、非サンドボックスの受付エージェントからサンドボックスレビュアーにハンドオフします。 +- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しに `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自のサンドボックス境界を持つようにします。 - [MCP](../mcp.md) と通常の関数ツール: サンドボックス機能は、`mcp_servers` や通常の Python ツールと共存できます。 - [エージェントの実行](../running_agents.md): サンドボックス実行も通常の `Runner` API を使用します。 -特に一般的なパターンは次の 2 つです。 +特に一般的なパターンは 2 つあります。 -- ワークフローのうちワークスペース分離が必要な部分だけ、非サンドボックスエージェントからサンドボックスエージェントへハンドオフする -- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールが独自の分離ワークスペースを持つようにする +- ワークフローのうちワークスペース隔離が必要な部分だけを、非サンドボックスエージェントからサンドボックスエージェントにハンドオフする +- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールが独自の隔離ワークスペースを持つようにする ### ターンとサンドボックス実行 ハンドオフと agent-as-tool 呼び出しは分けて説明すると理解しやすくなります。 -ハンドオフでは、引き続き 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの取り込みエージェントがサンドボックスレビュアーへハンドオフすると、同じ実行内の次のモデル呼び出しはサンドボックスエージェント向けに準備され、そのサンドボックスエージェントが次のターンを受け持つものになります。言い換えると、ハンドオフは同じ実行の次のターンをどのエージェントが所有するかを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。 +ハンドオフでは、引き続き 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの受付エージェントがサンドボックスレビュアーにハンドオフすると、同じ実行内の次のモデル呼び出しはサンドボックスエージェント用に準備され、そのサンドボックスエージェントが次のターンを担当します。言い換えると、ハンドオフは同じ実行の次のターンをどのエージェントが所有するかを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。 -`Agent.as_tool(...)` では、関係が異なります。外側のオーケストレーターは、ツールを呼び出すことを決定するために 1 つの外側ターンを使い、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行は、独自のターンループ、`max_turns`、承認、そして通常は独自のサンドボックス `RunConfig` を持ちます。1 つのネストされたターンで完了する場合もあれば、複数かかる場合もあります。外側のオーケストレーターから見ると、その作業すべては 1 回のツール呼び出しの背後にあるため、ネストされたターンは外側の実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。 +`Agent.as_tool(...)` では、関係が異なります。外側のオーケストレーターは、ツールを呼び出すと決定するために外側の 1 ターンを使用し、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行は、独自のターンループ、`max_turns`、承認、そして通常は独自のサンドボックス `RunConfig` を持ちます。1 つのネストされたターンで完了する場合もあれば、複数かかる場合もあります。外側のオーケストレーターの視点では、その作業全体が 1 つのツール呼び出しの背後にあるため、ネストされたターンは外側の実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。 -承認の動作も同じ分離に従います。 +承認の挙動も同じ分担に従います。 -- ハンドオフでは、サンドボックスエージェントがその実行のアクティブなエージェントになるため、承認は同じトップレベル実行に留まります。 -- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認は引き続き外側の実行に表示されますが、保存されたネスト実行状態に由来し、外側の実行が再開されるとネストされたサンドボックス実行を再開します。 +- ハンドオフでは、サンドボックスエージェントがその実行内のアクティブエージェントになるため、承認は同じトップレベル実行に留まります +- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認も外側の実行に表示されますが、それらは保存されたネスト実行状態から来ており、外側の実行が再開されるとネストされたサンドボックス実行を再開します -## 関連資料 +## 関連情報 - [クイックスタート](quickstart.md): 1 つのサンドボックスエージェントを実行します。 - [サンドボックスクライアント](clients.md): ローカル、Docker、ホスト型、マウントのオプションを選択します。 -- [エージェントメモリ](memory.md): 以前のサンドボックス実行から得た知見を保持し再利用します。 -- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターン。 \ No newline at end of file +- [エージェントメモリ](memory.md): 以前のサンドボックス実行からの学びを保持し、再利用します。 +- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成のパターン。 \ No newline at end of file diff --git a/docs/ja/sandbox/memory.md b/docs/ja/sandbox/memory.md index d603eea411..9f949c72dc 100644 --- a/docs/ja/sandbox/memory.md +++ b/docs/ja/sandbox/memory.md @@ -4,23 +4,23 @@ search: --- # エージェントメモリ -メモリを使うと、今後の sandbox-agent の実行が過去の実行から学習できるようになります。これは、メッセージ履歴を保存する SDK の会話用 [`Session`](../sessions/index.md) メモリとは別のものです。メモリは、過去の実行から得られた学びを sandbox ワークスペース内のファイルに要約します。 +メモリにより、今後の sandbox エージェントの実行は過去の実行から学習できます。これは、メッセージ履歴を保存する SDK の会話用 [`Session`](../sessions/index.md) メモリとは別のものです。メモリは、過去の実行から得た学びを sandbox ワークスペース内のファイルに要約します。 !!! warning "ベータ機能" - Sandbox エージェントはベータ版です。一般提供までに API の詳細、デフォルト設定、サポートされる機能は変更される可能性があり、今後さらに高度な機能も追加される予定です。 + Sandbox エージェントはベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能が変更される可能性があり、時間とともにさらに高度な機能が追加されることも想定してください。 -メモリは、将来の実行における次の 3 種類のコストを削減できます。 +メモリは、今後の実行における 3 種類のコストを削減できます。 -1. エージェントコスト: エージェントがワークフローの完了に長い時間を要した場合、次回の実行では探索が少なくて済むはずです。これにより、トークン使用量と完了までの時間を削減できます。 -2. ユーザーコスト: ユーザーがエージェントを修正したり、好みを示したりした場合、今後の実行ではそのフィードバックを記憶できます。これにより、人手による介入を減らせます。 -3. コンテキストコスト: エージェントが以前にタスクを完了していて、ユーザーがそのタスクを引き継いで進めたい場合、ユーザーは以前のスレッドを探したり、すべてのコンテキストを再入力したりする必要がありません。これにより、タスクの説明を短くできます。 +1. エージェントのコスト: エージェントがワークフローの完了に長い時間を要した場合、次回の実行では探索が少なくて済むはずです。これにより、トークン使用量と完了までの時間を削減できます。 +2. ユーザーのコスト: ユーザーがエージェントを修正したり好みを表明したりした場合、今後の実行でそのフィードバックを記憶できます。これにより、人による介入を削減できます。 +3. コンテキストのコスト: エージェントが以前にタスクを完了していて、ユーザーがそのタスクを発展させたい場合、ユーザーは以前のスレッドを探したり、すべてのコンテキストを再入力したりする必要がないはずです。これにより、タスク説明を短くできます。 -バグを修正し、メモリを生成し、スナップショットを再開し、そのメモリを後続の verifier 実行で使用する 2 回実行の完全な例については、[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を参照してください。別々のメモリレイアウトを使ったマルチターン・マルチエージェントの例については、[examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py) を参照してください。 +バグを修正し、メモリを生成し、スナップショットを再開し、そのメモリを後続の検証実行で使用する、2 回の実行からなる完全なコード例については、[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を参照してください。独立したメモリレイアウトを持つマルチターン、マルチエージェントのコード例については、[examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py) を参照してください。 ## メモリの有効化 -sandbox エージェントの capability として `Memory()` を追加します。 +sandbox エージェントに機能として `Memory()` を追加します。 ```python from pathlib import Path @@ -42,28 +42,28 @@ with tempfile.TemporaryDirectory(prefix="sandbox-memory-example-") as snapshot_d ) ``` -読み取りが有効な場合、`Memory()` には `Shell()` が必要です。これにより、注入された要約だけでは不十分なときに、エージェントがメモリファイルを読み取り、検索できます。ライブメモリ更新が有効な場合（デフォルト）、`Filesystem()` も必要です。これにより、エージェントが古いメモリを見つけた場合や、ユーザーがメモリの更新を求めた場合に、`memories/MEMORY.md` を更新できます。 +読み取りが有効な場合、`Memory()` には `Shell()` が必要です。これにより、挿入されたサマリーだけでは不十分なときに、エージェントがメモリファイルを読み取り、検索できます。ライブメモリ更新が有効な場合（デフォルト）、`Filesystem()` も必要です。これにより、エージェントが古くなったメモリを発見した場合や、ユーザーがメモリの更新を依頼した場合に、`memories/MEMORY.md` を更新できます。 -デフォルトでは、メモリアーティファクトは sandbox ワークスペースの `memories/` 以下に保存されます。後続の実行でそれらを再利用するには、同じライブ sandbox セッションを維持するか、永続化されたセッション状態またはスナップショットから再開することで、設定された memories ディレクトリー全体を保持して再利用してください。新しい空の sandbox は空のメモリで開始します。 +デフォルトでは、メモリアーティファクトは sandbox ワークスペースの `memories/` 配下に保存されます。後の実行で再利用するには、同じライブ sandbox セッションを維持するか、永続化されたセッション状態またはスナップショットから再開することで、設定済みのメモリディレクトリ全体を保持して再利用してください。新しい空の sandbox は空のメモリで開始されます。 -`Memory()` は、メモリの読み取りと生成の両方を有効にします。メモリを読み取るが新しいメモリを生成すべきではないエージェントには `Memory(generate=None)` を使用します。たとえば、内部エージェント、subagent、checker、またはシグナルをあまり追加しない単発のツールエージェントです。実行で後のためにメモリを生成すべきだが、既存のメモリの影響は受けたくない場合は、`Memory(read=None)` を使用します。 +`Memory()` は、メモリの読み取りと生成の両方を有効にします。メモリを読み取るが新しいメモリは生成すべきでないエージェントには、`Memory(generate=None)` を使用します。たとえば、内部エージェント、サブエージェント、チェッカー、または実行から得られるシグナルが多くない 1 回限りのツールエージェントです。後で使うメモリを生成する必要はあるものの、ユーザーが既存メモリによる影響を望まない場合は、`Memory(read=None)` を使用します。 ## メモリの読み取り -メモリの読み取りでは段階的開示を使用します。実行開始時に、SDK は一般的に有用なヒント、ユーザーの好み、利用可能なメモリの小さな要約（`memory_summary.md`）をエージェントの開発者プロンプトに注入します。これにより、過去の作業が関連しそうかどうかをエージェントが判断するための十分なコンテキストが与えられます。 +メモリ読み取りでは段階的開示を使用します。実行の開始時に、SDK は一般的に役立つヒント、ユーザーの好み、利用可能なメモリの小さなサマリー（`memory_summary.md`）を、エージェントの developer プロンプトに挿入します。これにより、エージェントは過去の作業が関連しそうかどうかを判断するのに十分なコンテキストを得られます。 -過去の作業が関連していそうな場合、エージェントは現在のタスクのキーワードを使って、設定されたメモリインデックス（`memories_dir` 配下の `MEMORY.md`）を検索します。さらに詳しい情報が必要な場合にのみ、設定された `rollout_summaries/` ディレクトリー配下の対応する過去の rollout 要約を開きます。 +過去の作業が関連しそうな場合、エージェントは現在のタスクからキーワードを抽出して、設定されたメモリインデックス（`memories_dir` 配下の `MEMORY.md`）を検索します。より詳細が必要な場合にのみ、設定された `rollout_summaries/` ディレクトリ配下にある対応する過去のロールアウトサマリーを開きます。 -メモリは古くなることがあります。エージェントには、メモリはあくまで参考情報として扱い、現在の環境を信頼するよう指示されています。デフォルトでは、メモリ読み取りでは `live_update` が有効になっているため、エージェントが古いメモリを見つけた場合、同じ実行内で設定された `MEMORY.md` を更新できます。たとえば、その実行がレイテンシーに敏感な場合など、エージェントがメモリを読み取るだけで実行中に変更すべきでない場合は、ライブ更新を無効にしてください。 +メモリは古くなることがあります。エージェントには、メモリをガイダンスとしてのみ扱い、現在の環境を信頼するよう指示されています。デフォルトでは、メモリ読み取りでは `live_update` が有効です。そのため、エージェントが古くなったメモリを発見した場合、同じ実行内で設定済みの `MEMORY.md` を更新できます。実行中にメモリを読み取るが変更してほしくない場合、たとえばレイテンシに敏感な実行では、ライブ更新を無効にしてください。 ## メモリの生成 -実行が終了すると、sandbox ランタイムはその実行セグメントを会話ファイルに追記します。蓄積された会話ファイルは、sandbox セッションが閉じられるときに処理されます。 +実行が完了すると、sandbox ランタイムはその実行セグメントを会話ファイルに追記します。蓄積された会話ファイルは、sandbox セッションが閉じられるときに処理されます。 メモリ生成には 2 つのフェーズがあります。 -1. フェーズ 1: 会話抽出。メモリ生成モデルが蓄積された 1 つの会話ファイルを処理し、会話要約を生成します。system、developer、および reasoning の内容は省略されます。会話が長すぎる場合は、先頭と末尾を保持したまま、コンテキストウィンドウに収まるように切り詰められます。また、フェーズ 2 で統合できるよう、会話からの簡潔なメモである raw メモリ抽出も生成されます。 -2. フェーズ 2: レイアウト統合。統合エージェントが 1 つのメモリレイアウトの raw メモリを読み取り、さらに証拠が必要な場合は会話要約を開き、パターンを `MEMORY.md` と `memory_summary.md` に抽出します。 +1. フェーズ 1: 会話の抽出。メモリ生成モデルが、蓄積された 1 つの会話ファイルを処理し、会話サマリーを生成します。system、developer、reasoning のコンテンツは省略されます。会話が長すぎる場合は、先頭と末尾を保持したうえで、コンテキストウィンドウに収まるよう切り詰められます。また、未加工のメモリ抽出も生成します。これは、フェーズ 2 が統合できる会話からの簡潔なメモです。 +2. フェーズ 2: レイアウトの統合。統合エージェントは、1 つのメモリレイアウトに対応する未加工のメモリを読み取り、より多くの根拠が必要な場合は会話サマリーを開き、パターンを `MEMORY.md` と `memory_summary.md` に抽出します。 デフォルトのワークスペースレイアウトは次のとおりです。 @@ -83,7 +83,7 @@ workspace/ └── skills/ ``` -`MemoryGenerateConfig` を使ってメモリ生成を設定できます。 +`MemoryGenerateConfig` でメモリ生成を設定できます。 ```python from agents.sandbox import MemoryGenerateConfig @@ -97,13 +97,13 @@ memory = Memory( ) ``` -`extra_prompt` を使うと、GTM エージェント向けの顧客情報や企業情報のように、どのシグナルがユースケースで最も重要かをメモリ生成器に伝えられます。 +`extra_prompt` を使用して、GTM エージェント向けの顧客や会社の詳細など、ユースケースで最も重要なシグナルをメモリ生成器に伝えます。 -最近の raw メモリが `max_raw_memories_for_consolidation`（デフォルトは 256）を超える場合、フェーズ 2 は最新の会話のメモリだけを保持し、古いものを削除します。新しさは、その会話が最後に更新された時刻に基づきます。この忘却メカニズムにより、メモリは最新の環境を反映しやすくなります。 +最近の未加工メモリが `max_raw_memories_for_consolidation`（デフォルトは 256）を超える場合、フェーズ 2 は最新の会話のメモリだけを保持し、古いものを削除します。新しさは、会話が最後に更新された時刻に基づきます。この忘却メカニズムにより、メモリが最新の環境を反映しやすくなります。 ## マルチターン会話 -マルチターンの sandbox チャットでは、通常の SDK `Session` を同じライブ sandbox セッションと組み合わせて使用します。 +マルチターンの sandbox チャットでは、同じライブ sandbox セッションとともに通常の SDK `Session` を使用します。 ```python from agents import Runner, SQLiteSession @@ -132,20 +132,20 @@ async with sandbox: ) ``` -両方の実行は同じメモリ会話ファイルに追記されます。これは、同じ SDK 会話セッション（`session=conversation_session`）を渡すことで、同じ `session.session_id` を共有するためです。これは、ライブワークスペースを識別する sandbox（`sandbox`）とは異なり、メモリ会話 ID としては使用されません。フェーズ 1 は sandbox セッションが閉じられたときに蓄積された会話を参照するため、分離された 2 つのターンではなく、やり取り全体からメモリを抽出できます。 +どちらの実行も、同じ SDK 会話セッション（`session=conversation_session`）を渡すため、1 つのメモリ会話ファイルに追記され、したがって同じ `session.session_id` を共有します。これはライブワークスペースを識別する sandbox（`sandbox`）とは異なります。`sandbox` はメモリ会話 ID としては使用されません。sandbox セッションが閉じられると、フェーズ 1 は蓄積された会話を参照するため、2 つの孤立したターンではなく、やり取り全体からメモリを抽出できます。 -複数の `Runner.run(...)` 呼び出しを 1 つのメモリ会話にしたい場合は、それらの呼び出しにまたがって安定した識別子を渡してください。メモリが実行を会話に関連付けるときは、次の順序で解決されます。 +複数の `Runner.run(...)` 呼び出しを 1 つのメモリ会話にしたい場合は、それらの呼び出し全体で安定した識別子を渡してください。メモリが実行を会話に関連付けるときは、次の順序で解決します。 -1. `Runner.run(...)` に渡した `conversation_id` -2. `SQLiteSession` などの SDK `Session` を渡した場合の `session.session_id` -3. 上記のいずれも存在しない場合の `RunConfig.group_id` -4. 安定した識別子が存在しない場合の、実行ごとに生成される ID +1. `conversation_id`（`Runner.run(...)` に渡した場合） +2. `session.session_id`（`SQLiteSession` などの SDK `Session` を渡した場合） +3. `RunConfig.group_id`（上記のどちらも存在しない場合） +4. 生成された実行ごとの ID（安定した識別子が存在しない場合） -## 異なるエージェント向けのメモリ分離用レイアウト +## エージェントごとのメモリ分離における異なるレイアウトの利用 -メモリの分離は、エージェント名ではなく `MemoryLayoutConfig` に基づきます。同じレイアウトと同じメモリ会話 ID を持つエージェントは、1 つのメモリ会話と 1 つの統合メモリを共有します。異なるレイアウトを持つエージェントは、同じ sandbox ワークスペースを共有していても、別々の rollout ファイル、raw メモリ、`MEMORY.md`、および `memory_summary.md` を保持します。 +メモリの分離はエージェント名ではなく `MemoryLayoutConfig` に基づきます。同じレイアウトと同じメモリ会話 ID を持つエージェントは、1 つのメモリ会話と 1 つの統合済みメモリを共有します。異なるレイアウトを持つエージェントは、同じ sandbox ワークスペースを共有している場合でも、別々のロールアウトファイル、未加工メモリ、`MEMORY.md`、`memory_summary.md` を保持します。 -複数のエージェントが 1 つの sandbox を共有しているが、メモリを共有すべきでない場合は、別々のレイアウトを使用します。 +複数のエージェントが 1 つの sandbox を共有するものの、メモリは共有すべきでない場合は、別々のレイアウトを使用します。 ```python from agents import SQLiteSession diff --git a/docs/ja/sandbox_agents.md b/docs/ja/sandbox_agents.md index 1c23fa1b10..bc184c8361 100644 --- a/docs/ja/sandbox_agents.md +++ b/docs/ja/sandbox_agents.md @@ -6,17 +6,17 @@ search: !!! warning "ベータ機能" - Sandbox エージェントはベータ版です。API、デフォルト、およびサポートされる機能の詳細は一般提供前に変更される可能性があり、今後さらに高度な機能が追加される見込みです。 + サンドボックスエージェントはベータ版です。一般提供前に API の詳細、デフォルト値、サポートされる機能が変更される可能性があり、今後より高度な機能が追加されることが想定されます。 -現代のエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果を発揮します。Agents SDK の **Sandbox Agents** は、大規模なドキュメントセットの検索、ファイル編集、コマンド実行、成果物の生成、保存された Sandbox 状態からの作業再開が可能な永続的なワークスペースをモデルに提供します。 +最新のエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果を発揮します。Agents SDK の **サンドボックスエージェント** は、モデルに永続的なワークスペースを提供し、大規模なドキュメントセットの検索、ファイル編集、コマンド実行、成果物の生成、保存済みのサンドボックス状態からの作業再開を可能にします。 -SDK は、ファイルステージング、ファイルシステムツール、シェルアクセス、Sandbox ライフサイクル、スナップショット、プロバイダー固有の連携を自分でつなぎ合わせることなく、その実行基盤を提供します。通常の `Agent` と `Runner` のフローを維持したまま、ワークスペース用の `Manifest`、Sandbox ネイティブツール用の機能、作業の実行場所を指定する `SandboxRunConfig` を追加します。 +SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の連携を自分で組み合わせる必要なく、その実行ハーネスを提供します。通常の `Agent` と `Runner` のフローはそのままに、ワークスペース用の `Manifest`、サンドボックスネイティブツール用の機能、作業の実行場所を指定する `SandboxRunConfig` を追加します。 ## 前提条件 - Python 3.10 以上 -- OpenAI Agents SDK の基本的な知識 -- Sandbox クライアント。ローカル開発では、`UnixLocalSandboxClient` から始めてください。 +- OpenAI Agents SDK に関する基本的な理解 +- サンドボックスクライアント。ローカル開発では、`UnixLocalSandboxClient` から始めてください。 ## インストール @@ -26,15 +26,15 @@ SDK をまだインストールしていない場合: pip install openai-agents ``` -Docker ベースの Sandbox の場合: +Docker ベースのサンドボックスの場合: ```bash pip install "openai-agents[docker]" ``` -## ローカル Sandbox エージェントの作成 +## ローカルサンドボックスエージェントの作成 -この例では、ローカルリポジトリを `repo/` 配下にステージングし、ローカルスキルを遅延読み込みし、Runner が実行用の Unix ローカル Sandbox セッションを作成できるようにします。 +この例では、ローカルリポジトリを `repo/` 配下にステージングし、ローカルスキルを遅延ロードし、ランナーが実行用の Unix ローカルサンドボックスセッションを作成できるようにします。 ```python import asyncio @@ -94,24 +94,24 @@ if __name__ == "__main__": asyncio.run(main()) ``` -[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、小さなシェルベースのリポジトリを使用しているため、Unix ローカル実行間で決定論的に検証できます。 +[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例は小さなシェルベースのリポジトリを使用しているため、Unix ローカル実行間で決定論的に検証できます。 ## 主な選択肢 -基本的な実行が動作したら、多くの人が次に検討する選択肢は次のとおりです。 +基本的な実行が動作したら、次に多くの人が検討する選択肢は次のとおりです。 -- `default_manifest`: 新しい Sandbox セッション用のファイル、リポジトリ、ディレクトリ、マウント -- `instructions`: プロンプト全体に適用すべき短いワークフロールール -- `base_instructions`: SDK の Sandbox プロンプトを置き換えるための高度なエスケープハッチ -- `capabilities`: ファイルシステム編集/画像検査、シェル、スキル、メモリ、圧縮などの Sandbox ネイティブツール -- `run_as`: モデル向けツールの Sandbox ユーザー ID -- `SandboxRunConfig.client`: Sandbox バックエンド +- `default_manifest`: 新しいサンドボックスセッション用のファイル、リポジトリ、ディレクトリ、マウント +- `instructions`: 複数のプロンプトにわたって適用すべき短いワークフロールール +- `base_instructions`: SDK のサンドボックスプロンプトを置き換えるための高度なエスケープハッチ +- `capabilities`: ファイルシステム編集 / 画像検査、シェル、スキル、メモリ、コンパクションなどのサンドボックスネイティブツール +- `run_as`: モデル向けツールで使用するサンドボックスのユーザー ID +- `SandboxRunConfig.client`: サンドボックスバックエンド - `SandboxRunConfig.session`、`session_state`、または `snapshot`: 後続の実行が以前の作業に再接続する方法 ## 次のステップ - [概念](sandbox/guide.md): マニフェスト、機能、権限、スナップショット、実行設定、構成パターンを理解します。 -- [Sandbox クライアント](sandbox/clients.md): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。 -- [エージェントメモリ](sandbox/memory.md): 以前の Sandbox 実行から得た教訓を保持し、再利用します。 +- [サンドボックスクライアント](sandbox/clients.md): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。 +- [エージェントメモリ](sandbox/memory.md): 以前のサンドボックス実行から得た知見を保存し、再利用します。 -シェルアクセスが時々使うツールの 1 つにすぎない場合は、[ツールガイド](tools.md) のホスト型シェルから始めてください。ワークスペースの分離、Sandbox クライアントの選択、または Sandbox セッションの再開動作が設計の一部である場合は、Sandbox エージェントを使用してください。 \ No newline at end of file +シェルアクセスがたまに使うツールの 1 つにすぎない場合は、[ツールガイド](tools.md) のホスト型シェルから始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計に含まれる場合は、サンドボックスエージェントを選択してください。 \ No newline at end of file diff --git a/docs/ja/sessions/advanced_sqlite_session.md b/docs/ja/sessions/advanced_sqlite_session.md index d053754db1..2f5cb469ea 100644 --- a/docs/ja/sessions/advanced_sqlite_session.md +++ b/docs/ja/sessions/advanced_sqlite_session.md @@ -4,15 +4,15 @@ search: --- # 高度な SQLite セッション -`AdvancedSQLiteSession` は、基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなどの高度な会話管理機能を提供します。 +`AdvancedSQLiteSession` は基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなど、高度な会話管理機能を提供します。 ## 機能 -- **会話の分岐**: 任意のユーザーメッセージから代替の会話パスを作成 -- **使用状況トラッキング**: 各ターンごとの詳細なトークン使用状況分析（完全な JSON 内訳付き） -- **構造化クエリ**: ターン単位の会話、ツール使用統計などを取得 -- **ブランチ管理**: 独立したブランチ切り替えと管理 -- **メッセージ構造メタデータ**: メッセージタイプ、ツール使用状況、会話フローを追跡 +- **会話の分岐**: 任意のユーザーメッセージから別の会話パスを作成します +- **使用状況の追跡**: ターンごとの詳細なトークン使用状況分析を、完全な JSON 内訳付きで提供します +- **構造化クエリ**: ターン別の会話、ツール使用状況の統計などを取得します +- **ブランチ管理**: 独立したブランチ切り替えと管理を行います +- **メッセージ構造メタデータ**: メッセージタイプ、ツール使用、会話フローを追跡します ## クイックスタート @@ -84,16 +84,16 @@ session = AdvancedSQLiteSession( ### パラメーター -- `session_id` (str): 会話セッションの一意な識別子 -- `db_path` (str | Path): SQLite データベースファイルへのパス。デフォルトはメモリ内ストレージ用の `:memory:` -- `create_tables` (bool): 高度なテーブルを自動作成するかどうか。デフォルトは `False` -- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガー +- `session_id` (str): 会話セッションの一意の識別子 +- `db_path` (str | Path): SQLite データベースファイルへのパス。デフォルトはインメモリストレージ用の `:memory:` です +- `create_tables` (bool): 高度なテーブルを自動的に作成するかどうか。デフォルトは `False` です +- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガーです -## 使用状況トラッキング +## 使用状況の追跡 -AdvancedSQLiteSession は、会話ターンごとのトークン使用データを保存することで、詳細な使用状況分析を提供します。**これは各エージェント実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。** +AdvancedSQLiteSession は、会話ターンごとにトークン使用状況データを保存することで、詳細な使用状況分析を提供します。 **これは、各エージェント実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。** -### 使用データの保存 +### 使用状況データの保存 ```python # After each agent run, store the usage data @@ -107,7 +107,7 @@ await session.store_run_usage(result) # - Detailed JSON token information (if available) ``` -### 使用統計の取得 +### 使用状況統計の取得 ```python # Get session-level usage (all branches) @@ -137,7 +137,7 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2) ## 会話の分岐 -AdvancedSQLiteSession の主要機能の 1 つは、任意のユーザーメッセージから会話ブランチを作成できることです。これにより、代替の会話パスを探索できます。 +AdvancedSQLiteSession の主要機能の 1 つは、任意のユーザーメッセージから会話ブランチを作成し、別の会話パスを探索できることです。 ### ブランチの作成 @@ -245,17 +245,17 @@ for turn in matching_turns: ### メッセージ構造 -セッションは、以下を含むメッセージ構造を自動的に追跡します。 +セッションは、次を含むメッセージ構造を自動的に追跡します。 -- メッセージタイプ (user, assistant, tool_call など) -- ツール呼び出し用のツール名 +- メッセージタイプ（ユーザー、assistant、tool_call など） +- ツール呼び出しのツール名 - ターン番号とシーケンス番号 -- ブランチ関連付け +- ブランチとの関連付け - タイムスタンプ ## データベーススキーマ -AdvancedSQLiteSession は、基本的な SQLite スキーマを次の 2 つの追加テーブルで拡張します。 +AdvancedSQLiteSession は、基本的な SQLite スキーマを 2 つの追加テーブルで拡張します。 ### message_structure テーブル @@ -298,7 +298,7 @@ CREATE TABLE turn_usage ( ## 完全な例 -すべての機能を包括的に示すデモについては、[完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)をご確認ください。 +すべての機能を包括的に示す [完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py) を確認してください。 ## API リファレンス diff --git a/docs/ja/sessions/encrypted_session.md b/docs/ja/sessions/encrypted_session.md index c62054ebf0..b65b0d8008 100644 --- a/docs/ja/sessions/encrypted_session.md +++ b/docs/ja/sessions/encrypted_session.md @@ -4,18 +4,18 @@ search: --- # 暗号化セッション -`EncryptedSession` は、あらゆるセッション実装に対して透過的な暗号化を提供し、古い項目の自動有効期限切れによって会話データを保護します。 +`EncryptedSession` は、任意のセッション実装に透過的な暗号化を提供し、古いアイテムの自動期限切れによって会話データを保護します。 ## 機能 -- **透過的な暗号化**: あらゆるセッションを Fernet 暗号化でラップします -- **セッションごとのキー**: HKDF 鍵導出を使用して、セッションごとに一意の暗号化を行います -- **自動有効期限切れ**: TTL が期限切れになると、古い項目は自動的にスキップされます -- **そのまま置き換え可能**: 既存のあらゆるセッション実装で動作します +- **透過的な暗号化**: 任意のセッションを Fernet 暗号化でラップします +- **セッションごとのキー**: HKDF キー導出を使用して、セッションごとに一意の暗号化を行います +- **自動期限切れ**: TTL が期限切れになると、古いアイテムは取得時に黙ってスキップされます +- **ドロップイン置換**: 既存の任意のセッション実装で動作します ## インストール -暗号化セッションには `encrypt` 追加機能が必要です: +暗号化セッションには `encrypt` extra が必要です。 ```bash pip install openai-agents[encrypt] @@ -57,7 +57,7 @@ if __name__ == "__main__": ### 暗号化キー -暗号化キーには、Fernet キーまたは任意の文字列を使用できます: +暗号化キーには、Fernet キーまたは任意の文字列を指定できます。 ```python from agents.extensions.memory import EncryptedSession @@ -81,7 +81,7 @@ session = EncryptedSession( ### TTL (有効期間) -暗号化された項目を有効とする期間を設定します: +暗号化されたアイテムが有効であり続ける期間を設定します。 ```python # Items expire after 1 hour @@ -101,7 +101,7 @@ session = EncryptedSession( ) ``` -## 異なるセッションタイプでの使用 +## さまざまなセッションタイプでの使用 ### SQLite セッションでの使用 @@ -140,30 +140,30 @@ session = EncryptedSession( !!! warning "高度なセッション機能" - `AdvancedSQLiteSession` のような高度なセッション実装で `EncryptedSession` を使用する場合は、次の点に注意してください: + `EncryptedSession` を `AdvancedSQLiteSession` のような高度なセッション実装と使用する場合は、次の点に注意してください。 - - メッセージ内容は暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に機能しません - - コンテンツベースの検索は暗号化データに対して実行されるため、有効性が制限されます + - メッセージ内容が暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に動作しません + - コンテンツベースの検索は暗号化されたデータに対して実行されるため、有効性が制限されます -## 鍵導出 +## キー導出 -EncryptedSession は HKDF (HMAC-based Key Derivation Function) を使用して、セッションごとに一意の暗号化キーを導出します: +EncryptedSession は HKDF (HMAC-based Key Derivation Function) を使用して、セッションごとに一意の暗号化キーを導出します。 -- **マスターキー**: 提供した暗号化キー +- **マスターキー**: 提供された暗号化キー - **セッションソルト**: セッション ID -- **Info 文字列**: `"agents.session-store.hkdf.v1"` +- **情報文字列**: `"agents.session-store.hkdf.v1"` - **出力**: 32 バイトの Fernet キー -これにより、次が保証されます: -- 各セッションが一意の暗号化キーを持つこと -- マスターキーなしではキーを導出できないこと -- セッションデータを異なるセッション間で復号できないこと +これにより、次のことが保証されます。 +- 各セッションに一意の暗号化キーがあります +- マスターキーがなければキーを導出できません +- セッションデータを異なるセッション間で復号できません -## 自動有効期限切れ +## 自動期限切れ -項目が TTL を超えると、取得時に自動的にスキップされます: +アイテムが TTL を超えると、取得時に自動的にスキップされます。 ```python # Items older than TTL are silently ignored diff --git a/docs/ja/sessions/index.md b/docs/ja/sessions/index.md index e5313b934c..7240850d21 100644 --- a/docs/ja/sessions/index.md +++ b/docs/ja/sessions/index.md @@ -6,9 +6,9 @@ search: Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。 -セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずにエージェントがコンテキストを維持できるようにします。これは、チャットアプリケーションや、エージェントに以前のやり取りを記憶させたいマルチターン会話を構築する場合に特に有用です。 +セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えておいてほしいチャットアプリケーションや複数ターンの会話を構築する場合に特に便利です。 -SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI サーバー管理の継続を使いたい場合は、セッションを重ねるのではなく、それらの仕組みのいずれかを選択してください。 +SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは、同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI のサーバー管理による継続を使用したい場合は、セッションを重ねて使うのではなく、それらの仕組みのいずれかを選択してください。 ## クイックスタート @@ -49,9 +49,9 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 同じセッションでの中断された実行の再開 +## 同じセッションによる中断された実行の再開 -実行が承認待ちで一時停止した場合は、再開後のターンが同じ保存済み会話履歴を引き継ぐように、同じセッションインスタンス（または同じバッキングストアを指す別のセッションインスタンス）で再開してください。 +実行が承認待ちで一時停止した場合は、同じセッションインスタンス（または同じバッキングストアを指す別のセッションインスタンス）で再開し、再開されたターンが同じ保存済み会話履歴を継続するようにします。 ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -67,27 +67,27 @@ if result.interruptions: セッションメモリが有効な場合: -1. **各実行前**: runner はセッションの会話履歴を自動的に取得し、それを入力アイテムの先頭に追加します。 -2. **各実行後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、assistant 応答、ツール呼び出しなど）がセッションに自動的に保存されます。 -3. **コンテキスト保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 +1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの前に追加します。 +2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）がセッションに自動的に保存されます。 +3. **コンテキストの保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。 -これにより、`.to_input_list()` を手動で呼び出し、実行間の会話状態を管理する必要がなくなります。 +これにより、`.to_input_list()` を手動で呼び出したり、実行間の会話状態を管理したりする必要がなくなります。 -## 履歴と新しい入力のマージ制御 +## 履歴と新しい入力のマージ方法の制御 -セッションを渡すと、runner は通常、モデル入力を次のように準備します。 +セッションを渡すと、ランナーは通常、モデル入力を次のように準備します。 1. セッション履歴（`session.get_items(...)` から取得） -2. 新しいターンの入力 +2. 新しいターン入力 -モデル呼び出しの前にそのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは 2 つのリストを受け取ります。 +モデル呼び出しの前にこのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは次の 2 つのリストを受け取ります。 - `history`: 取得されたセッション履歴（すでに入力アイテム形式に正規化済み） - `new_input`: 現在のターンの新しい入力アイテム モデルに送信する最終的な入力アイテムのリストを返します。 -コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは新しいターンに属するアイテムのみです。そのため、古い履歴を並べ替えたりフィルターしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。 +コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK は新しいターンに属するアイテムのみを永続化します。そのため、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。 ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,16 +109,16 @@ result = await Runner.run( ) ``` -セッションがアイテムを保存する方法を変えずに、カスタムの刈り込み、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終パスが必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。 +セッションがアイテムを保存する方法を変更せずに、カスタムの枝刈り、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終的な処理が必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。 -## 取得履歴の制限 +## 取得する履歴の制限 -各実行前に取得する履歴量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。 +各実行の前に取得する履歴の量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。 - `SessionSettings(limit=None)`（デフォルト）: 利用可能なすべてのセッションアイテムを取得します -- `SessionSettings(limit=N)`: 直近の `N` 個のアイテムのみを取得します +- `SessionSettings(limit=N)`: 直近の `N` アイテムのみを取得します -これは [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を通じて実行ごとに適用できます。 +これは、[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を介して実行ごとに適用できます。 ```python from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行に対して `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズに上限を設けたい長い会話で有用です。 +セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズを上限設定したい長い会話で便利です。 ## メモリ操作 ### 基本操作 -セッションは会話履歴を管理するためのいくつかの操作をサポートしています。 +セッションは、会話履歴を管理するためのいくつかの操作をサポートしています。 ```python from agents import SQLiteSession @@ -165,9 +165,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 @@ -204,26 +204,26 @@ SDK は、さまざまなユースケース向けに複数のセッション実 以下の詳細な例を読む前に、開始点を選ぶためにこの表を使用してください。 -| セッションタイプ | 最適な用途 | 備考 | +| セッションタイプ | 最適な用途 | 注記 | | --- | --- | --- | | `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルバックまたはインメモリ | -| `AsyncSQLiteSession` | `aiosqlite` を使う非同期 SQLite | 非同期ドライバーサポートを備えた拡張バックエンド | -| `RedisSession` | ワーカー/サービス間で共有されるメモリ | 低レイテンシの分散デプロイに適しています | -| `SQLAlchemySession` | 既存データベースを持つ本番アプリ | SQLAlchemy がサポートするデータベースで動作します | -| `MongoDBSession` | すでに MongoDB を使用している、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo。順序付け用のアトミックシーケンスカウンター | -| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数の状態ストアに加えて TTL と整合性制御をサポート | -| `OpenAIConversationsSession` | OpenAI 内のサーバー管理ストレージ | OpenAI Conversations API ベースの履歴 | -| `OpenAIResponsesCompactionSession` | 自動コンパクションを伴う長い会話 | 別のセッションバックエンドのラッパー | -| `AdvancedSQLiteSession` | SQLite と分岐/分析 | 機能セットはより重めです。専用ページを参照してください | -| `EncryptedSession` | 別のセッション上の暗号化 + TTL | ラッパーです。まず基盤となるバックエンドを選択してください | +| `AsyncSQLiteSession` | `aiosqlite` を使用した非同期 SQLite | 非同期ドライバー対応の拡張バックエンド | +| `RedisSession` | ワーカーやサービス間で共有するメモリ | 低レイテンシの分散デプロイに適しています | +| `SQLAlchemySession` | 既存データベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースで動作します | +| `MongoDBSession` | すでに MongoDB を使用しているアプリ、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo；順序付け用のアトミックシーケンスカウンター | +| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数のステートストアに加え、TTL と整合性制御をサポートします | +| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API をバックエンドとする履歴 | +| `OpenAIResponsesCompactionSession` | 自動圧縮を伴う長い会話 | 別のセッションバックエンドをラップします | +| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析 | より多機能です。専用ページを参照してください | +| `EncryptedSession` | 別のセッション上での暗号化と TTL | ラッパーです。まず基盤となるバックエンドを選択してください | -一部の実装には追加の詳細を含む専用ページがあり、それぞれの小節内でインラインにリンクされています。 +一部の実装には、追加の詳細を含む専用ページがあります。それらは各サブセクション内でリンクされています。 -ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドおよびアイテム永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置換ではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。 +ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドとアイテムの永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置き換えではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。 ### OpenAI Conversations API セッション -`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。 +`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations)を使用します。 ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -257,11 +257,11 @@ result = await Runner.run( print(result.final_output) # "California" ``` -### OpenAI Responses コンパクションセッション +### OpenAI Responses 圧縮セッション -Responses API（`responses.compact`）で保存済み会話履歴をコンパクト化するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターン後に自動的にコンパクションできます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。 +Responses API（`responses.compact`）で保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターンの後に自動的に圧縮できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。 -#### 典型的な使用法（自動コンパクション） +#### 一般的な使用方法（自動圧縮） ```python from agents import Agent, Runner, SQLiteSession @@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -デフォルトでは、候補しきい値に達すると、各ターン後にコンパクションが実行されます。 +デフォルトでは、候補しきい値に達すると各ターンの後に圧縮が実行されます。 -`compaction_mode="previous_response_id"` は、Responses API の応答 ID を使ってすでにターンをチェーンしている場合に最適です。`compaction_mode="input"` は代わりに現在のセッションアイテムからコンパクションリクエストを再構築します。これは応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に有用です。デフォルトの `"auto"` は、利用可能な中で最も安全なオプションを選択します。 +`compaction_mode="previous_response_id"` は、Responses API の応答 ID でターンをすでに連鎖させている場合に最も適しています。`compaction_mode="input"` は、代わりに現在のセッションアイテムから圧縮リクエストを再構築します。これは、応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に便利です。デフォルトの `"auto"` は、利用可能な中で最も安全な選択肢を選びます。 -エージェントが `ModelSettings(store=False)` で実行されている場合、Responses API は後で参照するために最後の応答を保持しません。このステートレスな設定では、デフォルトの `"auto"` モードは `previous_response_id` に依存する代わりに、入力ベースのコンパクションにフォールバックします。完全な例については [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。 +エージェントが `ModelSettings(store=False)` で実行される場合、Responses API は後で検索するための最後の応答を保持しません。このステートレスな構成では、デフォルトの `"auto"` モードは `previous_response_id` に依存するのではなく、入力ベースの圧縮にフォールバックします。完全な例については、[`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。 -#### 自動コンパクションがストリーミングをブロックする可能性 +#### auto-compaction によるストリーミングのブロック -コンパクションはセッション履歴をクリアして書き直すため、SDK は実行が完了したとみなす前にコンパクションの終了を待ちます。ストリーミングモードでは、コンパクションが重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになる可能性があります。 +圧縮はセッション履歴をクリアして書き換えるため、SDK は実行完了とみなす前に圧縮の完了を待ちます。ストリーミングモードでは、圧縮が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになることがあります。 -低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動コンパクションを無効にし、ターン間（またはアイドル時間中）に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ強制的にコンパクションするかを決定できます。 +低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動圧縮を無効にし、ターン間（またはアイドル時間中）に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ圧縮を強制するかを決めることができます。 ```python from agents import Agent, Runner, SQLiteSession @@ -332,7 +332,7 @@ result = await Runner.run( ### 非同期 SQLite セッション -`aiosqlite` による SQLite 永続化を使いたい場合は、`AsyncSQLiteSession` を使用します。 +`aiosqlite` をバックエンドとする SQLite の永続化が必要な場合は、`AsyncSQLiteSession` を使用します。 ```bash pip install aiosqlite @@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis セッション -複数のワーカーまたはサービス間で共有セッションメモリを使うには、`RedisSession` を使用します。 +複数のワーカーまたはサービス間で共有セッションメモリを使用するには、`RedisSession` を使用します。 ```bash pip install openai-agents[redis] @@ -387,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -詳細なドキュメントについては [SQLAlchemy セッション](sqlalchemy_session.md)を参照してください。 +詳細なドキュメントについては、[SQLAlchemy セッション](sqlalchemy_session.md)を参照してください。 ### Dapr セッション -すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なる状態ストアバックエンド間を移動できるセッションストレージが必要な場合は、`DaprSession` を使用します。 +すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なるステートストアバックエンドへ移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。 ```bash pip install openai-agents[dapr] @@ -412,18 +412,18 @@ async with DaprSession.from_address( print(result.final_output) ``` -備考: +注記: -- `from_address(...)` は Dapr クライアントを作成し、その所有権を持ちます。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。 -- バッキング状態ストアが TTL をサポートしている場合に、古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。 +- `from_address(...)` は Dapr クライアントを作成し、所有します。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。 +- 基盤となるステートストアが TTL をサポートしている場合に古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。 - より強い read-after-write 保証が必要な場合は、`consistency=DAPR_CONSISTENCY_STRONG` を渡します。 -- Dapr Python SDK は HTTP サイドカーエンドポイントも確認します。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。 +- Dapr Python SDK は HTTP サイドカーエンドポイントもチェックします。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。 - ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順については、[`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) を参照してください。 ### MongoDB セッション -すでに MongoDB を使用しているアプリケーションや、水平スケーラブルなマルチプロセスセッションストレージが必要なアプリケーションでは、`MongoDBSession` を使用します。 +すでに MongoDB を使用しているアプリケーション、または水平スケーラブルでマルチプロセス対応のセッションストレージが必要なアプリケーションには、`MongoDBSession` を使用します。 ```bash pip install openai-agents[mongodb] @@ -446,16 +446,16 @@ print(result.final_output) await session.close() ``` -備考: +注記: -- `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` 時に閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op になり、ライフサイクルは呼び出し元に残ります。 -- そのほかの変更なしに、`mongodb+srv://user:password@cluster.example.mongodb.net` URI を `from_uri(...)` に渡すことで、[MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。 -- 2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルト `agent_sessions`）および `messages_collection=`（デフォルト `agent_messages`）で構成できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントには、同時書き込み元やプロセス間で順序を保持する単調増加の `seq` カウンターが含まれます。 +- `from_uri(...)` は `AsyncMongoClient` を作成し、所有し、`session.close()` で閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op となり、ライフサイクルは呼び出し元が保持します。 +- ほかの変更なしに、`from_uri(...)` に `mongodb+srv://user:password@cluster.example.mongodb.net` URI を渡すことで [MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。 +- 2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルトは `agent_sessions`）と `messages_collection=`（デフォルトは `agent_messages`）で設定できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントは、同時実行の書き込み元やプロセスをまたいで順序を保持する単調増加の `seq` カウンターを持ちます。 - 最初の実行前に接続性を確認するには、`await session.ping()` を使用します。 -### Advanced SQLite セッション +### 高度な SQLite セッション -会話の分岐、利用状況分析、構造化クエリを備えた拡張 SQLite セッションです。 +会話の分岐、使用状況分析、構造化クエリを備えた拡張 SQLite セッションです。 ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -475,7 +475,7 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -詳細なドキュメントについては [Advanced SQLite セッション](advanced_sqlite_session.md)を参照してください。 +詳細なドキュメントについては、[高度な SQLite セッション](advanced_sqlite_session.md)を参照してください。 ### 暗号化セッション @@ -502,34 +502,34 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -詳細なドキュメントについては [暗号化セッション](encrypted_session.md)を参照してください。 +詳細なドキュメントについては、[暗号化セッション](encrypted_session.md)を参照してください。 ### その他のセッションタイプ -組み込みオプションはさらにいくつかあります。`examples/memory/` および `extensions/memory/` 配下のソースコードを参照してください。 +組み込みの選択肢はほかにもいくつかあります。`examples/memory/` と `extensions/memory/` 以下のソースコードを参照してください。 ## 運用パターン ### セッション ID の命名 -会話を整理しやすくする意味のあるセッション ID を使用してください。 +会話を整理しやすい、意味のあるセッション ID を使用してください。 - ユーザーベース: `"user_12345"` - スレッドベース: `"thread_abc123"` - コンテキストベース: `"support_ticket_456"` -### メモリ永続化 +### メモリの永続化 - 一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します - 永続的な会話にはファイルベース SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します -- `aiosqlite` ベースの実装が必要な場合は非同期 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）を使用します -- 共有された低レイテンシのセッションメモリには Redis バックのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します -- SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy によるセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します -- すでに MongoDB を使用している、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します -- 組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドに対応する本番クラウドネイティブデプロイには、Dapr 状態ストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します -- 履歴を OpenAI Conversations API に保存したい場合は、OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します -- 任意のセッションを透過的な暗号化と TTL ベースの有効期限切れでラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します -- より高度なユースケースでは、他の本番システム（たとえば Django）向けのカスタムセッションバックエンドの実装を検討してください +- `aiosqlite` ベースの実装が必要な場合は、非同期 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）を使用します +- 共有された低レイテンシのセッションメモリには、Redis バックのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します +- SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy を利用したセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) を使用します +- すでに MongoDB を使用しているアプリケーション、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します +- 組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドをサポートする本番クラウドネイティブデプロイには、Dapr ステートストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します +- OpenAI Conversations API に履歴を保存したい場合は、OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します +- 透過的な暗号化と TTL ベースの有効期限で任意のセッションをラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します +- より高度なユースケースでは、ほかの本番システム（たとえば Django）向けのカスタムセッションバックエンドの実装を検討してください ### 複数セッション @@ -684,15 +684,15 @@ result = await Runner.run( ) ``` -## コミュニティセッション実装 +## コミュニティによるセッション実装 コミュニティは追加のセッション実装を開発しています。 | パッケージ | 説明 | |---------|-------------| -| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション | +| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django 対応データベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション | -セッション実装を構築した場合は、ここに追加するためのドキュメント PR をぜひ提出してください。 +セッション実装を構築した場合は、ぜひドキュメント PR を送ってここに追加してください。 ## API リファレンス @@ -700,12 +700,12 @@ result = await Runner.run( - [`Session`][agents.memory.session.Session] - プロトコルインターフェイス - [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 実装 -- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API コンパクションラッパー +- [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 圧縮ラッパー - [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本的な SQLite 実装 - [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` に基づく非同期 SQLite 実装 - [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis バックのセッション実装 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy による実装 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy を利用した実装 - [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB バックのセッション実装 -- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状態ストア実装 +- [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr ステートストア実装 - [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite - [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向けの暗号化ラッパー \ No newline at end of file diff --git a/docs/ja/sessions/sqlalchemy_session.md b/docs/ja/sessions/sqlalchemy_session.md index 6c7b3cfe1a..850237d070 100644 --- a/docs/ja/sessions/sqlalchemy_session.md +++ b/docs/ja/sessions/sqlalchemy_session.md @@ -4,11 +4,11 @@ search: --- # SQLAlchemy セッション -`SQLAlchemySession` は SQLAlchemy を使用して本番運用対応のセッション実装を提供し、セッションストレージに SQLAlchemy がサポートする任意のデータベース ( PostgreSQL 、 MySQL 、 SQLite など ) を使用できます。 +`SQLAlchemySession` は SQLAlchemy を使用して、本番環境に対応したセッション実装を提供します。これにより、セッションストレージとして SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) を使用できます。 ## インストール -SQLAlchemy セッションには `sqlalchemy` extra が必要です。 +SQLAlchemy セッションには `sqlalchemy` extra が必要です: ```bash pip install openai-agents[sqlalchemy] @@ -18,7 +18,7 @@ pip install openai-agents[sqlalchemy] ### データベース URL の使用 -開始する最も簡単な方法です。 +始めるための最も簡単な方法です: ```python import asyncio @@ -42,9 +42,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -### 既存 engine の使用 +### 既存エンジンの使用 -既存の SQLAlchemy engine があるアプリケーション向けです。 +既存の SQLAlchemy エンジンを持つアプリケーション向けです: ```python import asyncio @@ -77,4 +77,4 @@ if __name__ == "__main__": ## API リファレンス - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - メインクラス -- [`Session`][agents.memory.session.Session] - ベースセッションプロトコル \ No newline at end of file +- [`Session`][agents.memory.session.Session] - 基本セッションプロトコル \ No newline at end of file diff --git a/docs/ja/streaming.md b/docs/ja/streaming.md index 98e0d24f74..62f7e42169 100644 --- a/docs/ja/streaming.md +++ b/docs/ja/streaming.md @@ -4,17 +4,17 @@ 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] オブジェクトの非同期ストリームが得られます。 -非同期イテレーターが終了するまで、`result.stream_events()` を消費し続けてください。イテレーターが終了するまで、ストリーミング実行は完了しません。また、セッション永続化、承認の記録管理、履歴の圧縮といった後処理は、最後の可視トークンが到着した後に完了する場合があります。ループを抜けると、`result.is_complete` は最終的な実行状態を反映します。 +非同期イテレーターが終了するまで、`result.stream_events()` を消費し続けてください。ストリーミング実行は、イテレーターが終了するまで完了しません。また、セッションの永続化、承認の記録管理、履歴の圧縮などの後処理は、最後の可視トークンが到着した後に完了する場合があります。ループが終了すると、`result.is_complete` は最終的な実行状態を反映します。 -## Raw 応答イベント +## raw レスポンスイベント -[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントには `response.created`、`response.output_text.delta` などの type とデータがあります。これらのイベントは、応答メッセージが生成され次第ユーザーへストリーミングしたい場合に便利です。 +[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントには型（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、レスポンスメッセージが生成され次第、ユーザーにストリーミングしたい場合に役立ちます。 -コンピュータツールの raw イベントは、保存された結果と同じプレビュー版と GA 版の区別を維持します。プレビューのフローでは、1 つの `action` を持つ `computer_call` アイテムをストリーミングします。一方、`gpt-5.5` では、バッチ化された `actions[]` を持つ `computer_call` アイテムをストリーミングできます。より高レベルの [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] サーフェスでは、これに対してコンピュータ専用の特別なイベント名は追加されません。どちらの形も `tool_called` として表面化し、スクリーンショットの結果は `computer_call_output` アイテムをラップする `tool_output` として返されます。 +コンピュータツールの raw イベントは、保存された実行結果と同じ preview と GA の区別を維持します。Preview フローでは、1 つの `action` を持つ `computer_call` アイテムをストリーミングします。一方、`gpt-5.5` では、バッチ化された `actions[]` を持つ `computer_call` アイテムをストリーミングできます。高レベルの [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] サーフェスは、このために特別なコンピュータ専用イベント名を追加しません。どちらの形式も引き続き `tool_called` として表面化し、スクリーンショットの実行結果は `computer_call_output` アイテムをラップする `tool_output` として返されます。 たとえば、これは LLM によって生成されたテキストをトークンごとに出力します。 @@ -41,7 +41,7 @@ if __name__ == "__main__": ## ストリーミングと承認 -ストリーミングは、ツール承認のために一時停止する実行と互換性があります。ツールが承認を必要とする場合、`result.stream_events()` は終了し、保留中の承認は [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] に公開されます。`result.to_state()` で結果を [`RunState`][agents.run_state.RunState] に変換し、割り込みを承認または拒否してから、`Runner.run_streamed(...)` で再開します。 +ストリーミングは、ツール承認のために一時停止する実行と互換性があります。ツールに承認が必要な場合、`result.stream_events()` は終了し、保留中の承認は [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。`result.to_state()` を使って実行結果を [`RunState`][agents.run_state.RunState] に変換し、中断を承認または拒否してから、`Runner.run_streamed(...)` で再開します。 ```python result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.") @@ -57,25 +57,25 @@ if result.interruptions: pass ``` -一時停止と再開の完全なウォークスルーについては、[human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。 +一時停止/再開の完全なウォークスルーについては、[human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。 ## 現在のターン後のストリーミングのキャンセル -途中でストリーミング実行を停止する必要がある場合は、[`result.cancel()`][agents.result.RunResultStreaming.cancel] を呼び出します。デフォルトでは、これにより実行は即座に停止します。停止する前に現在のターンをきれいに完了させるには、代わりに `result.cancel(mode="after_turn")` を呼び出します。 +途中でストリーミング実行を停止する必要がある場合は、[`result.cancel()`][agents.result.RunResultStreaming.cancel] を呼び出します。デフォルトでは、これにより実行はすぐに停止します。停止する前に現在のターンを正常に完了させるには、代わりに `result.cancel(mode="after_turn")` を呼び出します。 -`result.stream_events()` が終了するまで、ストリーミング実行は完了しません。SDK は、最後の可視トークンの後も、セッション項目の永続化、承認状態の確定、履歴の圧縮をまだ行っている可能性があります。 +ストリーミング実行は、`result.stream_events()` が終了するまで完了しません。最後の可視トークンの後も、SDK がセッションアイテムを永続化したり、承認状態を確定したり、履歴を圧縮したりしている場合があります。 -[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] から手動で続行していて、`cancel(mode="after_turn")` がツールターン後に停止した場合は、すぐに新しいユーザーターンを追加するのではなく、その正規化された入力で `result.last_agent` を再実行して、その未完了のターンを続行してください。 -- ストリーミング実行がツール承認のために停止した場合、それを新しいターンとして扱わないでください。ストリームの読み出しを最後まで行い、`result.interruptions` を確認し、代わりに `result.to_state()` から再開してください。 -- 次のモデル呼び出しの前に、取得したセッション履歴と新しいユーザー入力をどのようにマージするかをカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。そこで新規ターンの項目を書き換えた場合、その書き換え後のバージョンがそのターンで永続化されます。 +[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] から手動で継続しており、`cancel(mode="after_turn")` がツールターンの後で停止した場合は、すぐに新しいユーザーターンを追加するのではなく、その正規化された入力で `result.last_agent` を再実行して、未完了のターンを継続してください。 +- ストリーミング実行がツール承認のために停止した場合、それを新しいターンとして扱わないでください。ストリームの読み出しを最後まで完了し、`result.interruptions` を確認して、代わりに `result.to_state()` から再開してください。 +- 次のモデル呼び出しの前に、取得したセッション履歴と新しいユーザー入力をどのようにマージするかをカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。そこで新しいターンのアイテムを書き換えた場合、その書き換え後のバージョンがそのターンとして永続化されます。 -## 実行項目イベントとエージェントイベント +## 実行アイテムイベントとエージェントイベント -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。これらは、項目が完全に生成されたときに通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を送信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変わったとき（例: ハンドオフの結果として）に更新を提供します。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を送信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果として）に更新を提供します。 -### 実行項目イベント名 +### 実行アイテムイベント名 -`RunItemStreamEvent.name` は、固定されたセマンティックなイベント名のセットを使用します。 +`RunItemStreamEvent.name` は、固定された一連のセマンティックなイベント名を使用します。 - `message_output_created` - `handoff_requested` @@ -89,9 +89,9 @@ if result.interruptions: - `mcp_approval_response` - `mcp_list_tools` -`handoff_occured` は、後方互換性のために意図的にスペルミスされています。 +`handoff_occured` は、後方互換性のため意図的にスペルミスのままになっています。 -ホスト型ツール検索を使用する場合、モデルがツール検索リクエストを発行すると `tool_search_called` が発行され、Responses API が読み込まれたサブセットを返すと `tool_search_output_created` が発行されます。 +ホストされたツール検索を使用する場合、モデルがツール検索リクエストを発行すると `tool_search_called` が送出され、Responses API が読み込まれたサブセットを返すと `tool_search_output_created` が送出されます。 たとえば、これは raw イベントを無視し、更新をユーザーにストリーミングします。 diff --git a/docs/ja/tools.md b/docs/ja/tools.md index 208e39cdd9..18a68fee1c 100644 --- a/docs/ja/tools.md +++ b/docs/ja/tools.md @@ -4,37 +4,37 @@ search: --- # ツール -ツールにより、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。 +ツールにより、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの操作といったアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。 - OpenAI がホストするツール: OpenAI サーバー上でモデルと並行して実行されます。 -- ローカル/ランタイム実行ツール: `ComputerTool` と `ApplyPatchTool` は常にお使いの環境で実行され、`ShellTool` はローカルまたはホストされたコンテナーで実行できます。 -- Function Calling: 任意の Python 関数をツールとしてラップします。 +- ローカル/ランタイム実行ツール: `ComputerTool` と `ApplyPatchTool` は常にユーザーの環境で実行され、`ShellTool` はローカルまたはホスト型コンテナーで実行できます。 +- Function calling: 任意の Python 関数をツールとしてラップします。 - Agents as tools: 完全なハンドオフなしで、エージェントを呼び出し可能なツールとして公開します。 -- 実験的: Codex ツール: ツール呼び出しからワークスペーススコープの Codex タスクを実行します。 +- 実験的機能: Codex ツール: ツール呼び出しから、ワークスペーススコープの Codex タスクを実行します。 -## ツール種別の選択 +## ツールタイプの選択 -このページをカタログとして使い、その後、管理するランタイムに合ったセクションへ進んでください。 +このページをカタログとして使い、制御するランタイムに一致するセクションに移動してください。 -| 実現したいこと | 参照先 | +| やりたいこと | 開始先 | | --- | --- | -| OpenAI 管理のツール（Web 検索、ファイル検索、コードインタープリター、ホストされた MCP、画像生成）を使用する | [ホストされたツール](#hosted-tools) | -| ツール検索で大規模なツールサーフェスをランタイムまで遅延させる | [ホストされたツール検索](#hosted-tool-search) | -| 自分のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) | +| OpenAI 管理のツール（Web 検索、ファイル検索、code interpreter、ホスト型 MCP、画像生成）を使用する | [ホスト型ツール](#hosted-tools) | +| ツール検索で大規模なツールサーフェスをランタイムまで遅延させる | [ホスト型ツール検索](#hosted-tool-search) | +| 自身のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) | | Python 関数をツールとしてラップする | [関数ツール](#function-tools) | -| あるエージェントがハンドオフなしで別のエージェントを呼び出せるようにする | [Agents as tools](#agents-as-tools) | -| エージェントからワークスペーススコープの Codex タスクを実行する | [実験的: Codex ツール](#experimental-codex-tool) | +| ハンドオフなしで、あるエージェントが別のエージェントを呼び出せるようにする | [Agents as tools](#agents-as-tools) | +| エージェントからワークスペーススコープの Codex タスクを実行する | [実験的機能: Codex ツール](#experimental-codex-tool) | -## ホストされたツール +## ホスト型ツール OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合に、いくつかの組み込みツールを提供しています。 -- [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントが Web を検索できるようにします。 -- [`FileSearchTool`][agents.tool.FileSearchTool] は、OpenAI Vector Stores から情報を取得できるようにします。 -- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は、LLM がサンドボックス環境でコードを実行できるようにします。 +- [`WebSearchTool`][agents.tool.WebSearchTool] により、エージェントは Web を検索できます。 +- [`FileSearchTool`][agents.tool.FileSearchTool] により、OpenAI ベクトルストアから情報を取得できます。 +- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] により、LLM はサンドボックス化された環境でコードを実行できます。 - [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモート MCP サーバーのツールをモデルに公開します。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] は、プロンプトから画像を生成します。 -- [`ToolSearchTool`][agents.tool.ToolSearchTool] は、モデルが遅延されたツール、名前空間、またはホストされた MCP サーバーを必要に応じて読み込めるようにします。 +- [`ToolSearchTool`][agents.tool.ToolSearchTool] により、モデルは遅延されたツール、名前空間、またはホスト型 MCP サーバーを必要に応じて読み込めます。 高度なホスト型検索オプション: @@ -60,11 +60,11 @@ async def main(): print(result.final_output) ``` -### ホストされたツール検索 +### ホスト型ツール検索 -ツール検索により、OpenAI Responses モデルは大規模なツールサーフェスをランタイムまで遅延できるため、モデルは現在のターンに必要なサブセットだけを読み込みます。多数の関数ツール、名前空間グループ、またはホストされた MCP サーバーがあり、すべてのツールを最初から公開せずにツールスキーマのトークンを削減したい場合に便利です。 +ツール検索により、OpenAI Responses モデルは大規模なツールサーフェスをランタイムまで遅延できるため、モデルは現在のターンに必要なサブセットのみを読み込みます。これは、多数の関数ツール、名前空間グループ、またはホスト型 MCP サーバーがあり、すべてのツールを事前に公開せずにツールスキーマのトークンを削減したい場合に便利です。 -候補となるツールがエージェントを構築する時点ですでに分かっている場合は、ホストされたツール検索から始めてください。アプリケーションが何を読み込むかを動的に決める必要がある場合、Responses API はクライアント実行のツール検索もサポートしていますが、標準の `Runner` はそのモードを自動実行しません。 +エージェントを構築する時点で候補ツールがすでに分かっている場合は、ホスト型ツール検索から始めてください。アプリケーションが何を読み込むかを動的に決定する必要がある場合、Responses API はクライアント実行型ツール検索もサポートしていますが、標準の `Runner` はそのモードを自動実行しません。 ```python from typing import Annotated @@ -108,24 +108,24 @@ print(result.final_output) 知っておくべきこと: -- ホストされたツール検索は OpenAI Responses モデルでのみ利用できます。現在の Python SDK サポートは `openai>=2.25.0` に依存します。 -- エージェントで遅延読み込みサーフェスを設定する場合は、`ToolSearchTool()` を正確に 1 つ追加してください。 +- ホスト型ツール検索は、OpenAI Responses モデルでのみ利用できます。現在の Python SDK のサポートは `openai>=2.25.0` に依存します。 +- エージェントで遅延読み込みサーフェスを構成するときは、`ToolSearchTool()` を正確に 1 つ追加してください。 - 検索可能なサーフェスには、`@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])`、`HostedMCPTool(tool_config={..., "defer_loading": True})` が含まれます。 -- 遅延読み込みの関数ツールは `ToolSearchTool()` と組み合わせる必要があります。名前空間のみの構成でも、モデルが必要に応じて適切なグループを読み込めるように `ToolSearchTool()` を使用できます。 +- 遅延読み込みの関数ツールは、`ToolSearchTool()` と組み合わせる必要があります。名前空間のみの構成でも、モデルが必要に応じて適切なグループを読み込めるようにするために `ToolSearchTool()` を使用できます。 - `tool_namespace()` は、`FunctionTool` インスタンスを共有の名前空間名と説明の下にグループ化します。これは通常、`crm`、`billing`、`shipping` など、関連するツールが多数ある場合に最適です。 -- OpenAI の公式ベストプラクティスガイダンスは [可能な場合は名前空間を使用する](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible) です。 -- 可能な場合は、多数の個別に遅延された関数よりも、名前空間またはホストされた MCP サーバーを優先してください。通常、モデルにより良い高レベルの検索サーフェスと、より良いトークン節約を提供します。 -- 名前空間では、即時ツールと遅延ツールを混在させることができます。`defer_loading=True` がないツールは即座に呼び出し可能なままで、同じ名前空間内の遅延ツールはツール検索を通じて読み込まれます。 +- OpenAI の公式ベストプラクティスガイダンスは、[可能な場合は名前空間を使用する](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)です。 +- 可能な場合は、多数の個別に遅延された関数よりも、名前空間またはホスト型 MCP サーバーを優先してください。通常、これらはモデルに対してより優れた高レベルの検索サーフェスと、より大きなトークン節約を提供します。 +- 名前空間では、即時ツールと遅延ツールを混在させることができます。`defer_loading=True` のないツールはすぐに呼び出し可能なままで、同じ名前空間内の遅延ツールはツール検索を通じて読み込まれます。 - 目安として、各名前空間はかなり小さく保ち、理想的には 10 個未満の関数にしてください。 -- 名前付き `tool_choice` は、裸の名前空間名や遅延のみのツールを対象にできません。`auto`、`required`、または実際のトップレベルで呼び出し可能なツール名を優先してください。 -- `ToolSearchTool(execution="client")` は手動の Responses オーケストレーション用です。モデルがクライアント実行の `tool_search_call` を出力した場合、標準の `Runner` はそれを実行する代わりに例外を発生させます。 -- ツール検索のアクティビティは、専用のアイテムタイプとイベントタイプで [`RunResult.new_items`](results.md#new-items) および [`RunItemStreamEvent`](streaming.md#run-item-event-names) に表示されます。 -- 名前空間による読み込みとトップレベルの遅延ツールの両方を網羅した、完全に実行可能なコード例については `examples/tools/tool_search.py` を参照してください。 +- 名前付きの `tool_choice` は、裸の名前空間名や遅延のみのツールを対象にできません。`auto`、`required`、または実際のトップレベルの呼び出し可能なツール名を優先してください。 +- `ToolSearchTool(execution="client")` は、手動の Responses オーケストレーション用です。モデルがクライアント実行型の `tool_search_call` を発行した場合、標準の `Runner` はそれを実行せずに例外を送出します。 +- ツール検索アクティビティは、[`RunResult.new_items`](results.md#new-items) と [`RunItemStreamEvent`](streaming.md#run-item-event-names) に、専用の項目タイプとイベントタイプで表示されます。 +- 名前空間付き読み込みとトップレベルの遅延ツールの両方を扱う、完全に実行可能なコード例については、`examples/tools/tool_search.py` を参照してください。 - 公式プラットフォームガイド: [ツール検索](https://developers.openai.com/api/docs/guides/tools-tool-search)。 -### ホストされたコンテナーシェル + スキル +### ホスト型コンテナーシェル + スキル -`ShellTool` は OpenAI がホストするコンテナー実行もサポートしています。ローカルランタイムではなく、管理されたコンテナー内でモデルにシェルコマンドを実行させたい場合は、このモードを使用してください。 +`ShellTool` は、OpenAI がホストするコンテナー実行もサポートしています。ローカルランタイムではなく、管理されたコンテナー内でモデルにシェルコマンドを実行させたい場合は、このモードを使用します。 ```python from agents import Agent, Runner, ShellTool, ShellToolSkillReference @@ -158,52 +158,52 @@ result = await Runner.run( print(result.final_output) ``` -後続の実行で既存のコンテナーを再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。 +以降の実行で既存のコンテナーを再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。 知っておくべきこと: -- ホストされたシェルは Responses API のシェルツールを通じて利用できます。 -- `container_auto` はリクエスト用にコンテナーをプロビジョニングし、`container_reference` は既存のコンテナーを再利用します。 +- ホスト型シェルは、Responses API シェルツールを通じて利用できます。 +- `container_auto` は、リクエスト用のコンテナーをプロビジョニングします。`container_reference` は既存のコンテナーを再利用します。 - `container_auto` には `file_ids` と `memory_limit` も含めることができます。 -- `environment.skills` はスキル参照とインラインスキルバンドルを受け付けます。 -- ホストされた環境では、`ShellTool` に `executor`、`needs_approval`、`on_approval` を設定しないでください。 -- `network_policy` は `disabled` モードと `allowlist` モードをサポートします。 -- allowlist モードでは、`network_policy.domain_secrets` が名前でドメインスコープのシークレットを注入できます。 -- 完全な例については `examples/tools/container_shell_skill_reference.py` と `examples/tools/container_shell_inline_skill.py` を参照してください。 -- OpenAI プラットフォームガイド: [Shell](https://platform.openai.com/docs/guides/tools-shell) および [Skills](https://platform.openai.com/docs/guides/tools-skills)。 +- `environment.skills` は、スキル参照とインラインスキルバンドルを受け取ります。 +- ホスト型環境では、`ShellTool` に `executor`、`needs_approval`、`on_approval` を設定しないでください。 +- `network_policy` は、`disabled` モードと `allowlist` モードをサポートします。 +- `allowlist` モードでは、`network_policy.domain_secrets` により、名前でドメインスコープのシークレットを注入できます。 +- 完全なコード例については、`examples/tools/container_shell_skill_reference.py` と `examples/tools/container_shell_inline_skill.py` を参照してください。 +- OpenAI プラットフォームガイド: [シェル](https://platform.openai.com/docs/guides/tools-shell) と [スキル](https://platform.openai.com/docs/guides/tools-skills)。 ## ローカルランタイムツール -ローカルランタイムツールは、モデル応答自体の外部で実行されます。モデルは依然としていつ呼び出すかを決定しますが、実際の処理はアプリケーションまたは設定された実行環境が行います。 +ローカルランタイムツールは、モデル応答自体の外で実行されます。モデルは引き続きいつ呼び出すかを決定しますが、実際の作業はアプリケーションまたは構成された実行環境が実行します。 -`ComputerTool` と `ApplyPatchTool` は、常にユーザーが提供するローカル実装を必要とします。`ShellTool` は両方のモードにまたがります。管理された実行を行いたい場合は上記のホストされたコンテナー設定を使用し、自分のプロセスでコマンドを実行したい場合は以下のローカルランタイム設定を使用してください。 +`ComputerTool` と `ApplyPatchTool` には、常にユーザーが提供するローカル実装が必要です。`ShellTool` は両方のモードにまたがっています。管理された実行が必要な場合は上記のホスト型コンテナー構成を使用し、自身のプロセスでコマンドを実行したい場合は下記のローカルランタイム構成を使用してください。 ローカルランタイムツールでは、実装を提供する必要があります。 - [`ComputerTool`][agents.tool.ComputerTool]: GUI/ブラウザー自動化を有効にするために、[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] インターフェイスを実装します。 -- [`ShellTool`][agents.tool.ShellTool]: ローカル実行とホストされたコンテナー実行の両方に対応する最新のシェルツールです。 -- [`LocalShellTool`][agents.tool.LocalShellTool]: 従来のローカルシェル統合です。 +- [`ShellTool`][agents.tool.ShellTool]: ローカル実行とホスト型コンテナー実行の両方に対応する最新のシェルツールです。 +- [`LocalShellTool`][agents.tool.LocalShellTool]: レガシーなローカルシェル連携です。 - [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: diff をローカルに適用するために [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] を実装します。 -- ローカルシェルスキルは `ShellTool(environment={"type": "local", "skills": [...]})` で利用できます。 +- ローカルシェルスキルは、`ShellTool(environment={"type": "local", "skills": [...]})` で利用できます。 ### ComputerTool と Responses コンピュータツール -`ComputerTool` は引き続きローカルハーネスです。[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] 実装を提供し、SDK がそのハーネスを OpenAI Responses API のコンピュータサーフェスにマッピングします。 +`ComputerTool` は引き続きローカルハーネスです。[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] の実装を提供すると、SDK はそのハーネスを OpenAI Responses API のコンピュータサーフェスにマッピングします。 -明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストでは、SDK は GA 組み込みツールペイロード `{"type": "computer"}` を送信します。古い `computer-use-preview` モデルは、プレビュー用ペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` のままです。これは OpenAI の [コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/) で説明されているプラットフォーム移行を反映しています。 +明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストでは、SDK は GA 組み込みツールペイロード `{"type": "computer"}` を送信します。古い `computer-use-preview` モデルでは、プレビューペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` が維持されます。これは、OpenAI の [コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/)で説明されているプラットフォーム移行を反映しています。 - モデル: `computer-use-preview` -> `gpt-5.5` - ツールセレクター: `computer_use_preview` -> `computer` - コンピュータ呼び出しの形状: `computer_call` ごとに 1 つの `action` -> `computer_call` 上のバッチ化された `actions[]` -- 切り詰め: プレビューパスでは `ModelSettings(truncation="auto")` が必要 -> GA パスでは不要 +- 切り捨て: プレビューパスでは `ModelSettings(truncation="auto")` が必須 -> GA パスでは不要 -SDK は、実際の Responses リクエストで有効なモデルから、そのワイヤー形式を選択します。プロンプトテンプレートを使用し、プロンプト側がモデルを所有しているためリクエストで `model` を省略する場合、`model="gpt-5.5"` を明示したままにするか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。 +SDK は、実際の Responses リクエスト上の有効なモデルから、そのワイヤ形式を選択します。プロンプトテンプレートを使用し、プロンプトがモデルを保持しているためリクエストが `model` を省略する場合、`model="gpt-5.5"` を明示的に保持するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。 -[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け付けられ、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` がない場合、これらの文字列は引き続き通常の関数名のように動作します。 +[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け入れられ、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。`ComputerTool` がない場合、これらの文字列は引き続き通常の関数名のように動作します。 -この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリによって支えられている場合に重要です。GA の `computer` ペイロードはシリアライズ時に `environment` や寸法を必要としないため、未解決のファクトリでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるように、解決済みの `Computer` または `AsyncComputer` インスタンスが必要です。 +この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーによって支えられている場合に重要です。GA の `computer` ペイロードはシリアライズ時に `environment` や寸法を必要としないため、未解決のファクトリーでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるように、解決済みの `Computer` または `AsyncComputer` インスタンスが引き続き必要です。 -ランタイムでは、どちらのパスも同じローカルハーネスを使用します。プレビュー応答は単一の `action` を持つ `computer_call` アイテムを出力します。`gpt-5.5` はバッチ化された `actions[]` を出力でき、SDK は `computer_call_output` スクリーンショットアイテムを生成する前に、それらを順番に実行します。実行可能な Playwright ベースのハーネスについては `examples/tools/computer_use.py` を参照してください。 +ランタイムでは、どちらのパスも同じローカルハーネスを使用します。プレビュー応答は単一の `action` を持つ `computer_call` 項目を発行します。`gpt-5.5` はバッチ化された `actions[]` を発行でき、SDK は `computer_call_output` スクリーンショット項目を生成する前にそれらを順番に実行します。実行可能な Playwright ベースのハーネスについては、`examples/tools/computer_use.py` を参照してください。 ```python from agents import Agent, ApplyPatchTool, ShellTool @@ -247,16 +247,16 @@ agent = Agent( ## 関数ツール -任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的にセットアップします。 +任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的に設定します。 -- ツール名は Python 関数の名前になります（または名前を指定できます） +- ツールの名前は Python 関数の名前になります（または名前を指定できます） - ツールの説明は関数の docstring から取得されます（または説明を指定できます） - 関数入力のスキーマは、関数の引数から自動的に作成されます -- 無効にしない限り、各入力の説明は関数の docstring から取得されます +- 各入力の説明は、無効化されていない限り、関数の docstring から取得されます 関数シグネチャの抽出には Python の `inspect` モジュールを使用し、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマ作成には `pydantic` を使用します。 -OpenAI Responses モデルを使用している場合、`@function_tool(defer_loading=True)` は `ToolSearchTool()` が読み込むまで関数ツールを隠します。関連する関数ツールを [`tool_namespace()`][agents.tool.tool_namespace] でグループ化することもできます。完全なセットアップと制約については [ホストされたツール検索](#hosted-tool-search) を参照してください。 +OpenAI Responses モデルを使用している場合、`@function_tool(defer_loading=True)` は `ToolSearchTool()` が読み込むまで関数ツールを隠します。[`tool_namespace()`][agents.tool.tool_namespace] を使用して、関連する関数ツールをグループ化することもできます。詳細な設定と制約については、[ホスト型ツール検索](#hosted-tool-search)を参照してください。 ```python import json @@ -310,7 +310,7 @@ for tool in agent.tools: 1. 関数の引数には任意の Python 型を使用でき、関数は同期でも非同期でもかまいません。 2. Docstring が存在する場合、説明と引数の説明を取得するために使用されます -3. 関数は任意で `context` を受け取ることができます（最初の引数でなければなりません）。ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。 +3. 関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。 4. デコレートされた関数をツールのリストに渡すことができます。 ??? note "出力を表示するには展開してください" @@ -385,20 +385,20 @@ for tool in agent.tools: ### 関数ツールからの画像またはファイルの返却 -テキスト出力の返却に加えて、関数ツールの出力として 1 つ以上の画像またはファイルを返すことができます。そのためには、次のいずれかを返せます。 +テキスト出力を返すことに加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返すことができます。そのためには、次のいずれかを返せます。 - 画像: [`ToolOutputImage`][agents.tool.ToolOutputImage]（または TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） - ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（または TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） -- テキスト: 文字列または文字列化できるオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） +- テキスト: 文字列または文字列化可能なオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） ### カスタム関数ツール -Python 関数をツールとして使用したくない場合もあります。その場合は、必要に応じて [`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を提供する必要があります。 +Python 関数をツールとして使いたくない場合があります。希望する場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次のものを提供する必要があります。 - `name` - `description` -- `params_json_schema`: 引数用の JSON スキーマ -- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列としての引数を受け取り、ツール出力（たとえば、テキスト、structured tool output オブジェクト、または出力のリスト）を返す非同期関数 +- `params_json_schema`: 引数用の JSON スキーマです +- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] と引数を JSON 文字列として受け取り、ツール出力（たとえば、テキスト、構造化ツール出力オブジェクト、または出力のリスト）を返す非同期関数です。 ```python from typing import Any @@ -433,16 +433,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`][] にあります。 ### Pydantic Field による引数の制約と説明 -Pydantic の [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) を使用して、ツール引数に制約（例: 数値の最小/最大、文字列の長さやパターン）と説明を追加できます。Pydantic と同様に、デフォルトベース（`arg: int = Field(..., ge=1)`）と `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）の両方の形式がサポートされます。生成される JSON スキーマと検証には、これらの制約が含まれます。 +Pydantic の [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) を使用して、ツール引数に制約（例: 数値の最小/最大、文字列の長さまたはパターン）と説明を追加できます。Pydantic と同様に、デフォルトベース（`arg: int = Field(..., ge=1)`）と `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）の両方の形式がサポートされます。生成される JSON スキーマと検証には、これらの制約が含まれます。 ```python from typing import Annotated @@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr ### 関数ツールのタイムアウト -非同期関数ツールに対して、`@function_tool(timeout=...)` で呼び出しごとのタイムアウトを設定できます。 +`@function_tool(timeout=...)` を使用して、非同期関数ツールに呼び出し単位のタイムアウトを設定できます。 ```python import asyncio @@ -482,12 +482,12 @@ agent = Agent( ) ``` -タイムアウトに達すると、デフォルトの動作は `timeout_behavior="error_as_result"` で、モデルに見えるタイムアウトメッセージ（例: `Tool 'slow_lookup' timed out after 2 seconds.`）を送信します。 +タイムアウトに達した場合、デフォルトの動作は `timeout_behavior="error_as_result"` で、モデルに表示されるタイムアウトメッセージ（例: `Tool 'slow_lookup' timed out after 2 seconds.`）を送信します。 -タイムアウト処理は制御できます。 +タイムアウト処理を制御できます。 -- `timeout_behavior="error_as_result"`（デフォルト）: モデルが回復できるようにタイムアウトメッセージを返します。 -- `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] を発生させ、実行を失敗させます。 +- `timeout_behavior="error_as_result"`（デフォルト）: モデルが回復できるように、タイムアウトメッセージをモデルに返します。 +- `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] を送出し、実行を失敗させます。 - `timeout_error_function=...`: `error_as_result` を使用する場合のタイムアウトメッセージをカスタマイズします。 ```python @@ -511,15 +511,15 @@ except ToolTimeoutError as e: !!! note - タイムアウト設定は、非同期の `@function_tool` ハンドラーでのみサポートされます。 + タイムアウト構成は、非同期の `@function_tool` ハンドラーでのみサポートされます。 -### 関数ツールでのエラー処理 +### 関数ツールのエラー処理 -`@function_tool` を通じて関数ツールを作成するとき、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。 +`@function_tool` を介して関数ツールを作成する場合、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。 -- デフォルトでは（つまり何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。 -- 独自のエラー関数を渡した場合は、代わりにそれが実行され、応答が LLM に送信されます。 -- 明示的に `None` を渡した場合、ツール呼び出しエラーは再送出され、ユーザー側で処理できます。これは、モデルが無効な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などである可能性があります。 +- デフォルトでは（つまり何も渡さない場合）、LLM にエラーが発生したことを伝える `default_tool_error_function` が実行されます。 +- 独自のエラー関数を渡した場合は、それが代わりに実行され、その応答が LLM に送信されます。 +- 明示的に `None` を渡した場合、任意のツール呼び出しエラーが再送出され、呼び出し側で処理できます。これは、モデルが無効な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などになり得ます。 ```python from agents import function_tool, RunContextWrapper @@ -546,7 +546,7 @@ def get_user_profile(user_id: str) -> str: ## Agents as tools -一部のワークフローでは、制御をハンドオフするのではなく、中央のエージェントが専門エージェントのネットワークをオーケストレーションするようにしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。 +一部のワークフローでは、制御をハンドオフする代わりに、中央エージェントに専門特化したエージェントのネットワークをオーケストレーションさせたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。 ```python from agents import Agent, Runner @@ -587,7 +587,7 @@ async def main(): ### ツールエージェントのカスタマイズ -`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による structured input もサポートします。高度なオーケストレーション（たとえば、条件付きリトライ、フォールバック動作、複数のエージェント呼び出しのチェーン）には、ツール実装内で `Runner.run` を直接使用してください。 +`agent.as_tool` 関数は、エージェントをツールに簡単に変換するための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による構造化入力もサポートします。高度なオーケストレーション（たとえば、条件付きリトライ、フォールバック動作、複数のエージェント呼び出しのチェーン）の場合は、ツール実装内で `Runner.run` を直接使用してください。 ```python @function_tool @@ -606,29 +606,47 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### ツールエージェントの structured input +### ツールエージェントの構造化入力 -デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたは dataclass 型）を渡すことで structured schema を公開できます。 +デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたは dataclass 型）を渡すことで構造化スキーマを公開できます。 追加オプション: -- `include_input_schema=True` は、生成されるネストされた入力に完全な JSON Schema を含めます。 -- `input_builder=...` により、structured tool 引数をネストされたエージェント入力に変換する方法を完全にカスタマイズできます。 -- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内の解析済み structured payload が含まれます。 +- `include_input_schema=True` は、生成されるネストされた入力に完全な JSON スキーマを含めます。 +- `input_builder=...` により、構造化ツール引数がネストされたエージェント入力になる方法を完全にカスタマイズできます。 +- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内の解析済み構造化ペイロードが含まれます。 -完全に実行可能な例については `examples/agent_patterns/agents_as_tools_structured.py` を参照してください。 +```python +from pydantic import BaseModel, Field + + +class TranslationInput(BaseModel): + text: str = Field(description="Text to translate.") + source: str = Field(description="Source language.") + target: str = Field(description="Target language.") + + +translator_tool = translator_agent.as_tool( + tool_name="translate_text", + tool_description="Translate text between languages.", + parameters=TranslationInput, + include_input_schema=True, +) +``` + +完全に実行可能な例については、`examples/agent_patterns/agents_as_tools_structured.py` を参照してください。 ### ツールエージェントの承認ゲート -`Agent.as_tool(..., needs_approval=...)` は `function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中のアイテムが `result.interruptions` に表示されます。その後、`result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出した後に再開します。完全な一時停止/再開パターンについては、[ヒューマンインザループガイド](human_in_the_loop.md) を参照してください。 +`Agent.as_tool(..., needs_approval=...)` は、`function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中の項目が `result.interruptions` に表示されます。その後、`result.to_state()` を使い、`state.approve(...)` または `state.reject(...)` を呼び出した後に再開します。完全な一時停止/再開パターンについては、[Human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。 ### カスタム出力抽出 -特定のケースでは、中央エージェントへ返す前にツールエージェントの出力を変更したい場合があります。これは、次のような場合に役立ちます。 +場合によっては、中央エージェントに返す前に、ツールエージェントの出力を変更したいことがあります。これは、次のような場合に便利です。 - サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。 - エージェントの最終回答を変換または再フォーマットする（例: Markdown をプレーンテキストまたは CSV に変換する）。 -- 出力を検証する、またはエージェントの応答が欠落しているか不正な形式の場合にフォールバック値を提供する。 +- エージェントの応答が欠落している、または不正な形式の場合に、出力を検証するかフォールバック値を提供する。 これは、`as_tool` メソッドに `custom_output_extractor` 引数を指定することで実行できます。 @@ -650,12 +668,13 @@ json_tool = data_agent.as_tool( ``` カスタム抽出器内では、ネストされた [`RunResult`][agents.result.RunResult] も -[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] を公開します。これは、ネストされた実行結果を後処理するときに、外側のツール名、呼び出し ID、または raw 引数が必要な場合に便利です。 -[Results ガイド](results.md#agent-as-tool-metadata) を参照してください。 +[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] を公開します。これは、ネストされた実行結果を後処理する際に、 +外側のツール名、呼び出し ID、または生の引数が必要な場合に便利です。 +[実行結果ガイド](results.md#agent-as-tool-metadata)を参照してください。 ### ネストされたエージェント実行のストリーミング -ネストされたエージェントが出力するストリーミングイベントをリッスンしつつ、ストリーム完了後に最終出力を返すには、`as_tool` に `on_stream` コールバックを渡します。 +`as_tool` に `on_stream` コールバックを渡すと、ネストされたエージェントが発行するストリーミングイベントをリッスンしつつ、ストリーム完了後にその最終出力を返せます。 ```python from agents import AgentToolStreamEvent @@ -676,14 +695,14 @@ billing_agent_tool = billing_agent.as_tool( 想定されること: - イベントタイプは `StreamEvent["type"]` を反映します: `raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 -- `on_stream` を指定すると、ネストされたエージェントがストリーミングモードで自動的に実行され、最終出力を返す前にストリームが排出されます。 -- ハンドラーは同期または非同期のどちらでもよく、各イベントは到着順に配信されます。 -- ツールがモデルのツール呼び出し経由で起動された場合は `tool_call` が存在します。直接呼び出しでは `None` のままになる場合があります。 -- 完全に実行可能なサンプルについては `examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。 +- `on_stream` を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームが読み切られます。 +- ハンドラーは同期または非同期にできます。各イベントは到着した順に配信されます。 +- モデルツール呼び出しを介してツールが呼び出された場合、`tool_call` が存在します。直接呼び出しでは `None` のままになる場合があります。 +- 完全に実行可能なサンプルについては、`examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。 ### 条件付きツール有効化 -`is_enabled` パラメーターを使用すると、ランタイムでエージェントツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザー設定、またはランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。 +`is_enabled` パラメーターを使用して、ランタイムでエージェントツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザー設定、またはランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。 ```python import asyncio @@ -742,20 +761,20 @@ asyncio.run(main()) - **ブール値**: `True`（常に有効）または `False`（常に無効） - **呼び出し可能関数**: `(context, agent)` を受け取り、ブール値を返す関数 -- **非同期関数**: 複雑な条件ロジックのための非同期関数 +- **非同期関数**: 複雑な条件ロジック用の非同期関数 -無効化されたツールはランタイムで LLM から完全に隠されるため、次の用途に役立ちます。 +無効化されたツールは、ランタイムで LLM から完全に隠されるため、次のような用途に便利です。 - ユーザー権限に基づく機能ゲーティング - 環境固有のツール可用性（dev と prod） - 異なるツール構成の A/B テスト - ランタイム状態に基づく動的なツールフィルタリング -## 実験的: Codex ツール +## 実験的機能: Codex ツール `codex_tool` は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペーススコープのタスク（シェル、ファイル編集、MCP ツール）を実行できるようにします。このサーフェスは実験的であり、変更される可能性があります。 -メインエージェントが現在の実行から離れずに、範囲が限定されたワークスペースタスクを Codex に委任したい場合に使用します。デフォルトでは、ツール名は `codex` です。カスタム名を設定する場合は、`codex` であるか、`codex_` で始まる必要があります。エージェントに複数の Codex ツールを含める場合、それぞれ一意の名前を使用する必要があります。 +メインエージェントが現在の実行を離れることなく、範囲を限定したワークスペースタスクを Codex に委任したい場合に使用します。デフォルトでは、ツール名は `codex` です。カスタム名を設定する場合、それは `codex` であるか、`codex_` で始まる必要があります。エージェントに複数の Codex ツールが含まれる場合、それぞれが一意の名前を使用する必要があります。 ```python from agents import Agent @@ -784,33 +803,33 @@ agent = Agent( ) ``` -まず、次のオプショングループから始めてください。 +次のオプショングループから始めてください。 -- 実行サーフェス: `sandbox_mode` と `working_directory` は Codex が操作できる場所を定義します。これらを組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定します。 -- スレッドのデフォルト: `default_thread_options=ThreadOptions(...)` は、モデル、推論エフォート、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを設定します。従来の `web_search_enabled` よりも `web_search_mode` を優先してください。 -- ターンのデフォルト: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` や任意のキャンセル `signal` など、ターンごとの動作を設定します。 -- ツール I/O: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` アイテムを少なくとも 1 つ含める必要があります。`output_schema` により、structured Codex レスポンスを要求できます。 +- 実行サーフェス: `sandbox_mode` と `working_directory` は、Codex が操作できる場所を定義します。これらは組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定してください。 +- スレッドデフォルト: `default_thread_options=ThreadOptions(...)` は、モデル、推論エフォート、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを構成します。レガシーな `web_search_enabled` よりも `web_search_mode` を優先してください。 +- ターンデフォルト: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` や任意のキャンセル `signal` など、ターンごとの動作を構成します。 +- ツール I/O: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` 項目が少なくとも 1 つ含まれている必要があります。`output_schema` により、構造化された Codex 応答を要求できます。 -スレッドの再利用と永続化は別々の制御です。 +スレッド再利用と永続化は別々の制御です。 -- `persist_session=True` は、同じツールインスタンスへの繰り返し呼び出しに対して 1 つの Codex スレッドを再利用します。 -- `use_run_context_thread_id=True` は、同じ可変コンテキストオブジェクトを共有する実行間で、実行コンテキストにスレッド ID を保存して再利用します。 -- スレッド ID の優先順位は、呼び出しごとの `thread_id`、次に実行コンテキストのスレッド ID（有効な場合）、次に設定された `thread_id` オプションです。 +- `persist_session=True` は、同じツールインスタンスへの繰り返し呼び出しに 1 つの Codex スレッドを再利用します。 +- `use_run_context_thread_id=True` は、同じ可変コンテキストオブジェクトを共有する実行間で、実行コンテキスト内にスレッド ID を保存して再利用します。 +- スレッド ID の優先順位は、呼び出しごとの `thread_id`、次に実行コンテキストのスレッド ID（有効な場合）、次に構成済みの `thread_id` オプションです。 - デフォルトの実行コンテキストキーは、`name="codex"` の場合は `codex_thread_id`、`name="codex_"` の場合は `codex_thread_id_` です。`run_context_thread_id_key` で上書きできます。 -ランタイム設定: +ランタイム構成: - 認証: `CODEX_API_KEY`（推奨）または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡します。 - ランタイム: `codex_options.base_url` は CLI ベース URL を上書きします。 -- バイナリ解決: CLI パスを固定するには `codex_options.codex_path_override`（または `CODEX_PATH`）を設定します。それ以外の場合、SDK は `PATH` から `codex` を解決し、その後バンドルされたベンダーバイナリへフォールバックします。 -- 環境: `codex_options.env` はサブプロセス環境を完全に制御します。指定された場合、サブプロセスは `os.environ` を継承しません。 -- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes`（または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）は stdout/stderr リーダーの制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。 -- ストリーミング: `on_stream` はスレッド/ターンのライフサイクルイベントとアイテムイベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、および `error` アイテム更新）を受け取ります。 +- バイナリ解決: CLI パスを固定するには、`codex_options.codex_path_override`（または `CODEX_PATH`）を設定します。そうでない場合、SDK は `PATH` から `codex` を解決し、その後、同梱のベンダーバイナリにフォールバックします。 +- 環境: `codex_options.env` はサブプロセス環境を完全に制御します。これが指定された場合、サブプロセスは `os.environ` を継承しません。 +- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes`（または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）は stdout/stderr リーダー制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。 +- ストリーミング: `on_stream` はスレッド/ターンのライフサイクルイベントと項目イベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、`error` の項目更新）を受け取ります。 - 出力: 実行結果には `response`、`usage`、`thread_id` が含まれます。usage は `RunContextWrapper.usage` に追加されます。 -参考: +リファレンス: - [Codex ツール API リファレンス](ref/extensions/experimental/codex/codex_tool.md) - [ThreadOptions リファレンス](ref/extensions/experimental/codex/thread_options.md) - [TurnOptions リファレンス](ref/extensions/experimental/codex/turn_options.md) -- 完全に実行可能なサンプルについては `examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。 \ No newline at end of file +- 完全に実行可能なサンプルについては、`examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。 \ No newline at end of file diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index 216b151063..ec486bb631 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,55 +4,58 @@ search: --- # トレーシング -Agents SDK には組み込みのトレーシングが含まれており、エージェント実行中のイベントを包括的に記録します。これには、LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK には組み込みのトレーシングが含まれており、エージェント実行中のイベントの包括的な記録を収集します。これには、LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらには発生するカスタムイベントまで含まれます。[Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。無効にする一般的な方法は 3 つあります。 + トレーシングはデフォルトで有効になっています。一般的には、次の 3 つの方法で無効にできます。 - 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます - 2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード内でグローバルにトレーシングを無効化できます - 3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行に対してトレーシングを無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定することで、トレーシングをグローバルに無効化できます + 2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード内でトレーシングをグローバルに無効化できます + 3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定することで、単一の実行についてトレーシングを無効化できます -***OpenAI の API を使用し、Zero Data Retention ( ZDR ) ポリシーのもとで運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシー下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース** は、1 つの「ワークフロー」における単一のエンドツーエンド操作を表します。トレースは Span で構成されます。トレースには次のプロパティがあります。 - - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば、「Code generation」や「Customer service」などです。 - - `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: オプションのグループ ID で、同じ会話内の複数のトレースを関連付けるために使用します。たとえば、チャットスレッド ID を使用できます。 +- **トレース** は、「ワークフロー」の単一のエンドツーエンド操作を表します。これらはスパンで構成されます。トレースには以下のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「コード生成」や「カスタマーサービス」です。 + - `trace_id`: トレースの一意の ID です。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` でなければなりません。 + - `group_id`: 任意のグループ ID で、同じ会話からの複数のトレースを関連付けるために使用します。たとえば、チャットスレッド ID を使用できます。 - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースのオプションのメタデータです。 -- **スパン** は、開始時刻と終了時刻を持つ操作を表します。スパンには次のものがあります。 + - `metadata`: トレースの任意のメタデータです。 +- **スパン** は、開始時刻と終了時刻を持つ操作を表します。スパンには以下があります: - `started_at` と `ended_at` のタイムスタンプ。 - `trace_id`: そのスパンが属するトレースを表します - - `parent_id`: このスパンの親 Span を指します（存在する場合） - - `span_data`: Span に関する情報です。たとえば、`AgentSpanData` には Agent に関する情報が、`GenerationSpanData` には LLM 生成に関する情報が含まれます。 + - `parent_id`: このスパンの親スパン (存在する場合) を指します + - `span_data`: スパンに関する情報です。たとえば、`AgentSpanData` にはエージェントに関する情報が含まれ、`GenerationSpanData` には LLM 生成に関する情報が含まれる、などです。 ## デフォルトのトレーシング -デフォルトでは、SDK は次のものをトレースします。 +デフォルトでは、SDK は以下をトレースします: - `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。 - エージェントが実行されるたびに、`agent_span()` でラップされます -- LLM の生成は `generation_span()` でラップされます -- 関数ツールの各呼び出しは `function_span()` でラップされます +- LLM 生成は `generation_span()` でラップされます +- 関数ツール呼び出しはそれぞれ `function_span()` でラップされます - ガードレールは `guardrail_span()` でラップされます - ハンドオフは `handoff_span()` でラップされます -- 音声入力（ speech-to-text ）は `transcription_span()` でラップされます -- 音声出力（ text-to-speech ）は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の配下になる場合があります +- 音声入力 (音声テキスト変換) は `transcription_span()` でラップされます +- 音声出力 (テキスト音声変換) は `speech_span()` でラップされます +- 関連する音声スパンは `speech_group_span()` の下に親子関係として配置される場合があります -デフォルトでは、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] を使って名前やその他のプロパティを設定することもできます。 +デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へ送ることもできます（置き換え先または補助的な送信先として）。 +さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors)を設定して、トレースを他の送信先へ送信することもできます (置き換え、または副次的な送信先として)。 ## 長時間実行ワーカーと即時エクスポート -デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごとにバックグラウンドでトレースをエクスポートします。あるいは、インメモリキューがサイズのしきい値に達した場合はそれより早くエクスポートし、さらにプロセス終了時には最終フラッシュも実行します。Celery、RQ、Dramatiq、FastAPI のバックグラウンドタスクなどの長時間実行ワーカーでは、通常は追加コードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後には Traces ダッシュボードに表示されないことがあります。 +デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごとにバックグラウンドでトレースをエクスポートします。 +または、メモリ内キューがサイズトリガーに達した場合はそれより早くエクスポートし、 +プロセス終了時にも最終的なフラッシュを実行します。Celery、RQ、Dramatiq、FastAPI バックグラウンドタスクのような長時間実行ワーカーでは、通常、追加コードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後に Traces ダッシュボードへ表示されない場合があります。 -作業単位の終了時に即時配信を保証したい場合は、トレースコンテキストを抜けた後で [`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。 +作業単位の終了時に即時配信の保証が必要な場合は、トレースコンテキストが終了した後に +[`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。 ```python from agents import Runner, flush_traces, trace @@ -89,11 +92,12 @@ async def run(prompt: str, background_tasks: BackgroundTasks): return {"status": "queued"} ``` -[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファされているトレースとスパンがエクスポートされるまでブロックするため、不完全なトレースをフラッシュしないよう、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で問題ない場合は、この呼び出しは省略できます。 +[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファリングされているトレースとスパンが +エクスポートされるまでブロックします。そのため、部分的に構築されたトレースをフラッシュしないように、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で許容できる場合は、この呼び出しを省略できます。 ## 上位レベルのトレース -複数の `run()` 呼び出しを 1 つのトレースに含めたい場合があります。その場合は、コード全体を `trace()` でラップできます。 +場合によっては、`run()` への複数回の呼び出しを 1 つのトレースの一部にしたいことがあります。コード全体を `trace()` でラップすることで実現できます。 ```python from agents import Agent, Runner, trace @@ -108,49 +112,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 2 回の `Runner.run` 呼び出しは `with trace()` でラップされているため、個別に 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 +1. 2 つの `Runner.run` 呼び出しは `with trace()` でラップされているため、個別の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。 ## トレースの作成 -[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。その方法は 2 つあります。 +[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始および終了する必要があります。これには 2 つの方法があります: -1. **推奨**: トレースをコンテキストマネージャーとして使用します。つまり、`with trace(...) as my_trace` のように使います。これにより、適切なタイミングでトレースが自動的に開始および終了されます。 +1. **推奨**: トレースをコンテキストマネージャーとして使用します。つまり、`with trace(...) as my_trace` とします。これにより、適切なタイミングでトレースが自動的に開始および終了されます。 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 -現在のトレースは、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これは、並行実行でも自動的に動作することを意味します。トレースを手動で開始または終了する場合は、現在のトレースを更新するために `start()` / `finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。これにより、並行処理でも自動的に機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパンの作成 -各種 [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。 +各種 [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数が利用できます。 -スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの配下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。 +スパンは自動的に現在のトレースの一部となり、現在の最も近いスパンの下にネストされます。この現在のスパンは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。 -## 機微データ +## 機密データ -一部のスパンでは、機微データとなり得る情報を取得する場合があります。 +一部のスパンは、機密性の高い可能性があるデータをキャプチャする場合があります。 -`generation_span()` は LLM 生成の入出力を保存し、`function_span()` は関数呼び出しの入出力を保存します。これらには機微データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそのデータの取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使ってそのデータのキャプチャを無効化できます。 -同様に、音声スパンにはデフォルトで入力音声と出力音声の base64 エンコード済み PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。 +同様に、音声スパンには、デフォルトで入力および出力音声の base64 エンコードされた PCM データが含まれます。この音声データのキャプチャは、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成することで無効化できます。 -デフォルトでは、`trace_include_sensitive_data` は `True` です。コードを書かずにデフォルト値を設定するには、アプリの実行前に環境変数 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` を `true/1` または `false/0` に設定してください。 +デフォルトでは、`trace_include_sensitive_data` は `True` です。アプリを実行する前に `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 環境変数を `true/1` または `false/0` にエクスポートすることで、コードなしでデフォルトを設定できます。 ## カスタムトレーシングプロセッサー -トレーシングの高レベルなアーキテクチャは次のとおりです。 +トレーシングの高レベルアーキテクチャは次のとおりです: - 初期化時に、トレースの作成を担当するグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 -- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で設定します。このプロセッサーは、トレース / スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、これがスパンとトレースをバッチで OpenAI バックエンドへエクスポートします。 +- `TraceProvider` は、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成します。`BackendSpanExporter` は、スパンとトレースをバッチで OpenAI バックエンドにエクスポートします。 -このデフォルト設定をカスタマイズして、別のバックエンドまたは追加のバックエンドにトレースを送信したり、エクスポーターの動作を変更したりするには、2 つの方法があります。 +このデフォルト設定をカスタマイズして、代替または追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、2 つの選択肢があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使うと、準備が整ったトレースとスパンを受け取る **追加の** トレースプロセッサーを追加できます。これにより、トレースを OpenAI のバックエンドへ送信することに加えて、独自の処理も行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使うと、デフォルトのプロセッサーを独自のトレースプロセッサーで **置き換え** できます。これは、そうした処理を行う `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使用すると、利用可能になったトレースとスパンを受け取る **追加** のトレーシングプロセッサーを追加できます。これにより、トレースを OpenAI バックエンドに送信することに加えて、独自の処理を実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使用すると、デフォルトのプロセッサーを独自のトレーシングプロセッサーで **置き換える** ことができます。これは、それを行う `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。 -## non-OpenAI モデルでのトレーシング +## 非 OpenAI モデルでのトレーシング -OpenAI 以外のモデルでも、OpenAI API キーを使用することで、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。アダプターの選択と設定上の注意点については、Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションを参照してください。 +非 OpenAI モデルで OpenAI API キーを使用すると、トレーシングを無効にする必要なく、OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。アダプターの選択とセットアップ時の注意点については、モデルガイドの[サードパーティアダプター](models/index.md#third-party-adapters)セクションを参照してください。 ```python import os @@ -171,7 +175,7 @@ agent = Agent( ) ``` -単一の実行に対してのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更するのではなく、`RunConfig` 経由で渡してください。 +単一の実行で異なるトレーシングキーだけが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。 ```python from agents import Runner, RunConfig @@ -183,21 +187,21 @@ await Runner.run( ) ``` -## 追加の注記 -- Openai Traces ダッシュボードで無料トレースを表示できます。 +## 補足事項 +- Openai Traces ダッシュボードで無料のトレースを表示できます。 ## エコシステム統合 -以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシング機能をサポートしています。 +以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシングインターフェイスに対応しています。 ### 外部トレーシングプロセッサー一覧 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (セルフホスト/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks ホスト)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/ja/usage.md b/docs/ja/usage.md index 28cccd5512..3e92c79fdf 100644 --- a/docs/ja/usage.md +++ b/docs/ja/usage.md @@ -2,24 +2,24 @@ search: exclude: true --- -# 使用方法 +# 使用量 -Agents SDK は、すべての実行についてトークン使用量を自動的に追跡します。実行コンテキストからこれにアクセスし、コストの監視、制限の適用、または分析の記録に使用できます。 +Agents SDK は、各実行のトークン使用量を自動的に追跡します。実行コンテキストからアクセスでき、コストの監視、上限の適用、分析情報の記録に利用できます。 ## 追跡対象 -- **requests**: 実行された LLM API 呼び出し回数 +- **requests**: 実行された LLM API 呼び出しの数 - **input_tokens**: 送信された入力トークンの合計 -- **output_tokens**: 受信した出力トークンの合計 +- **output_tokens**: 受信された出力トークンの合計 - **total_tokens**: 入力 + 出力 -- **request_usage_entries**: リクエストごとの使用量内訳の一覧 +- **request_usage_entries**: リクエストごとの使用量内訳のリスト - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 実行からの使用量アクセス +## 実行からの使用量へのアクセス -`Runner.run(...)` の後、`result.context_wrapper.usage` 経由で使用量にアクセスします。 +`Runner.run(...)` の後に、`result.context_wrapper.usage` 経由で使用量にアクセスします。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -31,20 +31,20 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）にわたって集計されます。 +使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。 -### サードパーティアダプターでの使用量有効化 +### サードパーティアダプターでの使用量の有効化 -使用量レポートは、サードパーティアダプターおよびプロバイダーバックエンドによって異なります。アダプター経由のモデルに依存し、正確な `result.context_wrapper.usage` の値が必要な場合: +使用量レポートは、サードパーティアダプターやプロバイダーのバックエンドによって異なります。アダプター経由のモデルに依存しており、正確な `result.context_wrapper.usage` 値が必要な場合は、次の点に注意してください。 -- `AnyLLMModel` では、上流プロバイダーが使用量を返すと自動的に伝播されます。ストリーミング Chat Completions バックエンドでは、使用量チャンクが出力される前に `ModelSettings(include_usage=True)` が必要な場合があります。 -- `LitellmModel` では、一部のプロバイダーバックエンドは既定で使用量をレポートしないため、`ModelSettings(include_usage=True)` が必要になることがよくあります。 +- `AnyLLMModel` では、上流プロバイダーが使用量を返す場合、使用量は自動的に伝播されます。ストリーミングされた Chat Completions バックエンドでは、使用量チャンクが出力される前に `ModelSettings(include_usage=True)` が必要になる場合があります。 +- `LitellmModel` では、一部のプロバイダーのバックエンドがデフォルトで使用量をレポートしないため、`ModelSettings(include_usage=True)` が必要になることがよくあります。 -Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションにあるアダプター固有の注意事項を確認し、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 +Models ガイドの [サードパーティアダプター](models/index.md#third-party-adapters) セクションにあるアダプター固有の注記を確認し、デプロイ予定の正確なプロバイダーバックエンドを検証してください。 ## リクエストごとの使用量追跡 -SDK は、各 API リクエストの使用量を `request_usage_entries` で自動追跡します。これは、詳細なコスト計算やコンテキストウィンドウ消費の監視に役立ちます。 +SDK は、各 API リクエストの使用量を `request_usage_entries` で自動的に追跡します。これは詳細なコスト計算やコンテキストウィンドウ消費量の監視に役立ちます。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -53,9 +53,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## セッションでの使用量アクセス +## セッションでの使用量へのアクセス -`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行の使用量を返します。セッションはコンテキスト用に会話履歴を維持しますが、各実行の使用量は独立しています。 +`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行の使用量を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用量は独立しています。 ```python session = SQLiteSession("my_conversation") @@ -67,11 +67,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): @@ -82,9 +82,9 @@ class MyHooks(RunHooks): ## API リファレンス -詳細な API ドキュメントは以下を参照してください。 +詳細な API ドキュメントについては、以下を参照してください。 - [`Usage`][agents.usage.Usage] - 使用量追跡データ構造 - [`RequestUsage`][agents.usage.RequestUsage] - リクエストごとの使用量詳細 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用量にアクセス -- [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフック \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフックイン \ No newline at end of file diff --git a/docs/ja/visualization.md b/docs/ja/visualization.md index e8a6f7e3ee..ab0a9f3d7f 100644 --- a/docs/ja/visualization.md +++ b/docs/ja/visualization.md @@ -2,26 +2,26 @@ search: exclude: true --- -# エージェント可視化 +# エージェントの可視化 -エージェント可視化では、 **Graphviz** を使用して、エージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 +エージェントの可視化では、**Graphviz** を使用して、エージェントとその関係を構造化されたグラフィカルな表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。 ## インストール -オプションの `viz` 依存関係グループをインストールします。 +任意の `viz` 依存関係グループをインストールします。 ```bash pip install "openai-agents[viz]" ``` -## グラフ生成 +## グラフの生成 -`draw_graph` 関数を使用してエージェント可視化を生成できます。この関数は、以下の構成を持つ有向グラフを作成します。 +`draw_graph` 関数を使用して、エージェントの可視化を生成できます。この関数は、以下のような有向グラフを作成します。 -- **エージェント** は黄色のボックスとして表現されます。 -- **MCP サーバー** は灰色のボックスとして表現されます。 -- **ツール** は緑色の楕円として表現されます。 -- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジです。 +- **エージェント** は黄色のボックスで表されます。 +- **MCP サーバー** は灰色のボックスで表されます。 +- **ツール** は緑色の楕円で表されます。 +- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジとして表されます。 ### 使用例 @@ -67,37 +67,40 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![エージェントグラフ](../assets/images/graph.png) + +これにより、**トリアージエージェント** の構造と、サブエージェントおよびツールとの接続を視覚的に表すグラフが生成されます。 -これにより、 **triage agent** の構造と、サブエージェントおよびツールへの接続を視覚的に表すグラフが生成されます。 ## 可視化の理解 -生成されるグラフには以下が含まれます。 +生成されるグラフには、以下が含まれます。 - エントリーポイントを示す **開始ノード** (`__start__`)。 -- 黄色で塗りつぶされた **長方形** として表現されるエージェント。 -- 緑色で塗りつぶされた **楕円** として表現されるツール。 -- 灰色で塗りつぶされた **長方形** として表現される MCP サーバー。 +- 黄色で塗りつぶされた **長方形** として表されるエージェント。 +- 緑色で塗りつぶされた **楕円** として表されるツール。 +- 灰色で塗りつぶされた **長方形** として表される MCP サーバー。 - 相互作用を示す有向エッジ: - - エージェント間ハンドオフには **実線矢印**。 - - ツール呼び出しには **点線矢印**。 - - MCP サーバー呼び出しには **破線矢印**。 -- 実行が終了する位置を示す **終了ノード** (`__end__`)。 + - エージェント間のハンドオフを表す **実線矢印**。 + - ツール呼び出しを表す **点線矢印**。 + - MCP サーバー呼び出しを表す **破線矢印**。 +- 実行が終了する場所を示す **終了ノード** (`__end__`)。 -**注:** MCP サーバーは `agents` パッケージの最近のバージョン ( **v0.2.8** で確認済み ) で描画されます。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。 +**注:** MCP サーバーは、最近のバージョンの +`agents` パッケージで描画されます（**v0.2.8** で確認済み）。可視化で MCP ボックスが表示されない場合は、 +最新リリースにアップグレードしてください。 ## グラフのカスタマイズ -### グラフ表示 -デフォルトでは、 `draw_graph` はグラフをインライン表示します。グラフを別ウィンドウで表示するには、次のように記述します。 +### グラフの表示 +デフォルトでは、`draw_graph` はグラフをインラインで表示します。グラフを別ウィンドウで表示するには、次のように記述します。 ```python draw_graph(triage_agent).view() ``` -### グラフ保存 -デフォルトでは、 `draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します。 +### グラフの保存 +デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します。 ```python draw_graph(triage_agent, filename="agent_graph") diff --git a/docs/ja/voice/pipeline.md b/docs/ja/voice/pipeline.md index 902aed880c..2c7161ba1a 100644 --- a/docs/ja/voice/pipeline.md +++ b/docs/ja/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # パイプラインとワークフロー -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントオーケストレーションを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声への変換を処理します。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントを活用したワークフローを音声アプリに変換しやすくするクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、ワークフローの出力を音声に戻す処理を担います。 ```mermaid graph LR @@ -34,25 +34,25 @@ graph LR ## パイプラインの設定 -パイプラインを作成する際には、いくつかの項目を設定できます。 +パイプラインを作成する際に、いくつかの項目を設定できます。 1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]。新しい音声が文字起こしされるたびに実行されるコードです。 -2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。以下のような項目を設定できます。 - - モデル名をモデルにマッピングできるモデルプロバイダー - - トレーシング。トレーシングを無効にするかどうか、音声ファイルをアップロードするかどうか、ワークフロー名、トレース ID などを含みます。 - - プロンプト、言語、使用するデータ型など、 TTS および STT モデルの設定 +2. 使用する [`speech-to-text`][agents.voice.model.STTModel] モデルと [`text-to-speech`][agents.voice.model.TTSModel] モデル +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。次のような項目を設定できます。 + - モデル名をモデルに対応付けられるモデルプロバイダー + - トレーシング。トレーシングを無効にするか、音声ファイルをアップロードするか、ワークフロー名、トレース ID などを含みます。 + - TTS モデルと STT モデルの設定。プロンプト、言語、使用するデータ型などです。 ## パイプラインの実行 -パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力は 2 つの形式で渡せます。 +[`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドを使ってパイプラインを実行できます。このメソッドでは、次の 2 つの形式で音声入力を渡せます。 -1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声文字起こしがあり、それに対する結果だけを生成したい場合に使用します。これは、話者が話し終えたタイミングを検出する必要がないケースで有用です。たとえば、事前録音された音声がある場合や、ユーザーが話し終えたことが明確な push-to-talk アプリなどです。 -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたかどうかを検出する必要がある場合に使用します。検出された音声チャンクを随時プッシュでき、音声パイプラインは "activity detection" と呼ばれるプロセスを通じて、適切なタイミングで自動的にエージェントのワークフローを実行します。 +1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声文字起こしがあり、それに対する実行結果だけを生成したい場合に使用します。話者が話し終えたタイミングを検出する必要がない場合に便利です。たとえば、事前録音された音声がある場合や、ユーザーが話し終えたことが明確なプッシュ・トゥ・トークアプリなどです。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングを検出する必要がある可能性がある場合に使用します。検出された音声チャンクを送信でき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングでエージェントワークフローを自動的に実行します。 -## 結果 +## 実行結果 -音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングできるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] にはいくつかの種類があります。 +音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングできるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] には、次のようないくつかの種類があります。 1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]。音声チャンクを含みます。 2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]。ターンの開始や終了などのライフサイクルイベントを通知します。 @@ -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 4e93673a60..aa9bf9a419 100644 --- a/docs/ja/voice/quickstart.md +++ b/docs/ja/voice/quickstart.md @@ -6,7 +6,7 @@ search: ## 前提条件 -Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップ済みであることを確認してください。次に、SDK からオプションの音声依存関係をインストールします。 +Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。次に、SDK から任意の音声依存関係をインストールします。 ```bash pip install 'openai-agents[voice]' @@ -16,9 +16,9 @@ pip install 'openai-agents[voice]' 知っておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。 -1. 音声をテキストに変換するために speech-to-text モデルを実行します。 -2. 結果を生成するために、通常はエージェント型ワークフローであるあなたのコードを実行します。 -3. 結果テキストを音声に戻すために text-to-speech モデルを実行します。 +1. 音声認識モデルを実行して、音声をテキストに変換します。 +2. 通常はエージェント的なワークフローであるコードを実行して、結果を生成します。 +3. テキスト読み上げモデルを実行して、結果のテキストを音声に戻します。 ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## エージェント -まず、いくつかのエージェントを設定しましょう。この SDK でエージェントを構築したことがあれば、おなじみの内容です。いくつかのエージェント、ハンドオフ、ツールを用意します。 +まず、いくつかのエージェントをセットアップしましょう。この SDK でエージェントを構築したことがあれば、なじみのある内容です。ここでは、複数のエージェント、ハンドオフ、ツールを用意します。 ```python import asyncio @@ -92,7 +92,7 @@ agent = Agent( ## 音声パイプライン -ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用して、シンプルな音声パイプラインを設定します。 +ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインをセットアップします。 ```python from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline @@ -124,7 +124,7 @@ async for event in result.stream(): ``` -## すべての統合 +## 全体の統合 ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -この例を実行すると、エージェントがあなたに話しかけます！エージェントに自分で話しかけられるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。 \ No newline at end of file +この例を実行すると、エージェントがあなたに話しかけます！エージェントに自分で話しかけられるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例を確認してください。 \ No newline at end of file diff --git a/docs/ja/voice/tracing.md b/docs/ja/voice/tracing.md index 319d4c9165..fabae466de 100644 --- a/docs/ja/voice/tracing.md +++ b/docs/ja/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # トレーシング -[エージェントがトレーシングされる](../tracing.md)のと同様に、音声パイプラインも自動的にトレーシングされます。 +[エージェントのトレーシング](../tracing.md)と同様に、音声パイプラインも自動的にトレーシングされます。 -基本的なトレーシング情報については上記のトレーシングドキュメントを参照できますが、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を介してパイプラインのトレーシングを追加で設定することもできます。 +基本的なトレーシング情報については上記のトレーシングドキュメントを参照できますが、さらに [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを設定できます。 -トレーシングに関連する主要なフィールドは次のとおりです。 +トレーシングに関連する主なフィールドは次のとおりです。 -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトでは、トレーシングは有効です。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに、音声文字起こしのような潜在的に機微なデータを含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われるものには適用されません。 +- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは、トレーシングは有効です。 +- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに音声文字起こしなど、潜在的に機微なデータを含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われる処理には適用されません。 - [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。 -- [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース Workflow の名前です。 -- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` で、複数のトレースを関連付けられます。 +- [`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.trace_metadata]: トレースに含める追加のメタデータです。 \ No newline at end of file diff --git a/docs/ko/agents.md b/docs/ko/agents.md index ebdedd84ef..18ce2e955d 100644 --- a/docs/ko/agents.md +++ b/docs/ko/agents.md @@ -4,49 +4,49 @@ search: --- # 에이전트 -에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다. +에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs와 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다. -단일 일반 `Agent`를 정의하거나 사용자 지정하려는 경우 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 매니페스트로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 안에서 실행되어야 한다면 [샌드박스 에이전트 개념](sandbox/guide.md)을 읽어보세요. +단일 일반 `Agent`를 정의하거나 사용자 지정하려면 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 매니페스트로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 안에서 실행되어야 한다면 [샌드박스 에이전트 개념](sandbox/guide.md)을 읽어보세요. -SDK는 OpenAI 모델에 대해 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다. `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 제어하려면 대신 Responses API를 직접 사용하세요. +SDK는 OpenAI 모델에 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다. `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 소유하고 싶다면 대신 Responses API를 직접 사용하세요. ## 다음 가이드 선택 -이 페이지를 에이전트 정의를 위한 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요. +이 페이지를 에이전트 정의의 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요. -| 원하는 작업 | 다음 읽을 문서 | +| 원하는 작업 | 다음 읽을 내용 | | --- | --- | -| 모델 또는 프로바이더 설정 선택 | [모델](models/index.md) | +| 모델 또는 공급자 설정 선택 | [모델](models/index.md) | | 에이전트에 기능 추가 | [도구](tools.md) | -| 실제 리포지토리, 문서 번들 또는 격리된 워크스페이스에 대해 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) | -| 매니저 방식 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) | +| 실제 리포지토리, 문서 번들 또는 격리된 워크스페이스에서 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) | +| 관리자 방식 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) | | 핸드오프 동작 구성 | [핸드오프](handoffs.md) | | 턴 실행, 이벤트 스트리밍 또는 대화 상태 관리 | [에이전트 실행](running_agents.md) | -| 최종 출력, 실행 항목 또는 재개 가능한 상태 검사 | [결과](results.md) | -| 로컬 종속성 및 런타임 상태 공유 | [컨텍스트 관리](context.md) | +| 최종 출력, 실행 항목 또는 재개 가능 상태 검사 | [결과](results.md) | +| 로컬 의존성과 런타임 상태 공유 | [컨텍스트 관리](context.md) | -## 기본 구성 +## 기본 설정 에이전트의 가장 일반적인 속성은 다음과 같습니다. | 속성 | 필수 여부 | 설명 | | --- | --- | --- | -| `name` | 예 | 사람이 읽을 수 있는 에이전트 이름입니다. | -| `instructions` | 예 | 시스템 프롬프트 또는 동적 instructions 콜백입니다. [동적 instructions](#dynamic-instructions)를 참조하세요. | +| `name` | 예 | 사람이 읽기 쉬운 에이전트 이름입니다. | +| `instructions` | 아니요 | 시스템 프롬프트 또는 동적 instructions 콜백입니다. 강력히 권장됩니다. [동적 instructions](#dynamic-instructions)를 참조하세요. | | `prompt` | 아니요 | OpenAI Responses API 프롬프트 구성입니다. 정적 프롬프트 객체 또는 함수를 허용합니다. [프롬프트 템플릿](#prompt-templates)을 참조하세요. | | `handoff_description` | 아니요 | 이 에이전트가 핸드오프 대상으로 제공될 때 노출되는 짧은 설명입니다. | -| `handoffs` | 아니요 | 대화를 전문 에이전트에 위임합니다. [핸드오프](handoffs.md)를 참조하세요. | +| `handoffs` | 아니요 | 대화를 전문 에이전트에게 위임합니다. [핸드오프](handoffs.md)를 참조하세요. | | `model` | 아니요 | 사용할 LLM입니다. [모델](models/index.md)을 참조하세요. | -| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice` 같은 모델 튜닝 매개변수입니다. | +| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice`와 같은 모델 튜닝 매개변수입니다. | | `tools` | 아니요 | 에이전트가 호출할 수 있는 도구입니다. [도구](tools.md)를 참조하세요. | | `mcp_servers` | 아니요 | 에이전트를 위한 MCP 기반 도구입니다. [MCP 가이드](mcp.md)를 참조하세요. | -| `mcp_config` | 아니요 | 엄격한 스키마 변환 및 MCP 실패 형식화와 같이 MCP 도구가 준비되는 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration)를 참조하세요. | -| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 사용자 입력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. | -| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. | -| `output_type` | 아니요 | 일반 텍스트 대신 structured outputs 타입입니다. [출력 타입](#output-types)을 참조하세요. | -| `hooks` | 아니요 | 에이전트 범위의 라이프사이클 콜백입니다. [라이프사이클 이벤트(훅)](#lifecycle-events-hooks)을 참조하세요. | -| `tool_use_behavior` | 아니요 | 도구 결과가 모델로 다시 전달될지, 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior)을 참조하세요. | -| `reset_tool_choice` | 아니요 | 도구 사용 루프를 피하기 위해 도구 호출 후 `tool_choice`를 재설정합니다(기본값: `True`). [도구 사용 강제](#forcing-tool-use)를 참조하세요. | +| `mcp_config` | 아니요 | 엄격한 스키마 변환, MCP 실패 포매팅 등 MCP 도구가 준비되는 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration)를 참조하세요. | +| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 번째 사용자 입력에 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. | +| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. | +| `output_type` | 아니요 | 일반 텍스트 대신 사용할 구조화된 출력 타입입니다. [출력 타입](#output-types)을 참조하세요. | +| `hooks` | 아니요 | 에이전트 범위의 수명 주기 콜백입니다. [수명 주기 이벤트(훅)](#lifecycle-events-hooks)을 참조하세요. | +| `tool_use_behavior` | 아니요 | 도구 결과를 모델로 다시 보낼지, 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior)을 참조하세요. | +| `reset_tool_choice` | 아니요 | 도구 사용 루프를 방지하기 위해 도구 호출 후 `tool_choice`를 재설정합니다(기본값: `True`). [도구 사용 강제](#forcing-tool-use)를 참조하세요. | ```python from agents import Agent, ModelSettings, function_tool @@ -64,17 +64,17 @@ agent = Agent( ) ``` -이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 동일한 아이디어를 기반으로 하며, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [샌드박스 에이전트 개념](sandbox/guide.md)을 참조하세요. +이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 같은 아이디어를 기반으로 하며, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [샌드박스 에이전트 개념](sandbox/guide.md)을 참조하세요. ## 프롬프트 템플릿 -`prompt`를 설정하여 OpenAI 플랫폼에서 생성한 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 작동합니다. +`prompt`를 설정하여 OpenAI 플랫폼에서 만든 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 동작합니다. 사용하려면 다음을 수행하세요. 1. https://platform.openai.com/playground/prompts 로 이동합니다 2. 새 프롬프트 변수 `poem_style`을 만듭니다. -3. 다음 내용으로 시스템 프롬프트를 만듭니다. +3. 다음 콘텐츠로 시스템 프롬프트를 만듭니다. ``` Write a poem in {{poem_style}} @@ -127,9 +127,9 @@ result = await Runner.run( ## 컨텍스트 -에이전트는 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다. 사용자가 생성하여 `Runner.run()`에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되고, 에이전트 실행을 위한 의존성과 상태를 담는 모음 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다. +에이전트는 자체 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다. 사용자가 만들어 `Runner.run()`에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되고 에이전트 실행에 필요한 의존성과 상태를 담는 컨테이너 역할을 합니다. 어떤 Python 객체든 컨텍스트로 제공할 수 있습니다. -전체 `RunContextWrapper` 표면, 공유 사용량 추적, 중첩된 `tool_input`, 직렬화 시 주의 사항은 [컨텍스트 가이드](context.md)를 읽어보세요. +전체 `RunContextWrapper` 인터페이스, 공유 사용량 추적, 중첩된 `tool_input`, 직렬화 관련 주의 사항은 [컨텍스트 가이드](context.md)를 읽어보세요. ```python @dataclass @@ -148,7 +148,7 @@ agent = Agent[UserContext]( ## 출력 타입 -기본적으로 에이전트는 일반 텍스트(즉 `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 래핑할 수 있는 모든 타입을 지원합니다. dataclasses, lists, TypedDict 등이 포함됩니다. +기본적으로 에이전트는 일반 텍스트(즉, `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 감쌀 수 있는 모든 타입(dataclasses, lists, TypedDict 등)을 지원합니다. ```python from pydantic import BaseModel @@ -169,20 +169,20 @@ agent = Agent( !!! note - `output_type`을 전달하면, 이는 모델에 일반 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하라고 지시합니다. + `output_type`을 전달하면 모델에 일반적인 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하라고 지시하는 것입니다. ## 멀티 에이전트 시스템 설계 패턴 -멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 폭넓게 적용 가능한 두 가지 패턴을 자주 볼 수 있습니다. +멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 널리 적용 가능한 두 가지 패턴을 자주 볼 수 있습니다. -1. 매니저(Agents as tools): 중앙 매니저/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화 제어를 유지합니다. -2. 핸드오프: 동등한 에이전트가 대화 제어를 이를 이어받는 전문 에이전트에게 넘깁니다. 이는 분산형 방식입니다. +1. 관리자(agents as tools): 중앙 관리자/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화에 대한 제어를 유지합니다. +2. 핸드오프: 동등한 에이전트가 대화를 이어받는 전문 에이전트에게 제어를 핸드오프합니다. 이는 분산형 방식입니다. 자세한 내용은 [에이전트 구축을 위한 실용 가이드](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)를 참조하세요. -### 매니저(Agents as tools) +### 관리자(agents as tools) -`customer_facing_agent`는 모든 사용자 상호작용을 처리하고, 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 읽어보세요. +`customer_facing_agent`는 사용자와의 모든 상호작용을 처리하고 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 읽어보세요. ```python from agents import Agent @@ -232,7 +232,7 @@ triage_agent = Agent( ## 동적 instructions -대부분의 경우 에이전트를 만들 때 instructions를 제공할 수 있습니다. 그러나 함수를 통해 동적 instructions를 제공할 수도 있습니다. 함수는 에이전트와 컨텍스트를 받으며 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수가 모두 허용됩니다. +대부분의 경우 에이전트를 만들 때 instructions를 제공할 수 있습니다. 하지만 함수를 통해 동적 instructions를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 받고 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수 모두 허용됩니다. ```python def dynamic_instructions( @@ -247,29 +247,29 @@ agent = Agent[UserContext]( ) ``` -## 라이프사이클 이벤트(훅) +## 수명 주기 이벤트(훅) -때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어 특정 이벤트가 발생할 때 이벤트를 로깅하거나, 데이터를 미리 가져오거나, 사용량을 기록할 수 있습니다. +때로는 에이전트의 수명 주기를 관찰하고 싶을 수 있습니다. 예를 들어 특정 이벤트가 발생할 때 이벤트를 로깅하거나, 데이터를 미리 가져오거나, 사용량을 기록하고 싶을 수 있습니다. -두 가지 훅 범위가 있습니다. +훅 범위는 두 가지입니다. - [`RunHooks`][agents.lifecycle.RunHooks]는 다른 에이전트로의 핸드오프를 포함하여 전체 `Runner.run(...)` 호출을 관찰합니다. - [`AgentHooks`][agents.lifecycle.AgentHooks]는 `agent.hooks`를 통해 특정 에이전트 인스턴스에 연결됩니다. 콜백 컨텍스트도 이벤트에 따라 달라집니다. -- 에이전트 시작/종료 훅은 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받으며, 이는 원래 컨텍스트를 래핑하고 공유 실행 사용량 상태를 포함합니다. +- 에이전트 시작/종료 훅은 원래 컨텍스트를 감싸고 공유 실행 사용량 상태를 전달하는 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받습니다. - LLM, 도구, 핸드오프 훅은 [`RunContextWrapper`][agents.run_context.RunContextWrapper]를 받습니다. 일반적인 훅 타이밍은 다음과 같습니다. -- `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 완료할 때입니다. -- `on_llm_start` / `on_llm_end`: 각 모델 호출의 바로 전후입니다. -- `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출의 전후입니다. - 함수 도구의 경우 훅 `context`는 일반적으로 `ToolContext`이므로 `tool_call_id` 같은 도구 호출 메타데이터를 검사할 수 있습니다. -- `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때입니다. +- `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 완료할 때 +- `on_llm_start` / `on_llm_end`: 각 모델 호출 직전과 직후 +- `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출 전후 + 함수 도구의 경우, 훅 `context`는 일반적으로 `ToolContext`이므로 `tool_call_id`와 같은 도구 호출 메타데이터를 검사할 수 있습니다. +- `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때 -전체 워크플로를 위한 단일 관찰자가 필요하면 `RunHooks`를 사용하고, 한 에이전트에 사용자 지정 부수 효과가 필요하면 `AgentHooks`를 사용하세요. +전체 워크플로를 위한 단일 관찰자가 필요할 때는 `RunHooks`를 사용하고, 한 에이전트에 사용자 지정 사이드 이펙트가 필요할 때는 `AgentHooks`를 사용하세요. ```python from agents import Agent, RunHooks, Runner @@ -291,15 +291,15 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks()) print(result.final_output) ``` -전체 콜백 표면은 [라이프사이클 API 참조](ref/lifecycle.md)를 참조하세요. +전체 콜백 인터페이스는 [수명 주기 API 참조](ref/lifecycle.md)를 참조하세요. ## 가드레일 -가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대해 병렬로 검사/검증을 실행하고, 에이전트 출력이 생성된 후 그 출력에 대해서도 검사/검증을 실행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 검사할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 읽어보세요. +가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대한 검사/검증을 병렬로 실행하고, 에이전트 출력이 생성된 후 그 출력에 대해서도 검사/검증을 실행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 선별할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 읽어보세요. ## 에이전트 복제/복사 -에이전트의 `clone()` 메서드를 사용하면 Agent를 복제하고, 원하는 속성을 선택적으로 변경할 수 있습니다. +에이전트에서 `clone()` 메서드를 사용하면 에이전트를 복제하고, 선택적으로 원하는 속성을 변경할 수 있습니다. ```python pirate_agent = Agent( @@ -318,12 +318,12 @@ robot_agent = pirate_agent.clone( 도구 목록을 제공한다고 해서 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이 해당 특정 도구를 사용하도록 요구합니다. -OpenAI Responses 도구 검색을 사용하는 경우 명명된 도구 선택은 더 제한됩니다. `tool_choice`로 단순 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없으며, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 지정하지 않습니다. 이러한 경우에는 `auto` 또는 `required`를 선호하세요. Responses 관련 제약 조건은 [호스티드 도구 검색](tools.md#hosted-tool-search)을 참조하세요. +OpenAI Responses 도구 검색을 사용하는 경우, 이름이 지정된 도구 선택은 더 제한됩니다. `tool_choice`로 순수 네임스페이스 이름이나 deferred 전용 도구를 대상으로 지정할 수 없으며, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 하지 않습니다. 이러한 경우 `auto` 또는 `required`를 권장합니다. Responses 고유의 제약 사항은 [호스티드 툴 검색](tools.md#hosted-tool-search)을 참조하세요. ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -346,7 +346,7 @@ agent = Agent( `Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력이 처리되는 방식을 제어합니다. - `"run_llm_again"`: 기본값입니다. 도구가 실행되고, LLM이 결과를 처리하여 최종 응답을 생성합니다. -- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력이 추가 LLM 처리 없이 최종 응답으로 사용됩니다. +- `"stop_on_first_tool"`: 추가 LLM 처리 없이 첫 번째 도구 호출의 출력이 최종 응답으로 사용됩니다. ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -364,7 +364,7 @@ agent = Agent( ) ``` -- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고, 그 출력을 최종 응답으로 사용합니다. +- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고, 해당 출력을 최종 응답으로 사용합니다. ```python from agents import Agent, Runner, function_tool @@ -426,4 +426,4 @@ agent = Agent( !!! note - 무한 루프를 방지하기 위해, 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]를 통해 구성할 수 있습니다. 무한 루프가 발생하는 이유는 도구 결과가 LLM으로 전송되고, 그러면 LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 일이 무한히 반복되기 때문입니다. \ No newline at end of file + 무한 루프를 방지하기 위해 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]를 통해 구성할 수 있습니다. 무한 루프가 발생하는 이유는 도구 결과가 LLM으로 전송되고, LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 과정이 끝없이 반복되기 때문입니다. \ No newline at end of file diff --git a/docs/ko/config.md b/docs/ko/config.md index 93aeee967e..b7fe16f1b6 100644 --- a/docs/ko/config.md +++ b/docs/ko/config.md @@ -4,21 +4,21 @@ search: --- # 구성 -이 페이지에서는 기본 OpenAI 키 또는 클라이언트, 기본 OpenAI API 형태, 트레이싱 내보내기 기본값, 로깅 동작처럼 보통 애플리케이션 시작 시 한 번 설정하는 SDK 전역 기본값을 다룹니다 +이 페이지에서는 기본 OpenAI 키 또는 클라이언트, 기본 OpenAI API 형태, 트레이싱 내보내기 기본값, 로깅 동작처럼 일반적으로 애플리케이션 시작 시 한 번 설정하는 SDK 전체 기본값을 다룹니다. -이러한 기본값은 샌드박스 기반 워크플로에도 계속 적용되지만, 샌드박스 워크스페이스, 샌드박스 클라이언트, 세션 재사용은 별도로 구성합니다 +이러한 기본값은 샌드박스 기반 워크플로에도 계속 적용되지만, 샌드박스 워크스페이스, 샌드박스 클라이언트, 세션 재사용은 별도로 구성합니다. -대신 특정 에이전트 또는 실행을 구성해야 한다면, 다음부터 시작하세요: +대신 특정 에이전트 또는 실행을 구성해야 한다면 다음부터 시작하세요. -- 일반 `Agent`의 instructions, tools, 출력 타입, 핸드오프, 가드레일은 [Agents](agents.md) +- 일반 `Agent`의 instructions, tools, 출력 유형, 핸드오프, 가드레일은 [에이전트](agents.md) - `RunConfig`, 세션, 대화 상태 옵션은 [에이전트 실행](running_agents.md) -- `SandboxRunConfig`, 매니페스트, 기능, 샌드박스 클라이언트 전용 워크스페이스 설정은 [샌드박스 에이전트](sandbox/guide.md) -- 모델 선택 및 프로바이더 구성은 [모델](models/index.md) -- 실행별 트레이싱 메타데이터와 사용자 지정 트레이스 프로세서는 [트레이싱](tracing.md) +- `SandboxRunConfig`, 매니페스트, 기능, 샌드박스 클라이언트별 워크스페이스 설정은 [샌드박스 에이전트](sandbox/guide.md) +- 모델 선택 및 공급자 구성은 [모델](models/index.md) +- 실행별 트레이싱 메타데이터 및 사용자 지정 트레이스 프로세서는 [트레이싱](tracing.md) -## API 키와 클라이언트 +## API 키 및 클라이언트 -기본적으로 SDK는 LLM 요청과 트레이싱에 `OPENAI_API_KEY` 환경 변수를 사용합니다. 이 키는 SDK가 처음 OpenAI 클라이언트를 생성할 때(지연 초기화) 확인되므로, 첫 모델 호출 전에 환경 변수를 설정하세요. 앱 시작 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다. +기본적으로 SDK는 LLM 요청과 트레이싱에 `OPENAI_API_KEY` 환경 변수를 사용합니다. 키는 SDK가 처음 OpenAI 클라이언트를 생성할 때 확인되므로(지연 초기화), 첫 모델 호출 전에 환경 변수를 설정하세요. 앱이 시작되기 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다. ```python from agents import set_default_openai_key @@ -26,7 +26,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용해 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다. +또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용하여 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다. ```python from openai import AsyncOpenAI @@ -36,14 +36,14 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -환경 기반 엔드포인트 구성을 선호한다면, 기본 OpenAI 프로바이더는 `OPENAI_BASE_URL`도 읽습니다. Responses websocket 전송을 활성화하면 websocket `/responses` 엔드포인트에 `OPENAI_WEBSOCKET_BASE_URL`도 읽습니다. +환경 기반 엔드포인트 구성을 선호한다면 기본 OpenAI 공급자는 `OPENAI_BASE_URL`도 읽습니다. Responses 웹소켓 전송을 활성화하면 웹소켓 `/responses` 엔드포인트에 대해 `OPENAI_WEBSOCKET_BASE_URL`도 읽습니다. ```bash export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1" export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1" ``` -마지막으로, 사용되는 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 @@ -53,7 +53,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 @@ -61,7 +61,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -모델 트래픽은 하나의 키 또는 클라이언트를 사용하지만 트레이싱은 다른 OpenAI 키를 사용해야 한다면, 기본 키 또는 클라이언트를 설정할 때 `use_for_tracing=False`를 전달한 다음 트레이싱을 별도로 구성하세요. 사용자 지정 클라이언트를 사용하지 않는 경우 [`set_default_openai_key()`][agents.set_default_openai_key]에도 같은 패턴을 적용할 수 있습니다. +모델 트래픽은 하나의 키 또는 클라이언트를 사용하지만 트레이싱에는 다른 OpenAI 키를 사용해야 한다면, 기본 키 또는 클라이언트를 설정할 때 `use_for_tracing=False`를 전달한 다음 트레이싱을 별도로 구성하세요. 사용자 지정 클라이언트를 사용하지 않는 경우에도 [`set_default_openai_key()`][agents.set_default_openai_key]로 동일한 패턴을 사용할 수 있습니다. ```python from openai import AsyncOpenAI @@ -76,7 +76,7 @@ set_default_openai_client(custom_client, use_for_tracing=False) set_tracing_export_api_key("sk-tracing") ``` -기본 내보내기를 사용할 때 트레이스를 특정 조직 또는 프로젝트에 귀속해야 한다면, 앱 시작 전에 다음 환경 변수를 설정하세요: +기본 내보내기를 사용할 때 트레이스를 특정 조직 또는 프로젝트에 귀속해야 한다면 앱이 시작되기 전에 다음 환경 변수를 설정하세요. ```bash export OPENAI_ORG_ID="org_..." @@ -103,7 +103,7 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -트레이싱은 활성화한 채로 유지하되 트레이스 페이로드에서 잠재적으로 민감한 입력/출력을 제외하려면 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 `False`로 설정하세요: +트레이싱은 활성화한 상태로 유지하되 트레이스 페이로드에서 민감할 수 있는 입력/출력을 제외하려면 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 `False`로 설정하세요. ```python from agents import Runner, RunConfig @@ -115,19 +115,19 @@ await Runner.run( ) ``` -코드 없이 기본값을 변경하려면 앱 시작 전에 이 환경 변수를 설정할 수도 있습니다: +앱이 시작되기 전에 다음 환경 변수를 설정하여 코드 없이 기본값을 변경할 수도 있습니다. ```bash export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0 ``` -전체 트레이싱 제어는 [트레이싱 가이드](tracing.md)를 참고하세요. +전체 트레이싱 제어는 [트레이싱 가이드](tracing.md)를 참조하세요. ## 디버그 로깅 -SDK는 두 개의 Python 로거(`openai.agents` 및 `openai.agents.tracing`)를 정의하며 기본적으로 핸들러를 연결하지 않습니다. 로그는 애플리케이션의 Python 로깅 구성 설정을 따릅니다. +SDK는 두 개의 Python 로거(`openai.agents` 및 `openai.agents.tracing`)를 정의하며 기본적으로 핸들러를 연결하지 않습니다. 로그는 애플리케이션의 Python 로깅 구성을 따릅니다. -상세 로깅을 활성화하려면 [`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 @@ -135,7 +135,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -또는 핸들러, 필터, 포매터 등을 추가해 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. +또는 핸들러, 필터, 포매터 등을 추가하여 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요. ```python import logging @@ -156,16 +156,16 @@ logger.addHandler(logging.StreamHandler()) ### 로그의 민감한 데이터 -일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. +특정 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다. -기본적으로 SDK는 LLM 입력/출력이나 도구 입력/출력을 로깅하지 **않습니다**. 이러한 보호는 다음으로 제어됩니다: +기본적으로 SDK는 LLM 입력/출력 또는 도구 입력/출력을 로깅하지 **않습니다**. 이러한 보호는 다음으로 제어됩니다. ```bash OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 ``` -디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱 시작 전에 변수 중 하나를 `0`(또는 `false`)으로 설정하세요: +디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱이 시작되기 전에 두 변수 중 하나를 `0`(또는 `false`)으로 설정하세요. ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0 diff --git a/docs/ko/context.md b/docs/ko/context.md index cb403c0b8c..b86aa44c2b 100644 --- a/docs/ko/context.md +++ b/docs/ko/context.md @@ -4,49 +4,49 @@ search: --- # 컨텍스트 관리 -컨텍스트는 중의적으로 사용되는 용어입니다. 보통 신경 써야 할 컨텍스트는 두 가지 주요 범주가 있습니다 +컨텍스트는 여러 의미로 쓰이는 용어입니다. 주로 고려해야 할 컨텍스트에는 두 가지 주요 유형이 있습니다. -1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수 실행 시, `on_handoff` 같은 콜백, 라이프사이클 훅 등에서 필요할 수 있는 데이터와 의존성입니다 -2. LLM에서 사용할 수 있는 컨텍스트: LLM이 응답을 생성할 때 보는 데이터입니다 +1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수가 실행될 때, `on_handoff` 같은 콜백 중에, 생명주기 훅 등에서 필요할 수 있는 데이터와 의존성입니다. +2. LLM이 사용할 수 있는 컨텍스트: LLM이 응답을 생성할 때 보는 데이터입니다. ## 로컬 컨텍스트 -이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 동작 방식은 다음과 같습니다 +이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 작동 방식은 다음과 같습니다. -1. 원하는 Python 객체를 생성합니다. 일반적으로 dataclass 또는 Pydantic 객체를 사용합니다 -2. 해당 객체를 다양한 run 메서드에 전달합니다(예: `Runner.run(..., context=whatever)`) -3. 모든 도구 호출, 라이프사이클 훅 등은 `RunContextWrapper[T]` 래퍼 객체를 전달받으며, 여기서 `T`는 `wrapper.context`로 접근 가능한 컨텍스트 객체 타입입니다 +1. 원하는 Python 객체를 만듭니다. 일반적인 패턴은 dataclass나 Pydantic 객체를 사용하는 것입니다. +2. 해당 객체를 다양한 run 메서드에 전달합니다(예: `Runner.run(..., context=whatever)`). +3. 모든 도구 호출, 생명주기 훅 등에는 래퍼 객체인 `RunContextWrapper[T]`가 전달되며, 여기서 `T`는 `wrapper.context`를 통해 접근할 수 있는 컨텍스트 객체 타입을 나타냅니다. -일부 런타임 전용 콜백에서는 SDK가 `RunContextWrapper[T]`의 더 특화된 하위 클래스를 전달할 수 있습니다. 예를 들어, 함수 도구 라이프사이클 훅은 보통 `ToolContext`를 받으며, 이는 `tool_call_id`, `tool_name`, `tool_arguments` 같은 도구 호출 메타데이터도 제공합니다 +일부 런타임별 콜백의 경우 SDK가 `RunContextWrapper[T]`의 더 특화된 서브클래스를 전달할 수 있습니다. 예를 들어 함수 도구 생명주기 훅은 일반적으로 `ToolContext`를 받으며, 이는 `tool_call_id`, `tool_name`, `tool_arguments` 같은 도구 호출 메타데이터도 노출합니다. -가장 **중요한** 점은 다음과 같습니다: 특정 에이전트 실행에서 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 컨텍스트 _타입_ 을 사용해야 합니다 +알아두어야 할 **가장 중요한** 점은 특정 에이전트 실행에 포함되는 모든 에이전트, 도구 함수, 생명주기 등은 동일한 컨텍스트 _타입_을 사용해야 한다는 것입니다. -컨텍스트는 다음과 같은 용도로 사용할 수 있습니다 +컨텍스트는 다음과 같은 용도로 사용할 수 있습니다. -- 실행에 대한 맥락 데이터(예: 사용자 이름/uid 또는 사용자에 관한 기타 정보) -- 의존성(예: logger 객체, 데이터 fetcher 등) -- 헬퍼 함수 +- 실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 또는 사용자에 대한 기타 정보) +- 의존성(예: 로거 객체, 데이터 페처 등) +- 헬퍼 함수 !!! danger "참고" - 컨텍스트 객체는 LLM으로 전송되지 **않습니다**. 이는 순수하게 로컬 객체이며, 읽고 쓰고 메서드를 호출할 수 있습니다 + 컨텍스트 객체는 LLM으로 전송되지 **않습니다**. 이는 오직 로컬 객체이며, 읽고 쓰거나 해당 객체의 메서드를 호출할 수 있습니다. -단일 run 내에서 파생 래퍼는 동일한 기본 앱 컨텍스트, 승인 상태, 사용량 추적을 공유합니다. 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] run은 다른 `tool_input`을 연결할 수 있지만, 기본적으로 앱 상태의 격리된 복사본을 받지는 않습니다 +단일 실행 내에서 파생된 래퍼들은 동일한 기본 앱 컨텍스트, 승인 상태, 사용량 추적을 공유합니다. 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행은 다른 `tool_input`을 붙일 수 있지만, 기본적으로 앱 상태의 격리된 복사본을 받지는 않습니다. -### `RunContextWrapper` 노출 항목 +### `RunContextWrapper`의 노출 항목 -[`RunContextWrapper`][agents.run_context.RunContextWrapper]는 앱에서 정의한 컨텍스트 객체를 감싸는 래퍼입니다. 실제로는 주로 다음을 사용합니다 +[`RunContextWrapper`][agents.run_context.RunContextWrapper]는 앱에서 정의한 컨텍스트 객체를 감싸는 래퍼입니다. 실제로는 대부분 다음을 사용하게 됩니다. -- 자체 변경 가능한 앱 상태와 의존성을 위한 [`wrapper.context`][agents.run_context.RunContextWrapper.context] -- 현재 run 전체의 요청/토큰 사용량 집계를 위한 [`wrapper.usage`][agents.run_context.RunContextWrapper.usage] -- 현재 run이 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 내부에서 실행 중일 때 구조화된 입력을 위한 [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input] -- 승인 상태를 프로그래밍 방식으로 업데이트해야 할 때 [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool] +- [`wrapper.context`][agents.run_context.RunContextWrapper.context]: 직접 사용하는 변경 가능한 앱 상태와 의존성 +- [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]: 현재 실행 전반의 집계된 요청 및 토큰 사용량 +- [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]: 현재 실행이 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 안에서 실행 중일 때의 구조화된 입력 +- [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]: 승인 상태를 프로그래밍 방식으로 업데이트해야 할 때 사용 -`wrapper.context`만 앱에서 정의한 객체입니다. 나머지 필드는 SDK가 관리하는 런타임 메타데이터입니다 +`wrapper.context`만 앱에서 정의한 객체입니다. 다른 필드는 SDK가 관리하는 런타임 메타데이터입니다. -나중에 휴먼인더루프 (HITL) 또는 내구성 있는 작업 워크플로를 위해 [`RunState`][agents.run_state.RunState]를 직렬화하면, 해당 런타임 메타데이터도 상태와 함께 저장됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 비밀 정보를 넣지 마세요 +나중에 휴먼인더루프 (HITL) 또는 내구성 있는 작업 워크플로를 위해 [`RunState`][agents.run_state.RunState]를 직렬화하면, 해당 런타임 메타데이터가 상태와 함께 저장됩니다. 직렬화된 상태를 영속화하거나 전송할 계획이라면 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 비밀 정보를 넣지 마세요. -대화 상태는 별도의 관심사입니다. 턴을 어떻게 이어갈지에 따라 `result.to_input_list()`, `session`, `conversation_id`, 또는 `previous_response_id`를 사용하세요. 이 결정은 [결과](results.md), [에이전트 실행](running_agents.md), [세션](sessions/index.md)을 참고하세요 +대화 상태는 별개의 문제입니다. 턴을 이어가는 방식에 따라 `result.to_input_list()`, `session`, `conversation_id`, 또는 `previous_response_id`를 사용하세요. 이 결정에 대해서는 [결과](results.md), [에이전트 실행](running_agents.md), [세션](sessions/index.md)을 참고하세요. ```python import asyncio @@ -85,18 +85,18 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만 어떤 타입이든 사용할 수 있습니다 -2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 값을 읽습니다 -3. 타입 체커가 오류를 잡을 수 있도록(예: 다른 컨텍스트 타입을 받는 도구를 전달하려는 경우) 에이전트에 제네릭 `UserInfo`를 표시합니다 -4. 컨텍스트는 `run` 함수에 전달됩니다 -5. 에이전트가 도구를 올바르게 호출하고 나이를 가져옵니다 +1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만, 어떤 타입이든 사용할 수 있습니다. +2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다. +3. 에이전트에 제네릭 `UserInfo`를 표시하여, 타입 검사기가 오류를 잡을 수 있도록 합니다(예를 들어 다른 컨텍스트 타입을 받는 도구를 전달하려고 한 경우). +4. 컨텍스트가 `run` 함수에 전달됩니다. +5. 에이전트가 도구를 올바르게 호출하고 나이를 가져옵니다. --- ### 고급: `ToolContext` -경우에 따라 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원시 인자 문자열)에 접근하고 싶을 수 있습니다 -이때는 `RunContextWrapper`를 확장한 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다 +어떤 경우에는 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원문 인수 문자열)에 접근하고 싶을 수 있습니다. +이를 위해 `RunContextWrapper`를 확장하는 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다. ```python from typing import Annotated @@ -124,25 +124,25 @@ agent = Agent( ) ``` -`ToolContext`는 `RunContextWrapper`와 동일한 `.context` 속성을 제공하며 -현재 도구 호출에 특화된 추가 필드도 제공합니다 +`ToolContext`는 `RunContextWrapper`와 동일한 `.context` 속성을 제공하며, +현재 도구 호출에 특화된 추가 필드도 제공합니다. - `tool_name` – 호출되는 도구의 이름 - `tool_call_id` – 이 도구 호출의 고유 식별자 -- `tool_arguments` – 도구에 전달된 원시 인자 문자열 -- `tool_namespace` – 도구가 `tool_namespace()` 또는 다른 네임스페이스 표면을 통해 로드된 경우, 도구 호출의 Responses 네임스페이스 -- `qualified_tool_name` – 네임스페이스가 있을 때 네임스페이스가 포함된 도구 이름 +- `tool_arguments` – 도구에 전달된 원문 인수 문자열 +- `tool_namespace` – 도구가 `tool_namespace()` 또는 다른 네임스페이스가 지정된 표면을 통해 로드된 경우, 도구 호출의 Responses 네임스페이스 +- `qualified_tool_name` – 네임스페이스가 있을 때 해당 네임스페이스로 한정된 도구 이름 -실행 중 도구 수준 메타데이터가 필요할 때 `ToolContext`를 사용하세요 -에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper`로 충분합니다. `ToolContext`는 `RunContextWrapper`를 확장하므로, 중첩된 `Agent.as_tool()` run이 구조화된 입력을 제공한 경우 `.tool_input`도 노출할 수 있습니다 +실행 중에 도구 수준 메타데이터가 필요할 때 `ToolContext`를 사용하세요. +에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper`로 충분합니다. `ToolContext`는 `RunContextWrapper`를 확장하므로, 중첩된 `Agent.as_tool()` 실행이 구조화된 입력을 제공한 경우 `.tool_input`도 노출할 수 있습니다. --- ## 에이전트/LLM 컨텍스트 -LLM이 호출될 때 LLM이 볼 수 있는 데이터는 대화 기록뿐입니다. 즉, LLM에서 새로운 데이터를 사용할 수 있게 하려면 해당 기록에서 접근 가능하도록 만들어야 합니다. 방법은 몇 가지가 있습니다 +LLM이 호출될 때 LLM이 볼 수 있는 **유일한** 데이터는 대화 기록에 있는 데이터입니다. 즉, LLM이 어떤 새 데이터를 사용할 수 있게 하려면 해당 기록에서 사용할 수 있는 방식으로 제공해야 합니다. 이를 수행하는 방법은 몇 가지가 있습니다. -1. Agent `instructions`에 추가할 수 있습니다. 이는 "시스템 프롬프트" 또는 "개발자 메시지"라고도 합니다. 시스템 프롬프트는 정적 문자열일 수도 있고, 컨텍스트를 받아 문자열을 출력하는 동적 함수일 수도 있습니다. 이는 항상 유용한 정보(예: 사용자 이름 또는 현재 날짜)에 자주 쓰이는 방법입니다 -2. `Runner.run` 함수를 호출할 때 `input`에 추가합니다. 이는 `instructions` 방식과 유사하지만, [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 우선순위의 메시지를 둘 수 있게 해줍니다 -3. 함수 도구를 통해 노출합니다. 이는 _온디맨드_ 컨텍스트에 유용합니다. LLM이 어떤 데이터가 필요할 때를 스스로 결정하고, 그 데이터를 가져오기 위해 도구를 호출할 수 있습니다 -4. retrieval 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스(retrieval), 또는 웹(웹 검색)에서 관련 데이터를 가져올 수 있는 특수 도구입니다. 이는 관련 컨텍스트 데이터에 응답을 "grounding"하는 데 유용합니다 \ No newline at end of file +1. Agent `instructions`에 추가할 수 있습니다. 이는 "시스템 프롬프트" 또는 "개발자 메시지"라고도 합니다. 시스템 프롬프트는 정적 문자열일 수도 있고, 컨텍스트를 받아 문자열을 출력하는 동적 함수일 수도 있습니다. 이는 항상 유용한 정보(예: 사용자의 이름 또는 현재 날짜)에 흔히 사용하는 전략입니다. +2. `Runner.run` 함수를 호출할 때 `input`에 추가합니다. 이는 `instructions` 전략과 유사하지만, [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 위치의 메시지를 사용할 수 있게 해줍니다. +3. 함수 도구를 통해 노출합니다. 이는 _온디맨드_ 컨텍스트에 유용합니다. LLM이 어떤 데이터가 필요한 시점을 결정하고, 해당 데이터를 가져오기 위해 도구를 호출할 수 있습니다. +4. 검색 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져올 수 있는 특수 도구(검색) 또는 웹에서 가져올 수 있는 특수 도구(웹 검색)입니다. 이는 응답을 관련 컨텍스트 데이터에 "근거화"하는 데 유용합니다. \ No newline at end of file diff --git a/docs/ko/examples.md b/docs/ko/examples.md index 7718043d15..7807e02a61 100644 --- a/docs/ko/examples.md +++ b/docs/ko/examples.md @@ -2,74 +2,74 @@ search: exclude: true --- -# 코드 예제 +# 예제 -[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. examples는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다. +SDK의 다양한 샘플 구현은 [리포지토리](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 확인하세요. 예제는 여러 카테고리로 구성되어 있으며, 각기 다른 패턴과 기능을 보여 줍니다. ## 카테고리 - **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):** - 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다 + 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여 줍니다 - 결정론적 워크플로 - Agents as tools - - 스트리밍 이벤트를 포함한 Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`) - - 구조화된 입력 매개변수를 포함한 Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`) + - 스트리밍 이벤트를 사용하는 Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`) + - 구조화된 입력 매개변수를 사용하는 Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`) - 병렬 에이전트 실행 - 조건부 도구 사용 - - 서로 다른 동작으로 도구 사용 강제 (`examples/agent_patterns/forcing_tool_use.py`) + - 다양한 동작으로 도구 사용 강제 (`examples/agent_patterns/forcing_tool_use.py`) - 입출력 가드레일 - - 심판 역할의 LLM + - 평가자로서의 LLM - 라우팅 - 스트리밍 가드레일 - 도구 승인 및 상태 직렬화를 포함한 휴먼인더루프 (HITL) (`examples/agent_patterns/human_in_the_loop.py`) - 스트리밍을 포함한 휴먼인더루프 (HITL) (`examples/agent_patterns/human_in_the_loop_stream.py`) - - 승인 플로를 위한 사용자 지정 거절 메시지 (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`) + - 승인 흐름을 위한 사용자 지정 거부 메시지 (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`) - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 이 예제들은 다음과 같은 SDK의 기본 기능을 보여줍니다 + 이 예제는 다음과 같은 SDK의 기본 기능을 보여 줍니다 - - Hello World 예제 (기본 모델, GPT-5, 오픈 웨이트 모델) - - 에이전트 라이프사이클 관리 - - 실행 훅 및 에이전트 훅 라이프사이클 예제 (`examples/basic/lifecycle_example.py`) + - Hello world 예제(기본 모델, GPT-5, open-weight 모델) + - 에이전트 수명 주기 관리 + - 실행 훅 및 에이전트 훅 수명 주기 예제 (`examples/basic/lifecycle_example.py`) - 동적 시스템 프롬프트 - 기본 도구 사용 (`examples/basic/tools.py`) - 도구 입출력 가드레일 (`examples/basic/tool_guardrails.py`) - 이미지 도구 출력 (`examples/basic/image_tool_output.py`) - - 스트리밍 출력 (텍스트, 항목, 함수 호출 인자) + - 스트리밍 출력(텍스트, 항목, 함수 호출 인수) - 턴 간 공유 세션 헬퍼를 사용하는 Responses websocket 전송 (`examples/basic/stream_ws.py`) - 프롬프트 템플릿 - - 파일 처리 (로컬 및 원격, 이미지 및 PDF) + - 파일 처리(로컬 및 원격, 이미지 및 PDF) - 사용량 추적 - - Runner 관리 재시도 설정 (`examples/basic/retry.py`) - - 서드파티 어댑터를 통한 Runner 관리 재시도 (`examples/basic/retry_litellm.py`) + - Runner가 관리하는 재시도 설정 (`examples/basic/retry.py`) + - 서드파티 어댑터를 통해 Runner가 관리하는 재시도 (`examples/basic/retry_litellm.py`) - 비엄격 출력 타입 - 이전 응답 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):** - 메시지 필터링을 포함한 에이전트 핸드오프의 실용적인 예제: + 메시지 필터링을 포함한 에이전트 핸드오프의 실제 예제입니다. 포함 항목: - 메시지 필터 예제 (`examples/handoffs/message_filter.py`) - 스트리밍을 포함한 메시지 필터 (`examples/handoffs/message_filter_streaming.py`) - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - OpenAI Responses API와 함께 호스티드 MCP (Model context protocol)를 사용하는 방법을 보여주는 예제: + OpenAI Responses API와 함께 호스티드 MCP (Model Context Protocol)를 사용하는 방법을 보여 주는 예제입니다. 포함 항목: - - 승인 없는 간단한 호스티드 MCP (`examples/hosted_mcp/simple.py`) - - Google Calendar 같은 MCP 커넥터 (`examples/hosted_mcp/connectors.py`) + - 승인이 없는 간단한 호스티드 MCP (`examples/hosted_mcp/simple.py`) + - Google Calendar와 같은 MCP 커넥터 (`examples/hosted_mcp/connectors.py`) - 인터럽션(중단 처리) 기반 승인을 포함한 휴먼인더루프 (HITL) (`examples/hosted_mcp/human_in_the_loop.py`) - - MCP 도구 호출용 승인 시 콜백 (`examples/hosted_mcp/on_approval.py`) + - MCP 도구 호출에 대한 승인 시 콜백 (`examples/hosted_mcp/on_approval.py`) - **[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) 예제 @@ -77,61 +77,61 @@ search: - Streamable HTTP 예제 - Streamable HTTP 원격 연결 (`examples/mcp/streamable_http_remote_example`) - Streamable HTTP용 사용자 지정 HTTP 클라이언트 팩토리 (`examples/mcp/streamablehttp_custom_client_example`) - - `MCPUtil.get_all_function_tools`를 사용한 모든 MCP 도구 프리패칭 (`examples/mcp/get_all_mcp_tools_example`) - - FastAPI를 사용하는 MCPServerManager (`examples/mcp/manager_example`) + - `MCPUtil.get_all_function_tools`를 사용한 모든 MCP 도구 사전 가져오기 (`examples/mcp/get_all_mcp_tools_example`) + - FastAPI와 함께 사용하는 MCPServerManager (`examples/mcp/manager_example`) - MCP 도구 필터링 (`examples/mcp/tool_filter_example`) - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 에이전트를 위한 다양한 메모리 구현 예제: - - - SQLite 세션 저장소 - - 고급 SQLite 세션 저장소 - - Redis 세션 저장소 - - SQLAlchemy 세션 저장소 - - Dapr 상태 저장소 세션 저장소 - - 암호화된 세션 저장소 - - OpenAI Conversations 세션 저장소 - - Responses 컴팩션 세션 저장소 - - `ModelSettings(store=False)`를 사용한 상태 비저장 Responses 컴팩션 (`examples/memory/compaction_session_stateless_example.py`) - - 파일 기반 세션 저장소 (`examples/memory/file_session.py`) + 에이전트용 다양한 메모리 구현 예제입니다. 포함 항목: + + - SQLite 세션 스토리지 + - 고급 SQLite 세션 스토리지 + - Redis 세션 스토리지 + - SQLAlchemy 세션 스토리지 + - Dapr 상태 저장소 세션 스토리지 + - 암호화된 세션 스토리지 + - OpenAI Conversations 세션 스토리지 + - Responses 압축 세션 스토리지 + - `ModelSettings(store=False)`를 사용한 무상태 Responses 압축 (`examples/memory/compaction_session_stateless_example.py`) + - 파일 기반 세션 스토리지 (`examples/memory/file_session.py`) - 휴먼인더루프 (HITL)를 포함한 파일 기반 세션 (`examples/memory/file_hitl_example.py`) - 휴먼인더루프 (HITL)를 포함한 SQLite 인메모리 세션 (`examples/memory/memory_session_hitl_example.py`) - 휴먼인더루프 (HITL)를 포함한 OpenAI Conversations 세션 (`examples/memory/openai_session_hitl_example.py`) - - 세션 전반의 HITL 승인/거절 시나리오 (`examples/memory/hitl_session_scenario.py`) + - 세션 간 HITL 승인/거부 시나리오 (`examples/memory/hitl_session_scenario.py`) - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 사용자 지정 프로바이더와 서드파티 어댑터를 포함해 SDK에서 OpenAI 이외 모델을 사용하는 방법을 살펴보세요 + 사용자 지정 제공자와 서드파티 어댑터를 포함하여 SDK에서 OpenAI가 아닌 모델을 사용하는 방법을 살펴봅니다. - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** - SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제: + SDK를 사용하여 실시간 경험을 빌드하는 방법을 보여 주는 예제입니다. 포함 항목: - 구조화된 텍스트 및 이미지 메시지를 사용하는 웹 애플리케이션 패턴 - - 커맨드라인 오디오 루프 및 재생 처리 + - 명령줄 오디오 루프 및 재생 처리 - WebSocket을 통한 Twilio Media Streams 통합 - - Realtime Calls API attach 플로를 사용하는 Twilio SIP 통합 + - Realtime Calls API attach flows를 사용하는 Twilio SIP 통합 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** - reasoning content를 다루는 방법을 보여주는 예제: + 추론 콘텐츠를 다루는 방법을 보여 주는 예제입니다. 포함 항목: - - Runner API의 reasoning content, 스트리밍 및 비스트리밍 (`examples/reasoning_content/runner_example.py`) - - OpenRouter를 통한 OSS 모델의 reasoning content (`examples/reasoning_content/gpt_oss_stream.py`) - - 기본 reasoning content 예제 (`examples/reasoning_content/main.py`) + - Runner API를 사용한 추론 콘텐츠, 스트리밍 및 비스트리밍 (`examples/reasoning_content/runner_example.py`) + - OpenRouter를 통한 OSS 모델의 추론 콘텐츠 (`examples/reasoning_content/gpt_oss_stream.py`) + - 기본 추론 콘텐츠 예제 (`examples/reasoning_content/main.py`) - **[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 호스트하는 도구 및 실험적 Codex 도구 기능을 구현하는 방법을 알아보세요: + 다음과 같은 OpenAI 호스트하는 도구와 실험적 Codex 도구 기능을 구현하는 방법을 알아봅니다: - - 웹 검색 및 필터를 포함한 웹 검색 + - 웹 검색 및 필터를 사용한 웹 검색 - 파일 검색 - - Code Interpreter + - Code interpreter - 파일 편집 및 승인을 포함한 패치 적용 도구 (`examples/tools/apply_patch.py`) - - 승인 콜백을 포함한 셸 도구 실행 (`examples/tools/shell.py`) + - 승인 콜백을 사용하는 셸 도구 실행 (`examples/tools/shell.py`) - 휴먼인더루프 (HITL) 인터럽션(중단 처리) 기반 승인을 포함한 셸 도구 (`examples/tools/shell_human_in_the_loop.py`) - - 인라인 스킬을 포함한 호스티드 컨테이너 셸 (`examples/tools/container_shell_inline_skill.py`) - - 스킬 참조를 포함한 호스티드 컨테이너 셸 (`examples/tools/container_shell_skill_reference.py`) - - 로컬 스킬을 포함한 로컬 셸 (`examples/tools/local_shell_skill.py`) + - 인라인 스킬을 사용하는 호스티드 컨테이너 셸 (`examples/tools/container_shell_inline_skill.py`) + - 스킬 참조를 사용하는 호스티드 컨테이너 셸 (`examples/tools/container_shell_skill_reference.py`) + - 로컬 스킬을 사용하는 로컬 셸 (`examples/tools/local_shell_skill.py`) - 네임스페이스 및 지연 도구를 사용하는 도구 검색 (`examples/tools/tool_search.py`) - 컴퓨터 사용 - 이미지 생성 @@ -139,4 +139,4 @@ search: - 실험적 Codex 동일 스레드 워크플로 (`examples/tools/codex_same_thread.py`) - **[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 4baa3974a7..5b6cc7ab2b 100644 --- a/docs/ko/guardrails.md +++ b/docs/ko/guardrails.md @@ -4,74 +4,74 @@ search: --- # 가드레일 -가드레일을 사용하면 사용자 입력과 에이전트 출력에 대한 검사 및 검증을 수행할 수 있습니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고/비싼) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 그 모델에게 수학 숙제를 도와달라고 요청하게 두고 싶지는 않을 것입니다. 따라서 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜 비싼 모델의 실행을 막을 수 있어 시간과 비용을 절약할 수 있습니다(**blocking guardrails를 사용할 때; parallel guardrails의 경우 가드레일이 완료되기 전에 비싼 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래의 "Execution modes"를 참고하세요**). +가드레일을 사용하면 사용자 입력과 에이전트 출력에 대한 검사와 검증을 수행할 수 있습니다. 예를 들어, 고객 요청을 지원하기 위해 매우 똑똑한(따라서 느리고 비용이 많이 드는) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 모델에게 수학 숙제를 도와달라고 요청하는 상황은 원치 않을 것입니다. 따라서 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜 비용이 많이 드는 모델이 실행되지 않도록 하여 시간과 비용을 절약할 수 있습니다(**blocking 가드레일을 사용하는 경우입니다. parallel 가드레일의 경우 가드레일이 완료되기 전에 비용이 많이 드는 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래 "실행 모드"를 참고하세요**). -가드레일에는 두 가지 종류가 있습니다: +가드레일에는 두 가지 종류가 있습니다. -1. 입력 가드레일은 초기 사용자 입력에서 실행됩니다 +1. 입력 가드레일은 최초 사용자 입력에서 실행됩니다 2. 출력 가드레일은 최종 에이전트 출력에서 실행됩니다 ## 워크플로 경계 -가드레일은 에이전트와 도구에 연결되지만, 워크플로의 동일한 지점에서 모두 실행되지는 않습니다: +가드레일은 에이전트와 도구에 연결되지만, 워크플로의 모든 지점에서 실행되는 것은 아닙니다. -- **입력 가드레일**은 체인의 첫 번째 에이전트에 대해서만 실행됩니다 -- **출력 가드레일**은 최종 출력을 생성하는 에이전트에 대해서만 실행됩니다 -- **도구 가드레일**은 모든 커스텀 함수 도구 호출에서 실행되며, 실행 전에는 입력 가드레일이, 실행 후에는 출력 가드레일이 실행됩니다 +- **입력 가드레일**은 체인의 첫 번째 에이전트에 대해서만 실행됩니다. +- **출력 가드레일**은 최종 출력을 생성하는 에이전트에 대해서만 실행됩니다. +- **도구 가드레일**은 모든 사용자 지정 함수 도구 호출에서 실행되며, 입력 가드레일은 실행 전에, 출력 가드레일은 실행 후에 실행됩니다. -매니저, 핸드오프 또는 위임된 전문 에이전트가 포함된 워크플로에서 각 커스텀 함수 도구 호출마다 검사가 필요하다면, 에이전트 수준의 입력/출력 가드레일에만 의존하지 말고 도구 가드레일을 사용하세요. +매니저, 핸드오프, 또는 위임된 전문가가 포함된 워크플로에서 각 사용자 지정 함수 도구 호출 주변에 검사가 필요하다면, 에이전트 수준의 입력/출력 가드레일에만 의존하지 말고 도구 가드레일을 사용하세요. ## 입력 가드레일 -입력 가드레일은 3단계로 실행됩니다: +입력 가드레일은 3단계로 실행됩니다. -1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다 +1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑됩니다 -3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다 +3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. 그렇다면 왜 가드레일을 `Runner.run`에 전달하지 않고 에이전트의 `guardrails` 속성에 두는지 궁금할 수 있습니다. 이는 가드레일이 실제 Agent와 관련되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 유리합니다. + 입력 가드레일은 사용자 입력에서 실행되도록 의도되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트인 경우에만 실행됩니다. `guardrails` 속성이 왜 `Runner.run`에 전달되지 않고 에이전트에 있는지 궁금할 수 있습니다. 이는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로, 코드를 함께 배치하면 가독성에 도움이 됩니다. ### 실행 모드 -입력 가드레일은 두 가지 실행 모드를 지원합니다: +입력 가드레일은 두 가지 실행 모드를 지원합니다. -- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트 실행과 동시에 실행됩니다. 둘 다 같은 시점에 시작되므로 지연 시간 측면에서 가장 유리합니다. 하지만 가드레일이 실패하면, 취소되기 전에 에이전트가 이미 토큰을 소비하고 도구를 실행했을 수 있습니다 +- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트 실행과 동시에 실행됩니다. 둘 다 동시에 시작되므로 가장 낮은 지연 시간을 제공합니다. 하지만 가드레일이 실패하면, 취소되기 전에 에이전트가 이미 토큰을 소비하고 도구를 실행했을 수 있습니다. -- **차단 실행**(`run_in_parallel=False`): 에이전트가 시작되기 *전에* 가드레일이 실행되고 완료됩니다. 가드레일 트립와이어가 트리거되면 에이전트는 전혀 실행되지 않아 토큰 소비와 도구 실행을 방지합니다. 비용 최적화가 중요하고 도구 호출로 인한 잠재적 부작용을 피하고 싶을 때 이상적입니다 +- **차단 실행**(`run_in_parallel=False`): 에이전트가 시작되기 *전에* 가드레일이 실행되고 완료됩니다. 가드레일 트립와이어가 트리거되면 에이전트는 실행되지 않으므로 토큰 소비와 도구 실행을 방지합니다. 비용 최적화에 적합하며 도구 호출로 인한 잠재적 부작용을 피하고자 할 때 이상적입니다. ## 출력 가드레일 -출력 가드레일은 3단계로 실행됩니다: +출력 가드레일은 3단계로 실행됩니다. -1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다 +1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다. 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑됩니다 -3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다 +3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다. !!! Note - 출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로 이렇게 하는 이유는 가드레일이 실제 Agent와 관련되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 유리합니다. + 출력 가드레일은 최종 에이전트 출력에서 실행되도록 의도되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트인 경우에만 실행됩니다. 입력 가드레일과 마찬가지로, 이렇게 하는 이유는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로, 코드를 함께 배치하면 가독성에 도움이 됩니다. - 출력 가드레일은 항상 에이전트 완료 후 실행되므로 `run_in_parallel` 매개변수를 지원하지 않습니다. + 출력 가드레일은 항상 에이전트가 완료된 후 실행되므로 `run_in_parallel` 매개변수를 지원하지 않습니다. ## 도구 가드레일 -도구 가드레일은 **함수 도구**를 감싸서 실행 전후에 도구 호출을 검증하거나 차단할 수 있게 합니다. 도구 자체에 구성되며 해당 도구가 호출될 때마다 실행됩니다. +도구 가드레일은 **함수 도구**를 감싸며, 실행 전후에 도구 호출을 검증하거나 차단할 수 있게 해줍니다. 도구 자체에 구성되며, 해당 도구가 호출될 때마다 실행됩니다. -- 입력 도구 가드레일은 도구 실행 전에 실행되며 호출 건너뛰기, 메시지로 출력 대체, 또는 트립와이어 발생을 수행할 수 있습니다 -- 출력 도구 가드레일은 도구 실행 후에 실행되며 출력 대체 또는 트립와이어 발생을 수행할 수 있습니다 -- 도구 가드레일은 [`function_tool`][agents.tool.function_tool]로 생성된 함수 도구에만 적용됩니다. 핸드오프는 일반 함수 도구 파이프라인이 아닌 SDK의 핸드오프 파이프라인을 통해 실행되므로, 핸드오프 호출 자체에는 도구 가드레일이 적용되지 않습니다. Hosted tools(`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`) 및 내장 실행 도구(`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`)도 이 가드레일 파이프라인을 사용하지 않으며, [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 현재 도구 가드레일 옵션을 직접 노출하지 않습니다 +- 입력 도구 가드레일은 도구가 실행되기 전에 실행되며, 호출을 건너뛰거나, 출력을 메시지로 대체하거나, 트립와이어를 발생시킬 수 있습니다. +- 출력 도구 가드레일은 도구가 실행된 후 실행되며, 출력을 대체하거나 트립와이어를 발생시킬 수 있습니다. +- 도구 가드레일은 [`function_tool`][agents.tool.function_tool]로 생성된 함수 도구에만 적용됩니다. 핸드오프는 일반적인 함수 도구 파이프라인이 아니라 SDK의 핸드오프 파이프라인을 통해 실행되므로, 도구 가드레일은 핸드오프 호출 자체에는 적용되지 않습니다. 호스티드 툴(`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`)과 내장 실행 도구(`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`)도 이 가드레일 파이프라인을 사용하지 않으며, [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 현재 도구 가드레일 옵션을 직접 노출하지 않습니다. 자세한 내용은 아래 코드 스니펫을 참고하세요. ## 트립와이어 -입력 또는 출력이 가드레일 검사를 통과하지 못하면, Guardrail은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 Agent 실행을 중단합니다. +입력 또는 출력이 가드레일을 통과하지 못하면, Guardrail은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다. ## 가드레일 구현 -입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예제에서는 내부적으로 에이전트를 실행하는 방식으로 이를 수행합니다. +입력을 받고 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예시에서는 내부적으로 에이전트를 실행하여 이를 수행합니다. ```python from pydantic import BaseModel @@ -124,10 +124,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. 가드레일 함수에서 이 에이전트를 사용합니다 -2. 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다 -3. 가드레일 결과에 추가 정보를 포함할 수 있습니다 -4. 워크플로를 정의하는 실제 에이전트입니다 +1. 이 에이전트를 가드레일 함수에서 사용합니다. +2. 에이전트의 입력/컨텍스트를 받고 결과를 반환하는 가드레일 함수입니다. +3. 가드레일 결과에 추가 정보를 포함할 수 있습니다. +4. 워크플로를 정의하는 실제 에이전트입니다. 출력 가드레일도 유사합니다. @@ -182,12 +182,12 @@ async def main(): print("Math output guardrail tripped") ``` -1. 실제 에이전트의 출력 타입입니다 -2. 가드레일의 출력 타입입니다 -3. 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다 -4. 워크플로를 정의하는 실제 에이전트입니다 +1. 실제 에이전트의 출력 타입입니다. +2. 가드레일의 출력 타입입니다. +3. 에이전트의 출력을 받고 결과를 반환하는 가드레일 함수입니다. +4. 워크플로를 정의하는 실제 에이전트입니다. -마지막으로, 다음은 도구 가드레일 예시입니다. +마지막으로, 도구 가드레일의 예시는 다음과 같습니다. ```python import json diff --git a/docs/ko/handoffs.md b/docs/ko/handoffs.md index 9fdfbd2ee6..44eb868cf7 100644 --- a/docs/ko/handoffs.md +++ b/docs/ko/handoffs.md @@ -4,17 +4,17 @@ search: --- # 핸드오프 -핸드오프를 사용하면 한 에이전트가 다른 에이전트에 작업을 위임할 수 있습니다. 이는 서로 다른 에이전트가 각기 다른 영역을 전문으로 하는 시나리오에서 특히 유용합니다. 예를 들어 고객 지원 앱에는 주문 상태, 환불, FAQ 등의 작업을 각각 전담하는 에이전트가 있을 수 있습니다. +핸드오프를 사용하면 에이전트가 다른 에이전트에 작업을 위임할 수 있습니다. 이는 서로 다른 에이전트가 각기 다른 영역에 특화된 시나리오에서 특히 유용합니다. 예를 들어 고객 지원 앱에는 주문 상태, 환불, FAQ 등의 작업을 각각 전담하는 에이전트가 있을 수 있습니다. -핸드오프는 LLM에 도구로 표현됩니다. 따라서 `Refund Agent`라는 이름의 에이전트로 핸드오프가 있으면 도구 이름은 `transfer_to_refund_agent`가 됩니다. +핸드오프는 LLM에 도구로 표현됩니다. 따라서 `Refund Agent`라는 에이전트로 핸드오프가 있다면, 도구는 `transfer_to_refund_agent`로 호출됩니다. ## 핸드오프 생성 -모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, 여기에 `Agent`를 직접 전달하거나 핸드오프를 사용자 지정하는 `Handoff` 객체를 전달할 수 있습니다. +모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, 이 매개변수는 `Agent`를 직접 받거나 핸드오프를 사용자 지정하는 `Handoff` 객체를 받을 수 있습니다. -일반 `Agent` 인스턴스를 전달하면 해당 [`handoff_description`][agents.agent.Agent.handoff_description] (설정된 경우)이 기본 도구 설명에 추가됩니다. 전체 `handoff()` 객체를 작성하지 않고도 모델이 해당 핸드오프를 선택해야 하는 시점을 힌트로 제공할 때 사용하세요. +일반 `Agent` 인스턴스를 전달하면, 해당 [`handoff_description`][agents.agent.Agent.handoff_description]이 설정된 경우 기본 도구 설명에 덧붙여집니다. 전체 `handoff()` 객체를 작성하지 않고도 모델이 해당 핸드오프를 선택해야 하는 경우를 암시하는 데 사용하세요. -Agents SDK가 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용해 핸드오프를 만들 수 있습니다. 이 함수로 핸드오프 대상 에이전트와 선택적 재정의 및 입력 필터를 지정할 수 있습니다. +Agents SDK에서 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용하여 핸드오프를 만들 수 있습니다. 이 함수를 사용하면 핸드오프할 에이전트를 지정하고, 선택적으로 오버라이드와 입력 필터를 지정할 수 있습니다. ### 기본 사용법 @@ -30,22 +30,22 @@ 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`: 핸드오프 도구 호출 인자의 스키마입니다. 설정하면 파싱된 페이로드가 `on_handoff`로 전달됩니다. -- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 자세한 내용은 아래를 참고하세요. -- `is_enabled`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수가 될 수 있어 런타임에 동적으로 핸드오프를 활성화/비활성화할 수 있습니다. -- `nest_handoff_history`: RunConfig 수준의 `nest_handoff_history` 설정에 대한 선택적 호출별 재정의입니다. `None`이면 활성 run 설정에 정의된 값을 대신 사용합니다. +- `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, 이는 `transfer_to_`으로 해석됩니다. 이를 오버라이드할 수 있습니다. +- `tool_description_override`: `Handoff.default_tool_description()`의 기본 도구 설명을 오버라이드합니다. +- `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출되는 것을 알게 되는 즉시 일부 데이터 가져오기를 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 받으며, 선택적으로 LLM이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다. +- `input_type`: 핸드오프 도구 호출 인자의 스키마입니다. 설정하면 파싱된 페이로드가 `on_handoff`에 전달됩니다. +- `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있게 해줍니다. 자세한 내용은 아래를 참조하세요. +- `is_enabled`: 핸드오프가 활성화되어 있는지 여부입니다. 불리언이거나 불리언을 반환하는 함수일 수 있으므로, 런타임에 동적으로 핸드오프를 활성화하거나 비활성화할 수 있습니다. +- `nest_handoff_history`: RunConfig 수준의 `nest_handoff_history` 설정에 대한 선택적 호출별 오버라이드입니다. `None`이면 활성 실행 구성에 정의된 값이 대신 사용됩니다. -[`handoff()`][agents.handoffs.handoff] 헬퍼는 항상 전달한 특정 `agent`로 제어를 넘깁니다. 가능한 대상이 여러 개라면 대상마다 하나의 핸드오프를 등록하고 모델이 그중에서 선택하게 하세요. 호출 시점에 어떤 에이전트를 반환할지 직접 핸드오프 코드에서 결정해야 할 때만 사용자 지정 [`Handoff`][agents.handoffs.Handoff]를 사용하세요. +[`handoff()`][agents.handoffs.handoff] 헬퍼는 항상 전달한 특정 `agent`로 제어권을 이전합니다. 가능한 목적지가 여러 개라면 목적지마다 하나의 핸드오프를 등록하고 모델이 그중에서 선택하게 하세요. 호출 시점에 어떤 에이전트를 반환할지 자체 핸드오프 코드가 결정해야 하는 경우에만 사용자 지정 [`Handoff`][agents.handoffs.Handoff]를 사용하세요. ```python from agents import Agent, handoff, RunContextWrapper @@ -65,7 +65,7 @@ handoff_obj = handoff( ## 핸드오프 입력 -특정 상황에서는 핸드오프를 호출할 때 LLM이 일부 데이터를 제공하도록 하고 싶을 수 있습니다. 예를 들어 "Escalation agent"로 핸드오프한다고 가정해 보겠습니다. 이때 기록을 남기기 위해 사유를 함께 받도록 할 수 있습니다. +특정 상황에서는 LLM이 핸드오프를 호출할 때 일부 데이터를 제공하기를 원할 수 있습니다. 예를 들어 "에스컬레이션 에이전트"로 핸드오프하는 경우를 생각해 보세요. 이를 기록할 수 있도록 사유를 제공받고 싶을 수 있습니다. ```python from pydantic import BaseModel @@ -87,44 +87,44 @@ handoff_obj = handoff( ) ``` -`input_type`은 핸드오프 도구 호출 자체의 인자를 설명합니다. SDK는 그 스키마를 핸드오프 도구의 `parameters`로 모델에 노출하고, 반환된 JSON을 로컬에서 검증한 뒤, 파싱된 값을 `on_handoff`에 전달합니다. +`input_type`은 핸드오프 도구 호출 자체의 인자를 설명합니다. SDK는 해당 스키마를 핸드오프 도구의 `parameters`로 모델에 노출하고, 반환된 JSON을 로컬에서 검증하며, 파싱된 값을 `on_handoff`에 전달합니다. -이는 다음 에이전트의 기본 입력을 대체하지 않으며, 다른 목적지를 선택하지도 않습니다. [`handoff()`][agents.handoffs.handoff] 헬퍼는 여전히 래핑한 특정 에이전트로 전송하며, 수신 에이전트는 [`input_filter`][agents.handoffs.Handoff.input_filter] 또는 중첩 핸드오프 기록 설정으로 변경하지 않는 한 대화 기록을 계속 확인합니다. +이는 다음 에이전트의 주 입력을 대체하지 않으며, 다른 목적지를 선택하지도 않습니다. [`handoff()`][agents.handoffs.handoff] 헬퍼는 여전히 래핑한 특정 에이전트로 이전하며, 수신 에이전트는 [`input_filter`][agents.handoffs.Handoff.input_filter] 또는 중첩 핸드오프 기록 설정으로 변경하지 않는 한 여전히 대화 기록을 봅니다. -`input_type`은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]와도 별개입니다. 이미 로컬에 있는 애플리케이션 상태나 의존성이 아니라, 모델이 핸드오프 시점에 결정하는 메타데이터에 `input_type`을 사용하세요. +`input_type`은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]와도 별개입니다. 로컬에 이미 있는 애플리케이션 상태나 종속성이 아니라, 모델이 핸드오프 시점에 결정하는 메타데이터에는 `input_type`을 사용하세요. ### `input_type` 사용 시점 -핸드오프에 `reason`, `language`, `priority`, `summary` 같은 모델 생성 메타데이터의 작은 조각이 필요할 때 `input_type`을 사용하세요. 예를 들어 트리아지 에이전트는 `{ "reason": "duplicate_charge", "priority": "high" }`와 함께 환불 에이전트로 핸드오프할 수 있으며, `on_handoff`는 환불 에이전트가 이어받기 전에 해당 메타데이터를 기록하거나 저장할 수 있습니다. +핸드오프에 `reason`, `language`, `priority`, `summary`와 같이 모델이 생성한 작은 메타데이터가 필요할 때 `input_type`을 사용하세요. 예를 들어 분류 에이전트는 `{ "reason": "duplicate_charge", "priority": "high" }`와 함께 환불 에이전트로 핸드오프할 수 있으며, 환불 에이전트가 이어받기 전에 `on_handoff`에서 해당 메타데이터를 기록하거나 저장할 수 있습니다. -목적이 다르면 다른 메커니즘을 선택하세요: +목표가 다른 경우에는 다른 메커니즘을 선택하세요: -- 기존 애플리케이션 상태와 의존성은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 넣으세요. [컨텍스트 가이드](context.md)를 참고하세요. -- 수신 에이전트가 보는 기록을 바꾸려면 [`input_filter`][agents.handoffs.Handoff.input_filter], [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history], 또는 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 사용하세요. -- 가능한 전문 에이전트 대상이 여러 개라면 대상마다 하나의 핸드오프를 등록하세요. `input_type`은 선택된 핸드오프에 메타데이터를 추가할 수는 있지만, 대상 간 디스패치를 수행하지는 않습니다. -- 대화를 전송하지 않고 중첩 전문 에이전트에 구조화된 입력을 주고 싶다면 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]을 우선 사용하세요. [도구](tools.md#structured-input-for-tool-agents)를 참고하세요. +- 기존 애플리케이션 상태와 종속성은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 넣으세요. [컨텍스트 가이드](context.md)를 참조하세요. +- 수신 에이전트가 보게 될 기록을 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter], [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 또는 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 사용하세요. +- 여러 전문 에이전트 중 하나를 선택할 수 있는 경우 목적지마다 하나의 핸드오프를 등록하세요. `input_type`은 선택된 핸드오프에 메타데이터를 추가할 수 있지만, 목적지 사이에서 디스패치하지는 않습니다. +- 대화를 이전하지 않고 중첩된 전문 에이전트에 구조화된 입력을 제공하려면 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]를 선호하세요. [도구](tools.md#structured-input-for-tool-agents)를 참조하세요. ## 입력 필터 -핸드오프가 발생하면 새 에이전트가 대화를 이어받아 이전 전체 대화 기록을 보는 것과 같습니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter]를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData]를 통해 기존 입력을 받고, 새로운 `HandoffInputData`를 반환해야 하는 함수입니다. +핸드오프가 발생하면 새 에이전트가 대화를 이어받아 이전 대화 기록 전체를 볼 수 있는 것처럼 동작합니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter]를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData]를 통해 기존 입력을 받는 함수이며, 새로운 `HandoffInputData`를 반환해야 합니다. [`HandoffInputData`][agents.handoffs.HandoffInputData]에는 다음이 포함됩니다: -- `input_history`: `Runner.run(...)` 시작 전의 입력 기록 -- `pre_handoff_items`: 핸드오프가 호출된 에이전트 턴 이전에 생성된 항목 -- `new_items`: 핸드오프 호출 및 핸드오프 출력 항목을 포함해 현재 턴에서 생성된 항목 -- `input_items`: `new_items` 대신 다음 에이전트로 전달할 선택적 항목으로, 세션 기록용 `new_items`는 유지하면서 모델 입력을 필터링할 수 있게 해줍니다 -- `run_context`: 핸드오프 호출 시점의 활성 [`RunContextWrapper`][agents.run_context.RunContextWrapper] +- `input_history`: `Runner.run(...)`이 시작되기 전의 입력 기록입니다. +- `pre_handoff_items`: 핸드오프가 호출된 에이전트 턴 이전에 생성된 항목입니다. +- `new_items`: 핸드오프 호출과 핸드오프 출력 항목을 포함하여 현재 턴 동안 생성된 항목입니다. +- `input_items`: `new_items` 대신 다음 에이전트로 전달할 선택적 항목으로, 세션 기록을 위해 `new_items`는 그대로 유지하면서 모델 입력을 필터링할 수 있습니다. +- `run_context`: 핸드오프가 호출된 시점의 활성 [`RunContextWrapper`][agents.run_context.RunContextWrapper]입니다. -중첩 핸드오프는 옵트인 베타로 제공되며 안정화 중이므로 기본적으로 비활성화되어 있습니다. [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]를 활성화하면 러너는 이전 전사를 단일 어시스턴트 요약 메시지로 축약하고, 동일 run에서 여러 핸드오프가 발생할 때 새 턴이 계속 추가되도록 `` 블록으로 감쌉니다. 전체 `input_filter`를 작성하지 않고 생성된 메시지를 대체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 통해 자체 매핑 함수를 제공할 수 있습니다. 이 옵트인은 핸드오프와 run 어느 쪽에서도 명시적 `input_filter`를 제공하지 않을 때만 적용되므로, 이미 페이로드를 사용자 지정하는 기존 코드(이 저장소의 예제 포함)는 변경 없이 현재 동작을 유지합니다. [`handoff(...)`][agents.handoffs.handoff]에 `nest_handoff_history=True` 또는 `False`를 전달해 단일 핸드오프의 중첩 동작을 재정의할 수 있으며, 이는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 설정합니다. 생성된 요약의 래퍼 텍스트만 바꾸면 된다면 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (및 선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers])를 호출하세요. +중첩 핸드오프는 옵트인 베타로 제공되며, 안정화하는 동안 기본적으로 비활성화되어 있습니다. [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]를 활성화하면 러너는 이전 대화 기록을 하나의 assistant 요약 메시지로 축약하고, 동일한 실행 중 여러 핸드오프가 발생할 때 새 턴을 계속 덧붙이는 `` 블록으로 감쌉니다. 전체 `input_filter`를 작성하지 않고 생성된 메시지를 대체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 통해 자체 매핑 함수를 제공할 수 있습니다. 이 옵트인은 핸드오프와 실행 모두 명시적 `input_filter`를 제공하지 않을 때만 적용되므로, 이미 페이로드를 사용자 지정하는 기존 코드(이 저장소의 코드 예제 포함)는 변경 없이 현재 동작을 유지합니다. 단일 핸드오프에 대한 중첩 동작은 [`handoff(...)`][agents.handoffs.handoff]에 `nest_handoff_history=True` 또는 `False`를 전달하여 오버라이드할 수 있으며, 이는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 설정합니다. 생성된 요약의 래퍼 텍스트만 변경해야 하는 경우, 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]도 호출할 수 있습니다). -핸드오프와 활성 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] 양쪽 모두 필터를 정의한 경우, 해당 핸드오프에는 핸드오프별 [`input_filter`][agents.handoffs.Handoff.input_filter]가 우선 적용됩니다. +핸드오프와 활성 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]가 모두 필터를 정의하는 경우, 해당 특정 핸드오프에는 핸드오프별 [`input_filter`][agents.handoffs.Handoff.input_filter]가 우선합니다. !!! note - 핸드오프는 단일 run 내에서만 유지됩니다. 입력 가드레일은 체인의 첫 번째 에이전트에만 계속 적용되고, 출력 가드레일은 최종 출력을 생성하는 에이전트에만 적용됩니다. 워크플로 내 각 사용자 지정 함수 도구 호출 주변에서 검사가 필요하다면 도구 가드레일을 사용하세요. + 핸드오프는 단일 실행 안에서만 이루어집니다. 입력 가드레일은 여전히 체인의 첫 번째 에이전트에만 적용되고, 출력 가드레일은 최종 출력을 생성하는 에이전트에만 적용됩니다. 워크플로 안의 각 사용자 지정 함수 도구 호출 주변에 검사가 필요할 때는 도구 가드레일을 사용하세요. -일부 일반 패턴(예: 기록에서 모든 도구 호출 제거)은 [`agents.extensions.handoff_filters`][]에 구현되어 있습니다 +몇 가지 일반적인 패턴(예: 기록에서 모든 도구 호출 제거)은 [`agents.extensions.handoff_filters`][]에 구현되어 있습니다. ```python from agents import Agent, handoff @@ -142,7 +142,7 @@ handoff_obj = handoff( ## 권장 프롬프트 -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/human_in_the_loop.md b/docs/ko/human_in_the_loop.md index 542d4bb6da..e4e9967920 100644 --- a/docs/ko/human_in_the_loop.md +++ b/docs/ko/human_in_the_loop.md @@ -4,17 +4,17 @@ search: --- # 휴먼인더루프 (HITL) -휴먼인더루프 (HITL) 흐름을 사용해 민감한 도구 호출을 사람이 승인하거나 거절할 때까지 에이전트 실행을 일시 중지할 수 있습니다. 도구는 승인 필요 여부를 선언하고, 실행 결과는 대기 중인 승인을 인터럽션으로 노출하며, `RunState`를 통해 결정 이후 실행을 직렬화하고 재개할 수 있습니다 +휴먼인더루프 (HITL) 흐름을 사용해 사람이 민감한 도구 호출을 승인하거나 거부할 때까지 에이전트 실행을 일시 중지합니다. 도구는 승인이 필요한 시점을 선언하고, 실행 결과는 대기 중인 승인을 인터럽션(중단 처리)으로 표시하며, `RunState`를 사용하면 결정이 내려진 뒤 실행을 직렬화하고 재개할 수 있습니다. -이 승인 표면은 현재 최상위 에이전트로 제한되지 않고 실행 전체에 적용됩니다. 동일한 패턴은 도구가 현재 에이전트에 속한 경우, 핸드오프를 통해 도달한 에이전트에 속한 경우, 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에 속한 경우에도 적용됩니다. 중첩된 `Agent.as_tool()`의 경우에도 인터럽션은 바깥 실행에 나타나므로, 바깥 `RunState`에서 승인 또는 거절하고 원래 최상위 실행을 재개합니다 +이 승인 표면은 실행 전체에 적용되며, 현재 최상위 에이전트로 제한되지 않습니다. 도구가 현재 에이전트에 속한 경우, 핸드오프를 통해 도달한 에이전트에 속한 경우, 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에 속한 경우에도 동일한 패턴이 적용됩니다. 중첩된 `Agent.as_tool()` 사례에서도 인터럽션(중단 처리)은 여전히 외부 실행에 표시되므로, 외부 `RunState`에서 승인하거나 거부한 뒤 원래 최상위 실행을 재개합니다. -`Agent.as_tool()`에서는 서로 다른 두 계층에서 승인이 발생할 수 있습니다: 에이전트 도구 자체가 `Agent.as_tool(..., needs_approval=...)`를 통해 승인을 요구할 수 있고, 중첩된 실행이 시작된 뒤에는 중첩 에이전트 내부 도구가 자체 승인을 다시 요청할 수 있습니다. 둘 다 동일한 바깥 실행 인터럽션 흐름으로 처리됩니다 +`Agent.as_tool()`을 사용할 때 승인은 두 가지 서로 다른 계층에서 발생할 수 있습니다. 에이전트 도구 자체가 `Agent.as_tool(..., needs_approval=...)`을 통해 승인을 요구할 수 있고, 중첩된 에이전트 내부의 도구가 중첩 실행이 시작된 뒤 나중에 자체 승인을 발생시킬 수 있습니다. 둘 다 동일한 외부 실행 인터럽션(중단 처리) 흐름을 통해 처리됩니다. -이 페이지는 `interruptions`를 통한 수동 승인 흐름에 중점을 둡니다. 앱에서 코드로 판단할 수 있다면, 일부 도구 유형은 프로그래매틱 승인 콜백도 지원하므로 실행을 멈추지 않고 계속할 수 있습니다 +이 페이지는 `interruptions`를 통한 수동 승인 흐름에 초점을 맞춥니다. 앱이 코드에서 결정을 내릴 수 있다면, 일부 도구 유형은 프로그래밍 방식 승인 콜백도 지원하므로 실행을 일시 중지하지 않고 계속할 수 있습니다. -## 승인 필요 도구 표시 +## 승인이 필요한 도구 표시 -항상 승인을 요구하려면 `needs_approval`를 `True`로 설정하거나, 호출별로 판단하는 비동기 함수를 제공하세요. 호출 가능 객체는 실행 컨텍스트, 파싱된 도구 매개변수, 도구 호출 ID를 받습니다 +항상 승인을 요구하려면 `needs_approval`을 `True`로 설정하고, 호출별로 결정하려면 비동기 함수를 제공합니다. 호출 가능한 객체는 실행 컨텍스트, 파싱된 도구 매개변수, 도구 호출 ID를 받습니다. ```python from agents import Agent, Runner, function_tool @@ -41,28 +41,28 @@ agent = Agent( ) ``` -`needs_approval`는 [`function_tool`][agents.tool.function_tool], [`Agent.as_tool`][agents.agent.Agent.as_tool], [`ShellTool`][agents.tool.ShellTool], [`ApplyPatchTool`][agents.tool.ApplyPatchTool]에서 사용할 수 있습니다. 로컬 MCP 서버도 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]의 `require_approval`를 통해 승인을 지원합니다. 호스티드 MCP 서버는 [`HostedMCPTool`][agents.tool.HostedMCPTool]에서 `tool_config={"require_approval": "always"}`와 선택적 `on_approval_request` 콜백으로 승인을 지원합니다. Shell 및 apply_patch 도구는 인터럽션을 노출하지 않고 자동 승인 또는 자동 거절하려는 경우 `on_approval` 콜백을 받을 수 있습니다 +`needs_approval`은 [`function_tool`][agents.tool.function_tool], [`Agent.as_tool`][agents.agent.Agent.as_tool], [`ShellTool`][agents.tool.ShellTool], [`ApplyPatchTool`][agents.tool.ApplyPatchTool]에서 사용할 수 있습니다. 로컬 MCP 서버도 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]의 `require_approval`을 통해 승인을 지원합니다. 호스티드 MCP 서버는 [`HostedMCPTool`][agents.tool.HostedMCPTool]에서 `tool_config={"require_approval": "always"}`와 선택적 `on_approval_request` 콜백을 통해 승인을 지원합니다. Shell 및 apply_patch 도구는 인터럽션(중단 처리)을 표시하지 않고 자동 승인 또는 자동 거부를 하려는 경우 `on_approval` 콜백을 허용합니다. -## 승인 흐름 작동 방식 +## 승인 흐름의 작동 방식 -1. 모델이 도구 호출을 생성하면 러너는 해당 도구의 승인 규칙(`needs_approval`, `require_approval`, 또는 호스티드 MCP 동등 설정)을 평가합니다 -2. 해당 도구 호출에 대한 승인 결정이 이미 [`RunContextWrapper`][agents.run_context.RunContextWrapper]에 저장되어 있으면, 러너는 추가 확인 없이 진행합니다. 호출별 승인은 특정 호출 ID 범위에만 적용됩니다. 실행의 나머지 동안 같은 도구의 향후 호출에도 동일한 결정을 유지하려면 `always_approve=True` 또는 `always_reject=True`를 전달하세요 -3. 그렇지 않으면 실행이 일시 중지되고 `RunResult.interruptions`(또는 `RunResultStreaming.interruptions`)에 `agent.name`, `tool_name`, `arguments` 같은 세부 정보를 담은 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 항목이 포함됩니다. 여기에는 핸드오프 이후 또는 중첩 `Agent.as_tool()` 실행 내부에서 발생한 승인도 포함됩니다 -4. `result.to_state()`로 결과를 `RunState`로 변환하고, `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤, `Runner.run(agent, state)` 또는 `Runner.run_streamed(agent, state)`로 재개하세요. 여기서 `agent`는 해당 실행의 원래 최상위 에이전트입니다 -5. 재개된 실행은 중단된 지점부터 계속되며, 새 승인이 필요하면 이 흐름으로 다시 진입합니다 +1. 모델이 도구 호출을 내보내면, 러너는 해당 승인 규칙(`needs_approval`, `require_approval` 또는 호스티드 MCP에 해당하는 설정)을 평가합니다. +2. 해당 도구 호출에 대한 승인 결정이 이미 [`RunContextWrapper`][agents.run_context.RunContextWrapper]에 저장되어 있으면, 러너는 프롬프트 없이 진행합니다. 호출별 승인은 특정 호출 ID로 범위가 지정됩니다. 실행의 나머지 동안 해당 도구에 대한 향후 호출에도 같은 결정을 유지하려면 `always_approve=True` 또는 `always_reject=True`를 전달합니다. +3. 그렇지 않으면 실행이 일시 중지되고 `RunResult.interruptions`(또는 `RunResultStreaming.interruptions`)에는 `agent.name`, `tool_name`, `arguments`와 같은 세부 정보가 포함된 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 항목이 들어갑니다. 여기에는 핸드오프 이후 또는 중첩된 `Agent.as_tool()` 실행 내부에서 발생한 승인도 포함됩니다. +4. `result.to_state()`로 결과를 `RunState`로 변환하고, `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤, 실행의 원래 최상위 에이전트인 `agent`와 함께 `Runner.run(agent, state)` 또는 `Runner.run_streamed(agent, state)`로 재개합니다. +5. 재개된 실행은 중단된 지점부터 계속되며, 새 승인이 필요하면 이 흐름에 다시 진입합니다. -`always_approve=True` 또는 `always_reject=True`로 생성된 고정 결정은 실행 상태에 저장되므로, 나중에 동일한 일시 중지 실행을 재개할 때 `state.to_string()` / `RunState.from_string(...)` 및 `state.to_json()` / `RunState.from_json(...)`을 거쳐도 유지됩니다 +`always_approve=True` 또는 `always_reject=True`로 생성된 고정 결정은 실행 상태에 저장되므로, 나중에 같은 일시 중지된 실행을 재개할 때 `state.to_string()` / `RunState.from_string(...)` 및 `state.to_json()` / `RunState.from_json(...)` 후에도 유지됩니다. -같은 패스에서 모든 대기 중 승인을 처리할 필요는 없습니다. `interruptions`에는 일반 함수 도구, 호스티드 MCP 승인, 중첩 `Agent.as_tool()` 승인이 혼합되어 있을 수 있습니다. 일부 항목만 승인 또는 거절한 뒤 다시 실행하면, 해결된 호출은 계속 진행되고 미해결 항목은 `interruptions`에 남아 실행을 다시 일시 중지합니다 +같은 단계에서 대기 중인 모든 승인을 해결할 필요는 없습니다. `interruptions`에는 일반 함수 도구, 호스티드 MCP 승인, 중첩된 `Agent.as_tool()` 승인 등이 섞여 있을 수 있습니다. 일부 항목만 승인하거나 거부한 뒤 다시 실행하면, 해결된 호출은 계속될 수 있고 해결되지 않은 호출은 `interruptions`에 남아 실행을 다시 일시 중지합니다. -## 사용자 지정 거절 메시지 +## 사용자 지정 거부 메시지 -기본적으로 거절된 도구 호출은 SDK의 표준 거절 텍스트를 실행으로 다시 반환합니다. 이 메시지는 두 계층에서 사용자 지정할 수 있습니다 +기본적으로 거부된 도구 호출은 SDK의 표준 거부 텍스트를 실행으로 다시 반환합니다. 이 메시지는 두 계층에서 사용자 지정할 수 있습니다. -- 실행 전체 대체값: [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]를 설정해 실행 전체의 승인 거절에 대한 기본 모델 표시 메시지를 제어합니다 -- 호출별 재정의: 특정 거절 도구 호출에 다른 메시지를 노출하려면 `state.reject(...)`에 `rejection_message=...`를 전달합니다 +- 실행 전체 폴백: 전체 실행에서 승인 거부에 대해 모델에 표시되는 기본 메시지를 제어하려면 [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]를 설정합니다. +- 호출별 재정의: 특정 거부된 도구 호출 하나에 다른 메시지를 표시하려면 `state.reject(...)`에 `rejection_message=...`를 전달합니다. -둘 다 제공되면 호출별 `rejection_message`가 실행 전체 포매터보다 우선합니다 +둘 다 제공되면, 호출별 `rejection_message`가 실행 전체 포매터보다 우선합니다. ```python from agents import RunConfig, ToolErrorFormatterArgs @@ -83,27 +83,27 @@ state.reject( ) ``` -두 계층을 함께 보여주는 완전한 예시는 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py)를 참조하세요 +두 계층을 함께 보여 주는 전체 예제는 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py)를 참고하세요. ## 자동 승인 결정 -수동 `interruptions`가 가장 일반적인 패턴이지만 유일한 방법은 아닙니다 +수동 `interruptions`가 가장 일반적인 패턴이지만, 유일한 방법은 아닙니다. -- 로컬 [`ShellTool`][agents.tool.ShellTool] 및 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]은 `on_approval`을 사용해 코드에서 즉시 승인 또는 거절할 수 있습니다 -- [`HostedMCPTool`][agents.tool.HostedMCPTool]은 `tool_config={"require_approval": "always"}`와 `on_approval_request`를 함께 사용해 같은 유형의 프로그래매틱 결정을 내릴 수 있습니다 -- 일반 [`function_tool`][agents.tool.function_tool] 도구와 [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 이 페이지의 수동 인터럽션 흐름을 사용합니다 +- 로컬 [`ShellTool`][agents.tool.ShellTool] 및 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]은 `on_approval`을 사용해 코드에서 즉시 승인하거나 거부할 수 있습니다. +- [`HostedMCPTool`][agents.tool.HostedMCPTool]은 `tool_config={"require_approval": "always"}`와 `on_approval_request`를 함께 사용해 같은 종류의 프로그래밍 방식 결정을 수행할 수 있습니다. +- 일반 [`function_tool`][agents.tool.function_tool] 도구와 [`Agent.as_tool()`][agents.agent.Agent.as_tool]는 이 페이지의 수동 인터럽션(중단 처리) 흐름을 사용합니다. -이 콜백들이 결정을 반환하면 실행은 사람 응답을 기다리며 멈추지 않고 계속됩니다. Realtime 및 음성 세션 API의 경우 [Realtime 가이드](realtime/guide.md)의 승인 흐름을 참조하세요 +이러한 콜백이 결정을 반환하면, 실행은 사람의 응답을 기다리며 일시 중지하지 않고 계속됩니다. Realtime 및 음성 세션 API의 경우 [Realtime 가이드](realtime/guide.md)의 승인 흐름을 참고하세요. ## 스트리밍 및 세션 -동일한 인터럽션 흐름은 스트리밍 실행에서도 동작합니다. 스트리밍 실행이 일시 중지된 뒤에는 반복자가 끝날 때까지 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events]를 계속 소비하고, [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]를 확인해 해결한 다음, 재개 출력도 계속 스트리밍하려면 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed]로 재개하세요. 이 패턴의 스트리밍 버전은 [스트리밍](streaming.md)을 참조하세요 +동일한 인터럽션(중단 처리) 흐름은 스트리밍 실행에서도 작동합니다. 스트리밍 실행이 일시 중지된 뒤에는 이터레이터가 완료될 때까지 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events]를 계속 소비하고, [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]를 검사하고, 이를 해결한 다음, 재개된 출력도 계속 스트리밍하려면 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed]로 재개합니다. 이 패턴의 스트리밍 버전은 [스트리밍](streaming.md)을 참고하세요. -세션도 함께 사용 중이라면 `RunState`에서 재개할 때 동일한 세션 인스턴스를 계속 전달하거나, 같은 백엔드 스토어를 가리키는 다른 세션 객체를 전달하세요. 그러면 재개된 턴이 같은 저장 대화 기록에 추가됩니다. 세션 수명주기 상세는 [세션](sessions/index.md)을 참조하세요 +세션도 사용 중이라면 `RunState`에서 재개할 때 동일한 세션 인스턴스를 계속 전달하거나, 같은 백킹 스토어를 가리키는 다른 세션 객체를 전달합니다. 그러면 재개된 턴이 동일하게 저장된 대화 기록에 추가됩니다. 세션 수명 주기 세부 정보는 [세션](sessions/index.md)을 참고하세요. ## 예시: 일시 중지, 승인, 재개 -아래 스니펫은 JavaScript HITL 가이드를 반영합니다: 도구에 승인이 필요하면 일시 중지하고, 상태를 디스크에 저장했다가, 다시 불러와 결정 수집 후 재개합니다 +아래 스니펫은 JavaScript HITL 가이드를 반영합니다. 도구에 승인이 필요할 때 일시 중지하고, 상태를 디스크에 저장하며, 다시 로드한 뒤 결정을 수집하고 재개합니다. ```python import asyncio @@ -167,35 +167,35 @@ if __name__ == "__main__": asyncio.run(main()) ``` -이 예시에서 `prompt_approval`는 `input()`을 사용하고 `run_in_executor(...)`로 실행되므로 동기식입니다. 승인 소스가 이미 비동기(예: HTTP 요청 또는 비동기 데이터베이스 쿼리)라면 `async def` 함수를 사용해 대신 직접 `await`할 수 있습니다 +이 예제에서 `prompt_approval`은 `input()`을 사용하고 `run_in_executor(...)`로 실행되기 때문에 동기식입니다. 승인 소스가 이미 비동기식인 경우(예: HTTP 요청 또는 비동기 데이터베이스 쿼리), 대신 `async def` 함수를 사용하고 직접 `await`할 수 있습니다. -승인 대기 중에도 출력을 스트리밍하려면 `Runner.run_streamed`를 호출하고, `result.stream_events()`를 완료될 때까지 소비한 다음, 위에 나온 동일한 `result.to_state()` 및 재개 단계를 따르세요 +승인을 기다리는 동안 출력을 스트리밍하려면 `Runner.run_streamed`를 호출하고, 완료될 때까지 `result.stream_events()`를 소비한 다음, 위에 표시된 것과 동일한 `result.to_state()` 및 재개 단계를 따릅니다. -## 저장소 패턴 및 예제 +## 리포지토리 패턴 및 코드 예제 -- **스트리밍 승인**: `examples/agent_patterns/human_in_the_loop_stream.py`는 `stream_events()`를 모두 소비한 뒤 대기 중인 도구 호출을 승인하고 `Runner.run_streamed(agent, state)`로 재개하는 방법을 보여줍니다 -- **사용자 지정 거절 텍스트**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py`는 승인이 거절될 때 실행 수준 `tool_error_formatter`와 호출별 `rejection_message` 재정의를 결합하는 방법을 보여줍니다 -- **도구로서의 에이전트 승인**: `Agent.as_tool(..., needs_approval=...)`는 위임된 에이전트 작업에 검토가 필요할 때 동일한 인터럽션 흐름을 적용합니다. 중첩 인터럽션도 바깥 실행에 노출되므로 중첩 에이전트가 아니라 원래 최상위 에이전트를 재개하세요 -- **로컬 shell 및 apply_patch 도구**: `ShellTool`과 `ApplyPatchTool`도 `needs_approval`를 지원합니다. 향후 호출에 대한 결정을 캐시하려면 `state.approve(interruption, always_approve=True)` 또는 `state.reject(..., always_reject=True)`를 사용하세요. 자동 결정을 위해서는 `on_approval`를 제공하고(`examples/tools/shell.py` 참조), 수동 결정을 위해서는 인터럽션을 처리하세요(`examples/tools/shell_human_in_the_loop.py` 참조). 호스티드 shell 환경은 `needs_approval` 또는 `on_approval`를 지원하지 않습니다. [도구 가이드](tools.md)를 참조하세요 -- **로컬 MCP 서버**: MCP 도구 호출을 제어하려면 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp`에서 `require_approval`를 사용하세요(`examples/mcp/get_all_mcp_tools_example/main.py`, `examples/mcp/tool_filter_example/main.py` 참조) -- **호스티드 MCP 서버**: HITL을 강제하려면 `HostedMCPTool`에서 `require_approval`를 `"always"`로 설정하고, 필요 시 `on_approval_request`를 제공해 자동 승인 또는 거절할 수 있습니다(`examples/hosted_mcp/human_in_the_loop.py`, `examples/hosted_mcp/on_approval.py` 참조). 신뢰 가능한 서버에는 `"never"`를 사용하세요(`examples/hosted_mcp/simple.py`) -- **세션 및 메모리**: 승인과 대화 기록이 여러 턴에 걸쳐 유지되도록 `Runner.run`에 세션을 전달하세요. SQLite 및 OpenAI Conversations 세션 변형은 `examples/memory/memory_session_hitl_example.py`와 `examples/memory/openai_session_hitl_example.py`에 있습니다 -- **실시간 에이전트**: realtime 데모는 `RealtimeSession`의 `approve_tool_call` / `reject_tool_call`을 통해 도구 호출을 승인 또는 거절하는 WebSocket 메시지를 노출합니다(서버 측 핸들러는 `examples/realtime/app/server.py`, API 표면은 [Realtime 가이드](realtime/guide.md#tool-approvals) 참조) +- **스트리밍 승인**: `examples/agent_patterns/human_in_the_loop_stream.py`는 `stream_events()`를 모두 소비한 다음, `Runner.run_streamed(agent, state)`로 재개하기 전에 대기 중인 도구 호출을 승인하는 방법을 보여 줍니다. +- **사용자 지정 거부 텍스트**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py`는 승인이 거부될 때 실행 수준 `tool_error_formatter`와 호출별 `rejection_message` 재정의를 결합하는 방법을 보여 줍니다. +- **도구로서의 에이전트 승인**: 위임된 에이전트 작업에 검토가 필요할 때 `Agent.as_tool(..., needs_approval=...)`은 동일한 인터럽션(중단 처리) 흐름을 적용합니다. 중첩된 인터럽션(중단 처리)은 여전히 외부 실행에 표시되므로, 중첩된 에이전트가 아니라 원래 최상위 에이전트를 재개합니다. +- **로컬 shell 및 apply_patch 도구**: `ShellTool` 및 `ApplyPatchTool`도 `needs_approval`을 지원합니다. 향후 호출에 대한 결정을 캐시하려면 `state.approve(interruption, always_approve=True)` 또는 `state.reject(..., always_reject=True)`를 사용합니다. 자동 결정의 경우 `on_approval`을 제공하고(`examples/tools/shell.py` 참고), 수동 결정의 경우 인터럽션(중단 처리)을 처리합니다(`examples/tools/shell_human_in_the_loop.py` 참고). 호스티드 shell 환경은 `needs_approval` 또는 `on_approval`을 지원하지 않습니다. [도구 가이드](tools.md)를 참고하세요. +- **로컬 MCP 서버**: MCP 도구 호출을 제한하려면 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp`에서 `require_approval`을 사용합니다(`examples/mcp/get_all_mcp_tools_example/main.py` 및 `examples/mcp/tool_filter_example/main.py` 참고). +- **호스티드 MCP 서버**: HITL을 강제하려면 `HostedMCPTool`에서 `require_approval`을 `"always"`로 설정하고, 선택적으로 자동 승인 또는 거부를 위해 `on_approval_request`를 제공합니다(`examples/hosted_mcp/human_in_the_loop.py` 및 `examples/hosted_mcp/on_approval.py` 참고). 신뢰할 수 있는 서버에는 `"never"`를 사용합니다(`examples/hosted_mcp/simple.py`). +- **세션 및 메모리**: 승인과 대화 기록이 여러 턴에 걸쳐 유지되도록 `Runner.run`에 세션을 전달합니다. SQLite 및 OpenAI Conversations 세션 변형은 `examples/memory/memory_session_hitl_example.py` 및 `examples/memory/openai_session_hitl_example.py`에 있습니다. +- **실시간 에이전트**: realtime 데모는 `RealtimeSession`의 `approve_tool_call` / `reject_tool_call`을 통해 도구 호출을 승인하거나 거부하는 WebSocket 메시지를 노출합니다(서버 측 핸들러는 `examples/realtime/app/server.py`, API 표면은 [Realtime 가이드](realtime/guide.md#tool-approvals) 참고). ## 장기 실행 승인 -`RunState`는 내구성을 고려해 설계되었습니다. 대기 작업을 데이터베이스나 큐에 저장하려면 `state.to_json()` 또는 `state.to_string()`을 사용하고, 나중에 `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 다시 생성하세요 +`RunState`는 내구성을 갖도록 설계되었습니다. `state.to_json()` 또는 `state.to_string()`을 사용해 대기 중인 작업을 데이터베이스나 큐에 저장하고, 나중에 `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 다시 생성합니다. 유용한 직렬화 옵션: -- `context_serializer`: 매핑이 아닌 컨텍스트 객체를 직렬화하는 방식을 사용자 지정합니다 -- `context_deserializer`: `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 상태를 불러올 때 매핑이 아닌 컨텍스트 객체를 재구성합니다 -- `strict_context=True`: 컨텍스트가 이미 매핑이거나 적절한 serializer/deserializer를 제공하지 않으면 직렬화 또는 역직렬화를 실패시킵니다 -- `context_override`: 상태를 불러올 때 직렬화된 컨텍스트를 대체합니다. 원래 컨텍스트 객체를 복원하지 않으려는 경우 유용하지만, 이미 직렬화된 페이로드에서 해당 컨텍스트를 제거하지는 않습니다 -- `include_tracing_api_key=True`: 재개된 작업이 동일한 자격 증명으로 트레이스를 계속 내보내야 할 때 직렬화된 트레이스 페이로드에 트레이싱 API 키를 포함합니다 +- `context_serializer`: 매핑이 아닌 컨텍스트 객체를 직렬화하는 방식을 사용자 지정합니다. +- `context_deserializer`: `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 상태를 로드할 때 매핑이 아닌 컨텍스트 객체를 다시 빌드합니다. +- `strict_context=True`: 컨텍스트가 이미 매핑이거나 적절한 직렬화기/역직렬화기를 제공하지 않는 한 직렬화 또는 역직렬화에 실패합니다. +- `context_override`: 상태를 로드할 때 직렬화된 컨텍스트를 교체합니다. 원래 컨텍스트 객체를 복원하고 싶지 않을 때 유용하지만, 이미 직렬화된 페이로드에서 해당 컨텍스트를 제거하지는 않습니다. +- `include_tracing_api_key=True`: 재개된 작업이 동일한 자격 증명으로 트레이스를 계속 내보내야 할 때 직렬화된 트레이스 페이로드에 트레이싱 API 키를 포함합니다. -직렬화된 실행 상태에는 앱 컨텍스트와 함께 승인, 사용량, 직렬화된 `tool_input`, 중첩 에이전트-as-tool 재개, 트레이스 메타데이터, 서버 관리 대화 설정 같은 SDK 관리 런타임 메타데이터가 포함됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 `RunContextWrapper.context`를 영속 데이터로 취급하고, 상태와 함께 이동시키려는 의도가 없는 한 비밀 정보를 그 안에 두지 마세요 +직렬화된 실행 상태에는 앱 컨텍스트와 함께 승인, 사용량, 직렬화된 `tool_input`, 중첩된 agent-as-tool 재개, 트레이스 메타데이터, 서버 관리 대화 설정과 같은 SDK 관리 런타임 메타데이터가 포함됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 `RunContextWrapper.context`를 영속화된 데이터로 취급하고, 해당 상태와 함께 이동하기를 의도한 경우가 아니라면 여기에 비밀 정보를 넣지 마세요. -## 대기 작업 버전 관리 +## 대기 중인 작업의 버전 관리 -승인이 한동안 대기 상태로 있을 수 있다면, 직렬화된 상태와 함께 에이전트 정의 또는 SDK의 버전 마커를 저장하세요. 그러면 모델, 프롬프트 또는 도구 정의가 바뀔 때 발생할 수 있는 비호환성을 피하기 위해 역직렬화를 일치하는 코드 경로로 라우팅할 수 있습니다 \ No newline at end of file +승인이 한동안 대기할 수 있다면, 직렬화된 상태와 함께 에이전트 정의 또는 SDK의 버전 마커를 저장합니다. 그러면 모델, 프롬프트 또는 도구 정의가 변경될 때 비호환성을 피하기 위해 역직렬화를 일치하는 코드 경로로 라우팅할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/index.md b/docs/ko/index.md index b729cb77c2..fe254d2f51 100644 --- a/docs/ko/index.md +++ b/docs/ko/index.md @@ -4,51 +4,51 @@ 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 -- **Agents as tools / 핸드오프**: 에이전트가 특정 작업을 다른 에이전트에 위임할 수 있게 해주는 기능 -- **가드레일**: 에이전트 입력과 출력의 유효성 검사를 가능하게 하는 기능 +- **에이전트**: instructions와 tools를 갖춘 LLM +- **Agents as tools / 핸드오프**: 에이전트가 특정 작업을 다른 에이전트에 위임할 수 있게 하는 기능 +- **가드레일**: 에이전트 입력과 출력을 검증할 수 있게 하는 기능 -Python과 함께 사용하면 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현할 수 있을 만큼 강력하며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버그할 수 있을 뿐 아니라, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수도 있는 내장 **트레이싱**이 포함되어 있습니다. +Python과 결합하면 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하기에 충분히 강력하며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버깅하며, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수 있는 내장 **트레이싱** 기능이 포함되어 있습니다. -## Agents SDK 사용 이유 +## Agents SDK를 사용하는 이유 SDK에는 두 가지 핵심 설계 원칙이 있습니다. -1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있을 만큼 기본 구성 요소를 적게 유지합니다. -2. 기본 설정만으로도 잘 작동하지만, 정확히 어떤 일이 일어나는지 원하는 대로 커스터마이즈할 수 있습니다. +1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있을 만큼 기본 구성 요소는 적게 유지합니다. +2. 기본 설정만으로도 잘 작동하지만, 어떤 일이 일어나는지는 정확하게 사용자 지정할 수 있습니다. SDK의 주요 기능은 다음과 같습니다. -- **에이전트 루프**: 도구 호출을 처리하고, 결과를 LLM에 다시 보내며, 작업이 완료될 때까지 계속 진행하는 내장 에이전트 루프 -- **Python-first**: 새로운 추상화를 배울 필요 없이, 내장 언어 기능을 사용해 에이전트를 오케스트레이션하고 체인으로 연결 +- **에이전트 루프**: 도구 호출을 처리하고, 결과를 LLM에 다시 보내며, 작업이 완료될 때까지 계속 실행하는 내장 에이전트 루프 +- **파이썬 우선**: 새로운 추상화를 배울 필요 없이, 내장 언어 기능을 사용해 에이전트를 오케스트레이션하고 체인으로 연결 - **Agents as tools / 핸드오프**: 여러 에이전트 간 작업을 조율하고 위임하기 위한 강력한 메커니즘 -- **샌드박스 에이전트**: 매니페스트로 정의된 파일, 샌드박스 클라이언트 선택, 재개 가능한 샌드박스 세션을 갖춘 실제 격리 워크스페이스에서 전문 에이전트 실행 -- **가드레일**: 에이전트 실행과 병렬로 입력 유효성 검사와 안전성 검사를 실행하고, 검사를 통과하지 못하면 빠르게 실패 처리 -- **함수 도구**: 자동 스키마 생성과 Pydantic 기반 검증을 통해 모든 Python 함수를 도구로 변환 +- **샌드박스 에이전트**: 매니페스트로 정의된 파일, 샌드박스 클라이언트 선택, 재개 가능한 샌드박스 세션을 통해 실제 격리된 워크스페이스 안에서 전문가 실행 +- **가드레일**: 에이전트 실행과 병렬로 입력 검증 및 안전성 검사를 실행하고, 검사를 통과하지 못하면 빠르게 실패 처리 +- **함수 도구**: 자동 스키마 생성 및 Pydantic 기반 검증을 통해 모든 Python 함수를 도구로 변환 - **MCP 서버 도구 호출**: 함수 도구와 동일한 방식으로 작동하는 내장 MCP 서버 도구 통합 -- **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 지속형 메모리 계층 +- **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 영속 메모리 계층 - **휴먼인더루프 (HITL)**: 에이전트 실행 전반에 사람을 참여시키기 위한 내장 메커니즘 -- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하기 위한 내장 트레이싱. OpenAI 평가, 파인튜닝, 증류 도구 모음 지원 포함 -- **실시간 에이전트**: `gpt-realtime-2`, 자동 인터럽션 감지, 컨텍스트 관리, 가드레일 등을 사용해 강력한 음성 에이전트 구축 +- **트레이싱**: OpenAI의 평가, 파인튜닝, 증류 도구 모음 지원과 함께 워크플로를 시각화, 디버깅, 모니터링하기 위한 내장 트레이싱 +- **실시간 에이전트**: `gpt-realtime-2`, 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 활용해 강력한 음성 에이전트 구축 ## Agents SDK 또는 Responses API -SDK는 기본적으로 OpenAI 모델에 Responses API를 사용하지만, 모델 호출 주변에 더 높은 수준의 런타임을 추가합니다. +SDK는 OpenAI 모델에 기본적으로 Responses API를 사용하지만, 모델 호출 주변에 더 높은 수준의 런타임을 추가합니다. 다음과 같은 경우 Responses API를 직접 사용하세요. -- 루프, 도구 디스패치, 상태 처리를 직접 소유하고 싶을 때 -- 워크플로가 짧게 끝나며 주로 모델의 응답을 반환하는 것이 목적일 때 +- 루프, 도구 디스패치, 상태 처리를 직접 관리하려는 경우 +- 워크플로가 짧게 실행되며 주로 모델의 응답을 반환하는 것이 목적인 경우 다음과 같은 경우 Agents SDK를 사용하세요. -- 런타임이 턴, 도구 실행, 가드레일, 핸드오프 또는 세션을 관리하기를 원할 때 -- 에이전트가 산출물을 생성하거나 여러 조율된 단계에 걸쳐 동작해야 할 때 -- 실제 워크스페이스 또는 [샌드박스 에이전트](sandbox_agents.md)를 통한 재개 가능한 실행이 필요할 때 +- 런타임이 턴, 도구 실행, 가드레일, 핸드오프 또는 세션을 관리하기를 원하는 경우 +- 에이전트가 아티팩트를 생성하거나 여러 조율된 단계에 걸쳐 동작해야 하는 경우 +- 실제 워크스페이스나 [샌드박스 에이전트](sandbox_agents.md)를 통한 재개 가능한 실행이 필요한 경우 -하나를 전역적으로 선택할 필요는 없습니다. 많은 애플리케이션은 관리형 워크플로에는 SDK를 사용하고, 더 낮은 수준의 경로에는 Responses API를 직접 호출합니다. +둘 중 하나를 전역적으로 선택할 필요는 없습니다. 많은 애플리케이션은 관리형 워크플로에는 SDK를 사용하고, 더 낮은 수준의 경로에는 Responses API를 직접 호출합니다. ## 설치 @@ -79,23 +79,23 @@ export OPENAI_API_KEY=sk-... ## 시작 지점 -- [Quickstart](quickstart.md)를 통해 첫 텍스트 기반 에이전트를 만드세요. -- 그런 다음 [Running agents](running_agents.md#choose-a-memory-strategy)에서 턴 간 상태를 어떻게 유지할지 결정하세요. -- 작업이 실제 파일, 저장소 또는 에이전트별 격리 워크스페이스 상태에 의존한다면 [샌드박스 에이전트 퀵스타트](sandbox_agents.md)를 읽어보세요. -- 핸드오프와 매니저 스타일 오케스트레이션 중에서 결정하고 있다면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. +- [빠른 시작](quickstart.md)으로 첫 텍스트 기반 에이전트를 구축하세요. +- 그런 다음 [에이전트 실행](running_agents.md#choose-a-memory-strategy)에서 턴 간 상태를 어떻게 유지할지 결정하세요. +- 작업이 실제 파일, 리포지토리 또는 에이전트별 격리된 워크스페이스 상태에 의존한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)을 읽어 보세요. +- 핸드오프와 매니저 스타일 오케스트레이션 중에서 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어 보세요. ## 경로 선택 -수행하려는 작업은 알지만 어느 페이지에서 설명하는지 모를 때 이 표를 사용하세요. +하려는 작업은 알고 있지만 어느 페이지에서 설명하는지 모를 때 이 표를 사용하세요. | 목표 | 시작 지점 | | --- | --- | -| 첫 텍스트 에이전트를 만들고 한 번의 전체 실행 확인 | [Quickstart](quickstart.md) | -| 함수 도구, 호스티드 툴 또는 Agents as tools 추가 | [Tools](tools.md) | -| 실제 격리 워크스페이스 안에서 코딩, 리뷰 또는 문서 에이전트 실행 | [샌드박스 에이전트 퀵스타트](sandbox_agents.md) 및 [샌드박스 클라이언트](sandbox/clients.md) | -| 핸드오프와 매니저 스타일 오케스트레이션 중 결정 | [에이전트 오케스트레이션](multi_agent.md) | -| 턴 간 메모리 유지 | [Running agents](running_agents.md#choose-a-memory-strategy) 및 [Sessions](sessions/index.md) | -| OpenAI 모델, websocket 전송 또는 OpenAI 외 제공업체 사용 | [Models](models/index.md) | -| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토 | [Results](results.md) | -| `gpt-realtime-2`로 저지연 음성 에이전트 구축 | [실시간 에이전트 퀵스타트](realtime/quickstart.md) 및 [실시간 전송](realtime/transport.md) | -| 음성-텍스트 / 에이전트 / 텍스트-음성 파이프라인 구축 | [음성 파이프라인 퀵스타트](voice/quickstart.md) | \ No newline at end of file +| 첫 텍스트 에이전트를 만들고 전체 실행 한 번 확인 | [빠른 시작](quickstart.md) | +| 함수 도구, 호스티드 툴 또는 agents as tools 추가 | [도구](tools.md) | +| 실제 격리된 워크스페이스 안에서 코딩, 리뷰 또는 문서 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) 및 [샌드박스 클라이언트](sandbox/clients.md) | +| 핸드오프와 매니저 스타일 오케스트레이션 중에서 결정 | [에이전트 오케스트레이션](multi_agent.md) | +| 턴 간 메모리 유지 | [에이전트 실행](running_agents.md#choose-a-memory-strategy) 및 [세션](sessions/index.md) | +| OpenAI 모델, 웹소켓 전송 또는 비 OpenAI 제공자 사용 | [모델](models/index.md) | +| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토 | [결과](results.md) | +| `gpt-realtime-2`로 지연 시간이 낮은 음성 에이전트 구축 | [실시간 에이전트 빠른 시작](realtime/quickstart.md) 및 [실시간 전송](realtime/transport.md) | +| 음성-텍스트 변환 / 에이전트 / 텍스트-음성 변환 파이프라인 구축 | [음성 파이프라인 빠른 시작](voice/quickstart.md) | \ No newline at end of file diff --git a/docs/ko/mcp.md b/docs/ko/mcp.md index 4015b89666..5aa13bb042 100644 --- a/docs/ko/mcp.md +++ b/docs/ko/mcp.md @@ -4,30 +4,32 @@ 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 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방식을 제공합니다. +> 애플리케이션용 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 서버를 호출하도록 하기| [`HostedMCPTool`][agents.tool.HostedMCPTool]을 통한 **호스티드 MCP 서버 도구** | +| OpenAI의 Responses API가 모델을 대신해 공개적으로 접근 가능한 MCP 서버를 호출하도록 하기| [`HostedMCPTool`][agents.tool.HostedMCPTool]을 통한 **Hosted MCP server tools** | | 로컬 또는 원격에서 실행하는 Streamable HTTP 서버에 연결하기 | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 통한 **Streamable HTTP MCP 서버** | -| Server-Sent Events를 사용해 HTTP를 구현한 서버와 통신하기 | [`MCPServerSse`][agents.mcp.server.MCPServerSse]를 통한 **SSE 포함 HTTP MCP 서버** | -| 로컬 프로세스를 시작하고 stdin/stdout으로 통신하기 | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 통한 **stdio MCP 서버** | +| Server-Sent Events를 사용하는 HTTP를 구현한 서버와 통신하기 | [`MCPServerSse`][agents.mcp.server.MCPServerSse]를 통한 **SSE 사용 HTTP MCP 서버** | +| 로컬 프로세스를 시작하고 stdin/stdout을 통해 통신하기 | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 통한 **stdio MCP 서버** | -아래 섹션에서는 각 옵션, 구성 방법, 어떤 경우에 특정 전송 방식을 선호해야 하는지 설명합니다. +아래 섹션에서는 각 옵션, 구성 방법, 그리고 어떤 경우에 특정 전송 방식을 선호해야 하는지 설명합니다. ## 에이전트 수준 MCP 구성 -전송 방식을 선택하는 것 외에도 `Agent.mcp_config`를 설정해 MCP 도구가 준비되는 방식을 조정할 수 있습니다. +전송 방식을 선택하는 것 외에도 `Agent.mcp_config`를 설정하여 MCP 도구가 준비되는 방식을 조정할 수 있습니다. ```python from agents import Agent @@ -49,33 +51,34 @@ agent = Agent( 참고: -- `convert_schemas_to_strict`는 최선 노력 방식입니다. 스키마를 변환할 수 없으면 원래 스키마가 사용됩니다. +- `convert_schemas_to_strict`는 최선의 방식으로 동작합니다. 스키마를 변환할 수 없으면 원래 스키마가 사용됩니다. - `failure_error_function`은 MCP 도구 호출 실패가 모델에 표시되는 방식을 제어합니다. - `failure_error_function`이 설정되지 않은 경우 SDK는 기본 도구 오류 포매터를 사용합니다. -- 서버 수준 `failure_error_function`은 해당 서버에 대해 `Agent.mcp_config["failure_error_function"]`를 재정의합니다. -- `include_server_in_tool_names`는 옵트인 방식입니다. 활성화하면 각 로컬 MCP 도구가 결정적 서버 접두사 이름과 함께 모델에 노출되며, 여러 MCP 서버가 같은 이름의 도구를 게시할 때 충돌을 피하는 데 도움이 됩니다. 생성된 이름은 ASCII에 안전하고, 함수 도구 이름 길이 제한 내에 있으며, 동일한 에이전트의 기존 로컬 함수 도구와 활성화된 핸드오프 이름을 피합니다. SDK는 여전히 원래 서버에서 원래 MCP 도구 이름을 호출합니다. +- 서버 수준의 `failure_error_function`은 해당 서버에 대해 `Agent.mcp_config["failure_error_function"]`을 재정의합니다. +- `include_server_in_tool_names`는 명시적으로 선택해야 합니다. 활성화하면 각 로컬 MCP 도구가 결정론적인 서버 접두사 이름으로 모델에 노출되어, 여러 MCP 서버가 같은 이름의 도구를 게시할 때 충돌을 방지하는 데 도움이 됩니다. 생성된 이름은 ASCII에 안전하며, 함수 도구 이름 길이 제한 내에 유지되고, 동일한 에이전트의 기존 로컬 함수 도구 및 활성화된 핸드오프 이름을 피합니다. SDK는 여전히 원래 서버에서 원래 MCP 도구 이름을 호출합니다. -## 전송 방식 간 공통 패턴 +## 전송 방식 전반의 공통 패턴 -전송 방식을 선택한 뒤에는 대부분의 통합에서 동일한 후속 결정을 내려야 합니다. +전송 방식을 선택한 후에는 대부분의 통합에서 동일한 후속 결정을 내려야 합니다: -- 일부 도구만 노출하는 방법([도구 필터링](#tool-filtering)). +- 도구의 일부만 노출하는 방법([도구 필터링](#tool-filtering)). - 서버가 재사용 가능한 프롬프트도 제공하는지 여부([프롬프트](#prompts)). - `list_tools()`를 캐시해야 하는지 여부([캐싱](#caching)). - MCP 활동이 트레이스에 표시되는 방식([트레이싱](#tracing)). -로컬 MCP 서버(`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`)의 경우 승인 정책과 호출별 `_meta` 페이로드도 공통 개념입니다. Streamable HTTP 섹션에는 가장 완전한 예제가 있으며, 동일한 패턴이 다른 로컬 전송 방식에도 적용됩니다. +로컬 MCP 서버(`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`)의 경우 승인 정책과 호출별 `_meta` 페이로드도 공통 개념입니다. Streamable HTTP 섹션에서 가장 완전한 예를 보여 주며, 동일한 패턴은 다른 로컬 전송 방식에도 적용됩니다. -## 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 도구 -[`HostedMCPTool`][agents.tool.HostedMCPTool]를 에이전트의 `tools` 목록에 추가하여 호스티드 툴을 만듭니다. `tool_config` -dict는 REST API로 보낼 JSON을 그대로 반영합니다. +[`HostedMCPTool`][agents.tool.HostedMCPTool]을 에이전트의 `tools` 목록에 추가하여 호스티드 툴을 만듭니다. `tool_config` +dict는 REST API로 보낼 JSON과 동일한 구조입니다: ```python import asyncio @@ -109,11 +112,12 @@ asyncio.run(main()) 호스티드 서버는 도구를 자동으로 노출하므로 `mcp_servers`에 추가하지 않습니다. -호스티드 도구 검색이 호스티드 MCP 서버를 지연 로드하도록 하려면 `tool_config["defer_loading"] = True`를 설정하고 [`ToolSearchTool`][agents.tool.ToolSearchTool]를 에이전트에 추가하세요. 이는 OpenAI Responses 모델에서만 지원됩니다. 전체 도구 검색 설정과 제약 조건은 [도구](tools.md#hosted-tool-search)를 참조하세요. +호스티드 툴 검색이 호스티드 MCP 서버를 지연 로드하도록 하려면 `tool_config["defer_loading"] = True`를 설정하고 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 에이전트에 추가하세요. 이는 OpenAI Responses 모델에서만 지원됩니다. 전체 도구 검색 설정 및 제약 조건은 [도구](tools.md#hosted-tool-search)를 참고하세요. ### 호스티드 MCP 결과 스트리밍 -호스티드 툴은 함수 도구와 정확히 같은 방식으로 스트리밍 결과를 지원합니다. 모델이 아직 작업 중인 동안 증분 MCP 출력을 소비하려면 `Runner.run_streamed`를 사용하세요. +호스티드 툴은 함수 도구와 정확히 같은 방식으로 결과 스트리밍을 지원합니다. 모델이 아직 작업 중일 때 +증분 MCP 출력을 소비하려면 `Runner.run_streamed`를 사용하세요: ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -125,7 +129,9 @@ 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 @@ -153,11 +159,12 @@ agent = Agent( ) ``` -콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행하기 위해 승인 데이터가 필요할 때마다 호출됩니다. +콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행되기 위해 승인 데이터가 필요할 때마다 호출됩니다. ### 커넥터 기반 호스티드 서버 -호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다. +호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. +Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다. ```python import os @@ -173,13 +180,14 @@ HostedMCPTool( ) ``` -스트리밍, 승인, 커넥터를 포함한 완전히 작동하는 호스티드 툴 샘플은 +스트리밍, 승인, 커넥터를 포함해 완전히 동작하는 호스티드 툴 샘플은 [`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 @@ -214,14 +222,14 @@ async def main() -> None: asyncio.run(main()) ``` -생성자는 추가 옵션을 받습니다. +생성자는 추가 옵션을 받습니다: -- `client_session_timeout_seconds`는 HTTP 읽기 제한 시간을 제어합니다. -- `use_structured_content`는 텍스트 출력보다 `tool_result.structured_content`를 선호할지 여부를 전환합니다. +- `client_session_timeout_seconds`는 HTTP 읽기 타임아웃을 제어합니다. +- `use_structured_content`는 텍스트 출력보다 `tool_result.structured_content`를 우선할지 여부를 전환합니다. - `max_retry_attempts`와 `retry_backoff_seconds_base`는 `list_tools()` 및 `call_tool()`에 자동 재시도를 추가합니다. -- `tool_filter`를 사용하면 일부 도구만 노출할 수 있습니다([도구 필터링](#tool-filtering) 참조). -- `require_approval`은 로컬 MCP 도구에 휴먼인더루프(HITL) 승인 정책을 활성화합니다. -- `failure_error_function`은 모델에 표시되는 MCP 도구 실패 메시지를 사용자 지정합니다. 오류를 발생시키려면 `None`으로 설정하세요. +- `tool_filter`를 사용하면 도구의 일부만 노출할 수 있습니다([도구 필터링](#tool-filtering) 참고). +- `require_approval`은 로컬 MCP 도구에 대한 휴먼인더루프 (HITL) 승인 정책을 활성화합니다. +- `failure_error_function`은 모델에 표시되는 MCP 도구 실패 메시지를 사용자 지정합니다. 대신 오류를 발생시키려면 `None`으로 설정하세요. - `tool_meta_resolver`는 `call_tool()` 전에 호출별 MCP `_meta` 페이로드를 주입합니다. ### 로컬 MCP 서버의 승인 정책 @@ -230,9 +238,9 @@ asyncio.run(main()) 지원되는 형식: -- 모든 도구에 대해 `"always"` 또는 `"never"` -- `True` / `False`(항상/절대와 동일) -- 도구별 맵, 예: `{"delete_file": "always", "read_file": "never"}` +- 모든 도구에 대해 `"always"` 또는 `"never"`. +- `True` / `False`(always/never와 동일). +- 도구별 맵, 예: `{"delete_file": "always", "read_file": "never"}`. - 그룹화된 객체: `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`. @@ -245,11 +253,11 @@ async with MCPServerStreamableHttp( ... ``` -전체 일시 중지/재개 흐름은 [휴먼인더루프(HITL)](human_in_the_loop.md)와 `examples/mcp/get_all_mcp_tools_example/main.py`를 참조하세요. +전체 일시 중지/재개 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md) 및 `examples/mcp/get_all_mcp_tools_example/main.py`를 참고하세요. ### `tool_meta_resolver`를 사용한 호출별 메타데이터 -MCP 서버가 `_meta`에 요청 메타데이터(예: 테넌트 ID 또는 트레이스 컨텍스트)를 기대하는 경우 `tool_meta_resolver`를 사용하세요. 아래 예제는 `Runner.run(...)`에 `context`로 `dict`를 전달한다고 가정합니다. +MCP 서버가 `_meta`에 요청 메타데이터(예: 테넌트 ID 또는 트레이스 컨텍스트)를 기대하는 경우 `tool_meta_resolver`를 사용하세요. 아래 예에서는 `Runner.run(...)`에 `context`로 `dict`를 전달한다고 가정합니다. ```python from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext @@ -272,17 +280,17 @@ server = MCPServerStreamableHttp( 실행 컨텍스트가 Pydantic 모델, dataclass 또는 사용자 지정 클래스인 경우 속성 접근으로 테넌트 ID를 읽으세요. -### MCP 도구 출력: 텍스트와 이미지 +### MCP 도구 출력: 텍스트 및 이미지 -MCP 도구가 이미지 콘텐츠를 반환하면 SDK는 이를 이미지 도구 출력 항목에 자동으로 매핑합니다. 혼합 텍스트/이미지 응답은 출력 항목 목록으로 전달되므로, 에이전트는 일반 함수 도구의 이미지 출력을 소비하는 것과 동일한 방식으로 MCP 이미지 결과를 소비할 수 있습니다. +MCP 도구가 이미지 콘텐츠를 반환하면 SDK가 이를 이미지 도구 출력 항목으로 자동 매핑합니다. 텍스트/이미지 혼합 응답은 출력 항목 목록으로 전달되므로, 에이전트는 일반 함수 도구의 이미지 출력을 소비하는 것과 같은 방식으로 MCP 이미지 결과를 소비할 수 있습니다. -## 3. SSE 포함 HTTP MCP 서버 +## 3. SSE 사용 HTTP MCP 서버 !!! warning - MCP 프로젝트는 Server-Sent Events 전송 방식을 더 이상 사용하지 않도록 했습니다. 새 통합에는 Streamable HTTP 또는 stdio를 선호하고, SSE는 레거시 서버에만 유지하세요. + MCP 프로젝트는 Server-Sent Events 전송 방식을 더 이상 권장하지 않습니다. 새 통합에는 Streamable HTTP 또는 stdio를 선호하고, SSE는 레거시 서버에만 유지하세요. -MCP 서버가 SSE 포함 HTTP 전송 방식을 구현하는 경우 +MCP 서버가 SSE 사용 HTTP 전송 방식을 구현하는 경우 [`MCPServerSse`][agents.mcp.server.MCPServerSse]를 인스턴스화하세요. 전송 방식을 제외하면 API는 Streamable HTTP 서버와 동일합니다. ```python @@ -312,7 +320,9 @@ 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 @@ -340,7 +350,7 @@ async with MCPServerStdio( ## 5. MCP 서버 관리자 -MCP 서버가 여러 개 있는 경우 `MCPServerManager`를 사용해 미리 연결하고, 연결된 하위 집합을 에이전트에 노출하세요. +여러 MCP 서버가 있는 경우 `MCPServerManager`를 사용하여 미리 연결하고 연결된 하위 집합을 에이전트에 노출하세요. 생성자 옵션과 재연결 동작은 [MCPServerManager API 참조](ref/mcp/manager.md)를 확인하세요. ```python @@ -364,23 +374,24 @@ async with MCPServerManager(servers) as manager: 주요 동작: -- `active_servers`에는 `drop_failed_servers=True`(기본값)일 때 성공적으로 연결된 서버만 포함됩니다. +- `drop_failed_servers=True`(기본값)인 경우 `active_servers`에는 성공적으로 연결된 서버만 포함됩니다. - 실패는 `failed_servers`와 `errors`에 추적됩니다. -- 첫 번째 연결 실패에서 오류를 발생시키려면 `strict=True`를 설정하세요. +- 첫 번째 연결 실패 시 오류를 발생시키려면 `strict=True`를 설정하세요. - 실패한 서버를 다시 시도하려면 `reconnect(failed_only=True)`를 호출하고, 모든 서버를 다시 시작하려면 `reconnect(failed_only=False)`를 호출하세요. - 수명 주기 동작을 조정하려면 `connect_timeout_seconds`, `cleanup_timeout_seconds`, `connect_in_parallel`을 사용하세요. ## 공통 서버 기능 -아래 섹션은 MCP 서버 전송 방식 전반에 적용됩니다(정확한 API 표면은 서버 클래스에 따라 달라집니다). +아래 섹션은 MCP 서버 전송 방식 전반에 적용됩니다(정확한 API 표면은 서버 클래스에 따라 다름). ## 도구 필터링 -각 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 @@ -398,11 +409,13 @@ filesystem_server = MCPServerStdio( ) ``` -`allowed_tool_names`와 `blocked_tool_names`가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서 차단된 도구를 제거합니다. +`allowed_tool_names`와 `blocked_tool_names`가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서 +차단된 도구를 제거합니다. ### 동적 도구 필터링 -더 정교한 로직에는 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 callable을 전달하세요. callable은 동기 또는 비동기일 수 있으며, 도구가 노출되어야 할 때 `True`를 반환합니다. +더 정교한 로직이 필요하면 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 콜러블을 전달하세요. 이 콜러블은 +동기 또는 비동기일 수 있으며, 도구가 노출되어야 하는 경우 `True`를 반환합니다. ```python from pathlib import Path @@ -430,10 +443,11 @@ async with MCPServerStdio( ## 프롬프트 -MCP 서버는 에이전트 instructions를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 메서드를 노출합니다. +MCP 서버는 에이전트 지침을 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지 +메서드를 노출합니다: - `list_prompts()`는 사용 가능한 프롬프트 템플릿을 열거합니다. -- `get_prompt(name, arguments)`는 선택적으로 매개변수를 사용해 구체적인 프롬프트를 가져옵니다. +- `get_prompt(name, arguments)`는 선택적으로 매개변수를 포함해 구체적인 프롬프트를 가져옵니다. ```python from agents import Agent @@ -453,19 +467,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/) – 사양 및 설계 가이드 -- [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 데모 +- [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 b3cd1afd43..ebdb3f3e81 100644 --- a/docs/ko/models/index.md +++ b/docs/ko/models/index.md @@ -4,35 +4,35 @@ search: --- # 모델 -Agents SDK는 OpenAI 모델을 두 가지 방식으로 기본 지원합니다. +Agents SDK는 두 가지 방식으로 OpenAI 모델을 기본 지원합니다. -- **권장**: 새 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] -- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] +- **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용하여 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 모델만 사용 | 기본 OpenAI provider를 Responses 모델 경로와 함께 사용 | [OpenAI 모델](#openai-models) | -| websocket transport로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket transport 활성화 | [Responses WebSocket transport](#responses-websocket-transport) | -| 하나의 비 OpenAI provider 사용 | 내장 provider 통합 지점부터 시작 | [비 OpenAI 모델](#non-openai-models) | -| 에이전트 간 모델 또는 provider 혼합 | 실행별 또는 에이전트별로 provider를 선택하고 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [provider 간 모델 혼합](#mixing-models-across-providers) | +| OpenAI 모델만 사용 | Responses 모델 경로와 함께 기본 OpenAI 프로바이더 사용 | [OpenAI 모델](#openai-models) | +| websocket 전송으로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket 전송 활성화 | [Responses WebSocket 전송](#responses-websocket-transport) | +| 하나의 비 OpenAI 프로바이더 사용 | 내장 프로바이더 통합 지점부터 시작 | [비 OpenAI 모델](#non-openai-models) | +| 에이전트 간 모델 또는 프로바이더 혼합 | 실행별 또는 에이전트별로 프로바이더를 선택하고 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [프로바이더 간 모델 혼합](#mixing-models-across-providers) | | 고급 OpenAI Responses 요청 설정 조정 | OpenAI Responses 경로에서 `ModelSettings` 사용 | [고급 OpenAI Responses 설정](#advanced-openai-responses-settings) | -| 비 OpenAI 또는 혼합 provider 라우팅을 위한 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 배포하려는 provider 경로 검증 | [서드파티 어댑터](#third-party-adapters) | +| 비 OpenAI 또는 혼합 프로바이더 라우팅을 위한 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 배포하려는 프로바이더 경로 검증 | [서드파티 어댑터](#third-party-adapters) | ## OpenAI 모델 -대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider와 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것이 권장됩니다. +대부분의 OpenAI 전용 앱에서는 기본 OpenAI 프로바이더와 함께 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것이 권장됩니다. -`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 지연 시간이 짧은 에이전트 워크플로를 위해 `reasoning.effort="none"` 및 `verbosity="low"`가 설정된 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)입니다. 액세스 권한이 있다면, 명시적인 `model_settings`를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하는 것을 권장합니다. +`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 지연 시간이 낮은 에이전트 워크플로를 위해 `reasoning.effort="none"` 및 `verbosity="low"`가 적용된 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)입니다. 접근 권한이 있다면 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하되 명시적인 `model_settings`를 유지하는 것을 권장합니다. -[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법이 두 가지 있습니다. +[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면 두 가지 방법으로 에이전트를 구성할 수 있습니다. ### 기본 모델 -첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +첫째, 사용자 지정 모델을 설정하지 않는 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```bash export OPENAI_DEFAULT_MODEL=gpt-5.5 @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 모델 -이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)와 같은 GPT-5 모델을 사용하면 SDK가 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 설정이 적용됩니다. 기본 모델의 reasoning effort를 조정하려면 직접 `ModelSettings`를 전달하세요. +이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 GPT-5 모델을 사용하면 SDK는 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 값을 설정합니다. 기본 모델의 추론 노력을 조정하려면 직접 만든 `ModelSettings`를 전달하세요. ```python from openai.types.shared import Reasoning @@ -74,17 +74,17 @@ my_agent = Agent( ) ``` -더 낮은 지연 시간을 위해서는 GPT-5 모델에서 `reasoning.effort="none"`을 사용하는 것이 권장됩니다. +지연 시간을 낮추려면 GPT-5 모델에 `reasoning.effort="none"`을 사용하는 것이 권장됩니다. #### ComputerTool 모델 선택 -에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함된 경우 실제 Responses 요청의 유효 모델이 SDK가 전송하는 computer-tool payload를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` payload를 유지합니다. +에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함되어 있으면 실제 Responses 요청에서 유효한 모델이 SDK가 전송하는 컴퓨터 도구 페이로드를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` 페이로드를 유지합니다. -프롬프트가 관리하는 호출이 주요 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않기 위해 preview 호환 computer payload를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA selector를 강제하세요. +프롬프트 관리형 호출은 주요 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않도록 프리뷰 호환 컴퓨터 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하세요. -등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효 요청 모델과 일치하는 내장 selector로 정규화됩니다. 등록된 `ComputerTool`이 없으면 해당 문자열은 일반 함수 이름처럼 계속 동작합니다. +등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효한 요청 모델과 일치하는 내장 선택자로 정규화됩니다. `ComputerTool`이 등록되어 있지 않으면 이러한 문자열은 일반 함수 이름처럼 계속 동작합니다. -Preview 호환 요청은 `environment`와 display dimensions를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] factory를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA selector를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요. +프리뷰 호환 요청은 `environment`와 표시 크기를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리형 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA 선택자를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요. #### 비 GPT-5 모델 @@ -98,11 +98,11 @@ Preview 호환 요청은 `environment`와 display dimensions를 미리 직렬화 - [`tool_namespace()`][agents.tool.tool_namespace] - `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면 -이 기능들은 Chat Completions 모델 및 비 Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, bare namespace 이름이나 지연 전용 함수 이름을 강제하지 말고 모델이 `auto` 또는 `required` tool choice를 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요. +이러한 기능은 Chat Completions 모델과 비 Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 단순 네임스페이스 이름이나 지연 전용 함수 이름을 강제로 지정하는 대신 모델이 `auto` 또는 `required` 도구 선택을 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요. -### Responses WebSocket transport +### Responses WebSocket 전송 -기본적으로 OpenAI Responses API 요청은 HTTP transport를 사용합니다. OpenAI 기반 모델을 사용할 때 websocket transport를 선택할 수 있습니다. +기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델을 사용할 때 websocket 전송을 선택적으로 사용할 수 있습니다. #### 기본 설정 @@ -112,13 +112,13 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -이는 기본 OpenAI provider가 확인한 OpenAI Responses 모델(`"gpt-5.5"` 같은 문자열 모델 이름 포함)에 영향을 줍니다. +이는 기본 OpenAI 프로바이더가 해석하는 OpenAI Responses 모델에 영향을 줍니다(`"gpt-5.5"` 같은 문자열 모델 이름 포함). -Transport 선택은 SDK가 모델 이름을 모델 인스턴스로 확인할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 transport는 이미 고정되어 있습니다. [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket을 사용하고, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP를 사용하며, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions에 남아 있습니다. `RunConfig(model_provider=...)`를 전달하면 전역 기본값 대신 해당 provider가 transport 선택을 제어합니다. +전송 선택은 SDK가 모델 이름을 모델 인스턴스로 해석할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 전송은 이미 고정되어 있습니다. [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket을 사용하고, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP를 사용하며, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions를 유지합니다. `RunConfig(model_provider=...)`를 전달하면 전역 기본값 대신 해당 프로바이더가 전송 선택을 제어합니다. -#### Provider 또는 실행 수준 설정 +#### 프로바이더 또는 실행 수준 설정 -Provider별 또는 실행별로 websocket transport를 구성할 수도 있습니다. +프로바이더별 또는 실행별로 websocket 전송을 구성할 수도 있습니다. ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -OpenAI 기반 provider는 선택적인 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정에서 harness ID 같은 provider 수준 등록 메타데이터가 필요한 경우를 위한 고급 옵션입니다. +OpenAI 기반 프로바이더는 선택적 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정이 하니스 ID 같은 프로바이더 수준 등록 메타데이터를 기대하는 경우를 위한 고급 옵션입니다. ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### `MultiProvider`를 사용한 고급 라우팅 -prefix 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 여기에 `openai_use_responses_websocket=True`를 설정하세요. +접두사 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...` 및 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 그곳에서 `openai_use_responses_websocket=True`를 설정하세요. `MultiProvider`는 두 가지 기존 기본값을 유지합니다. -- `openai/...`는 OpenAI provider의 별칭으로 처리되므로 `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다. -- 알 수 없는 prefix는 그대로 전달되지 않고 `UserError`를 발생시킵니다. +- `openai/...`는 OpenAI 프로바이더의 별칭으로 처리되므로 `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다. +- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError`를 발생시킵니다. -OpenAI provider가 literal namespaced 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키도록 할 때는 pass-through 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요. +OpenAI 프로바이더가 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키는 경우, 패스스루 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요. ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,37 +198,37 @@ result = await Runner.run( ) ``` -백엔드가 literal `openai/...` 문자열을 기대할 때 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 namespaced 모델 ID를 기대할 때는 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket transport 외부의 `MultiProvider`에서도 작동합니다. 이 예제는 이 섹션에서 설명하는 transport 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다. +백엔드가 리터럴 `openai/...` 문자열을 기대하는 경우 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대하는 경우 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket 전송 외부의 `MultiProvider`에서도 작동합니다. 이 예제에서는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다. -`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요한 경우 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 내부 OpenAI provider로 전달됩니다. +`MultiProvider`를 통해 라우팅하면서 동일한 프로바이더 수준 등록 메타데이터가 필요한 경우 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 기본 OpenAI 프로바이더로 전달됩니다. -사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우 websocket transport에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다. +사용자 지정 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우 websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다. #### 참고 사항 -- 이는 websocket transport를 통한 Responses API이지 [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 비 OpenAI provider에는 적용되지 않습니다. 단, 이들이 Responses websocket `/responses` 엔드포인트를 지원하는 경우는 예외입니다. -- 환경에 `websockets` 패키지가 아직 없다면 설치하세요. -- websocket transport를 활성화한 직후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 턴 간(및 중첩된 agent-as-tool 호출 간) 동일한 websocket 연결을 재사용하려는 멀티턴 워크플로에서는 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼가 권장됩니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참조하세요. -- 긴 reasoning 턴이나 지연 시간 급증이 있는 네트워크에서는 `responses_websocket_options`로 websocket keepalive 동작을 사용자 지정하세요. 지연된 pong 프레임을 허용하려면 `ping_timeout`을 늘리거나, ping은 활성화한 채 heartbeat timeout을 비활성화하려면 `ping_timeout=None`을 설정하세요. websocket 지연 시간보다 신뢰성이 더 중요한 경우 HTTP/SSE transport를 선호하세요. +- 이것은 [Realtime API](../realtime/guide.md)가 아니라 websocket 전송을 통한 Responses API입니다. Chat Completions나 비 OpenAI 프로바이더에는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 한 적용되지 않습니다. +- 환경에 아직 없다면 `websockets` 패키지를 설치하세요. +- websocket 전송을 활성화한 후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 여러 턴의 워크플로에서 같은 websocket 연결을 여러 턴(및 중첩된 agent-as-tool 호출)에 걸쳐 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼가 권장됩니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참조하세요. +- 긴 추론 턴이나 지연 시간 급증이 있는 네트워크의 경우 `responses_websocket_options`로 websocket keepalive 동작을 사용자 지정하세요. 지연된 pong 프레임을 허용하려면 `ping_timeout`을 늘리거나, ping은 활성화한 상태로 heartbeat 시간 제한을 비활성화하려면 `ping_timeout=None`을 설정하세요. websocket 지연 시간보다 안정성이 더 중요한 경우 HTTP/SSE 전송을 선호하세요. ## 비 OpenAI 모델 -비 OpenAI provider가 필요하다면 SDK의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 이것으로 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다. +비 OpenAI 프로바이더가 필요한 경우 SDK의 내장 프로바이더 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 이것만으로 충분합니다. 각 패턴의 코드 예제는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다. -### 비 OpenAI provider 통합 방법 +### 비 OpenAI 프로바이더 통합 방법 | 접근 방식 | 사용 시점 | 범위 | | --- | --- | --- | -| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트가 대부분 또는 모든 에이전트의 기본값이어야 할 때 | 전역 기본값 | -| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider가 단일 실행에 적용되어야 할 때 | 실행별 | -| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트가 서로 다른 provider 또는 구체적인 모델 객체를 필요로 할 때 | 에이전트별 | -| 서드파티 어댑터 | 내장 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요할 때 | [서드파티 어댑터](#third-party-adapters) 참조 | +| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트가 대부분 또는 모든 에이전트의 기본값이어야 하는 경우 | 전역 기본값 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 프로바이더가 단일 실행에 적용되어야 하는 경우 | 실행별 | +| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 프로바이더 또는 구체적인 모델 객체가 필요한 경우 | 에이전트별 | +| 서드파티 어댑터 | 내장 경로가 제공하지 않는 어댑터 관리형 프로바이더 범위 또는 라우팅이 필요한 경우 | [서드파티 어댑터](#third-party-adapters) 참조 | -다음 내장 경로를 통해 다른 LLM provider를 통합할 수 있습니다. +다음 내장 경로를 사용하여 다른 LLM 프로바이더를 통합할 수 있습니다. -1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역 사용하려는 경우에 유용합니다. 이는 LLM provider에 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` 수준에 있습니다. 이를 통해 “이 실행의 모든 에이전트에 사용자 지정 모델 provider를 사용”하도록 지정할 수 있습니다. 구성 가능한 예시는 [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 인스턴스에 모델을 지정할 수 있습니다. 이를 통해 서로 다른 에이전트에 서로 다른 provider를 혼합해 사용할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)를 참조하세요. +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)를 참조하세요. `platform.openai.com`의 API 키가 없는 경우 `set_tracing_disabled()`를 통해 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다. @@ -245,19 +245,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - 이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문입니다. 사용 중인 LLM provider가 이를 지원한다면 Responses 사용을 권장합니다. + 이 예제들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM 프로바이더가 아직 Responses API를 지원하지 않기 때문입니다. 사용 중인 LLM 프로바이더가 이를 지원한다면 Responses 사용을 권장합니다. ## 하나의 워크플로에서 모델 혼합 -단일 워크플로 내에서 각 에이전트에 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 triage에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 성능이 좋은 모델을 사용할 수 있습니다. [`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 @@ -290,7 +290,7 @@ async def main(): print(result.final_output) ``` -1. OpenAI 모델의 이름을 직접 설정합니다. +1. OpenAI 모델 이름을 직접 설정합니다. 2. [`Model`][agents.models.interface.Model] 구현을 제공합니다. 에이전트에 사용되는 모델을 더 세부적으로 구성하려면 temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다. @@ -312,16 +312,16 @@ OpenAI Responses 경로를 사용 중이고 더 많은 제어가 필요하다면 ### 일반적인 고급 `ModelSettings` 옵션 -OpenAI Responses API를 사용할 때는 여러 요청 필드에 이미 직접 대응되는 `ModelSettings` 필드가 있으므로, 해당 필드에는 `extra_args`가 필요하지 않습니다. +OpenAI Responses API를 사용할 때 여러 요청 필드는 이미 직접적인 `ModelSettings` 필드를 갖고 있으므로 해당 필드에는 `extra_args`가 필요하지 않습니다. - `parallel_tool_calls`: 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다. -- `truncation`: 컨텍스트가 초과될 때 실패하지 않고 Responses API가 가장 오래된 대화 항목을 삭제하도록 하려면 `"auto"`로 설정합니다. -- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 여부를 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와 `store=False`일 때 로컬 입력으로 fallback해야 할 수 있는 세션 compaction 흐름에 중요합니다. -- `context_management`: `compact_threshold`를 사용한 Responses compaction 등 서버 측 컨텍스트 처리를 구성합니다. -- `prompt_cache_retention`: 예를 들어 `"24h"`로 캐시된 프롬프트 prefix를 더 오래 유지합니다. -- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 payload를 요청합니다. -- `top_logprobs`: 출력 텍스트에 대한 top-token logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다. -- `retry`: 모델 호출에 runner 관리 retry 설정을 사용하도록 선택합니다. [Runner 관리 retry](#runner-managed-retries)를 참조하세요. +- `truncation`: 컨텍스트가 초과되어 실패하는 대신 Responses API가 가장 오래된 대화 항목을 삭제하도록 하려면 `"auto"`를 설정합니다. +- `store`: 생성된 응답을 나중에 검색할 수 있도록 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와, `store=False`일 때 로컬 입력으로 폴백해야 할 수 있는 세션 압축 흐름에 중요합니다. +- `context_management`: `compact_threshold`를 사용하는 Responses 압축 같은 서버 측 컨텍스트 처리를 구성합니다. +- `prompt_cache_retention`: 예를 들어 `"24h"`를 사용해 캐시된 프롬프트 접두사를 더 오래 유지합니다. +- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다. +- `top_logprobs`: 출력 텍스트에 대한 상위 토큰 logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다. +- `retry`: 모델 호출에 대해 러너 관리형 재시도 설정을 선택적으로 사용합니다. [Runner 관리형 재시도](#runner-managed-retries)를 참조하세요. ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -`store=False`로 설정하면 Responses API는 나중에 서버 측에서 조회할 수 있도록 해당 응답을 보관하지 않습니다. 이는 stateless 또는 zero-data-retention 스타일의 흐름에 유용하지만, 그렇지 않으면 응답 ID를 재사용할 기능들이 대신 로컬에서 관리되는 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` compaction 경로를 입력 기반 compaction으로 전환합니다. [Sessions 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요. +`store=False`를 설정하면 Responses API는 해당 응답을 나중에 서버 측에서 검색할 수 있도록 보관하지 않습니다. 이는 상태 비저장 또는 제로 데이터 보존 스타일의 흐름에 유용하지만, 그렇지 않으면 응답 ID를 재사용할 기능들이 대신 로컬에서 관리되는 상태에 의존해야 함을 의미하기도 합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않은 경우 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [세션 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요. -서버 측 compaction은 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]과 다릅니다. `context_management=[{"type": "compaction", "compact_threshold": ...}]`는 각 Responses API 요청과 함께 전송되며, 렌더링된 컨텍스트가 임계값을 넘을 때 API가 응답의 일부로 compaction 항목을 내보낼 수 있습니다. `OpenAIResponsesCompactionSession`은 턴 사이에 독립 실행형 `responses.compact` 엔드포인트를 호출하고 로컬 세션 기록을 다시 작성합니다. +서버 측 압축은 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]과 다릅니다. `context_management=[{"type": "compaction", "compact_threshold": ...}]`는 각 Responses API 요청과 함께 전송되며, 렌더링된 컨텍스트가 임계값을 넘을 때 API가 응답의 일부로 압축 항목을 내보낼 수 있습니다. `OpenAIResponsesCompactionSession`은 턴 사이에 독립형 `responses.compact` 엔드포인트를 호출하고 로컬 세션 기록을 다시 작성합니다. ### `extra_args` 전달 -SDK가 아직 최상위 수준에서 직접 노출하지 않는 provider별 또는 더 새로운 요청 필드가 필요할 때 `extra_args`를 사용하세요. +SDK가 아직 최상위 수준에서 직접 노출하지 않는 프로바이더별 또는 최신 요청 필드가 필요할 때 `extra_args`를 사용하세요. -또한 OpenAI의 Responses API를 사용할 때 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 최상위 수준에서 사용할 수 없다면 `extra_args`를 사용해 이들도 전달할 수 있습니다. 동일한 요청 필드를 직접 `ModelSettings` 필드를 통해 동시에 설정하지 마세요. +또한 OpenAI의 Responses API를 사용할 때 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 이러한 매개변수가 최상위 수준에서 제공되지 않는 경우 `extra_args`를 사용해 전달할 수 있습니다. 동일한 요청 필드를 직접적인 `ModelSettings` 필드를 통해 동시에 설정하지 마세요. ```python from agents import Agent, ModelSettings @@ -365,9 +365,9 @@ english_agent = Agent( ) ``` -## Runner 관리 retry +## Runner 관리형 재시도 -Retry는 런타임 전용이며 선택 사항입니다. `ModelSettings(retry=...)`를 설정하고 retry 정책이 retry를 선택하지 않는 한 SDK는 일반 모델 요청을 retry하지 않습니다. +재시도는 런타임 전용이며 선택적으로 사용합니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK는 일반 모델 요청을 재시도하지 않습니다. ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -395,85 +395,85 @@ agent = Agent( ) ``` -`ModelRetrySettings`에는 세 개의 필드가 있습니다. +`ModelRetrySettings`에는 세 가지 필드가 있습니다.
| 필드 | 타입 | 참고 | | --- | --- | --- | -| `max_retries` | `int | None` | 초기 요청 이후 허용되는 retry 시도 횟수입니다. | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 retry할 때의 기본 지연 전략입니다. `backoff.max_delay`는 이 계산된 backoff 지연에만 상한을 적용합니다. 정책이 반환한 명시적 지연이나 retry-after 힌트에는 상한을 적용하지 않습니다. | -| `policy` | `RetryPolicy | None` | retry 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다. | +| `max_retries` | `int | None` | 초기 요청 이후 허용되는 재시도 횟수입니다. | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 재시도할 때의 기본 지연 전략입니다. `backoff.max_delay`는 이 계산된 backoff 지연만 제한합니다. 정책이 반환한 명시적 지연이나 retry-after 힌트는 제한하지 않습니다. | +| `policy` | `RetryPolicy | None` | 재시도 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다. |
-Retry 정책은 다음을 포함하는 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 받습니다. +재시도 정책은 다음을 포함하는 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 받습니다. -- `attempt` 및 `max_retries`: 시도 횟수를 고려한 결정을 내릴 수 있습니다. -- `stream`: 스트리밍 동작과 비스트리밍 동작을 분기할 수 있습니다. -- `error`: 원문 검사를 위한 값입니다. -- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 사실 -- 기본 모델 어댑터가 retry 지침을 제공할 수 있을 때의 `provider_advice` +- `attempt` 및 `max_retries`로 시도 횟수를 고려한 결정을 내릴 수 있습니다. +- `stream`으로 스트리밍 및 비스트리밍 동작을 분기할 수 있습니다. +- 원문 검사를 위한 `error` +- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 정규화된 사실 +- 기본 모델 어댑터가 재시도 지침을 제공할 수 있을 때의 `provider_advice` 정책은 다음 중 하나를 반환할 수 있습니다. -- 단순 retry 결정을 위한 `True` / `False` -- 지연을 override하거나 진단 reason을 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision] +- 간단한 재시도 결정을 위한 `True` / `False` +- 지연을 재정의하거나 진단 이유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision] SDK는 `retry_policies`에서 바로 사용할 수 있는 헬퍼를 내보냅니다. | 헬퍼 | 동작 | | --- | --- | | `retry_policies.never()` | 항상 선택하지 않습니다. | -| `retry_policies.provider_suggested()` | 사용 가능한 경우 provider retry 조언을 따릅니다. | -| `retry_policies.network_error()` | 일시적인 transport 및 timeout 실패와 일치합니다. | -| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 일치합니다. | -| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연을 사용해 retry합니다. 이 헬퍼는 retry-after 값을 명시적인 정책 지연으로 취급하므로 `backoff.max_delay`가 이를 제한하지 않습니다. | -| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 선택하면 retry합니다. | -| `retry_policies.all(...)` | 모든 중첩 정책이 선택할 때만 retry합니다. | +| `retry_policies.provider_suggested()` | 제공되는 경우 프로바이더의 재시도 조언을 따릅니다. | +| `retry_policies.network_error()` | 일시적인 전송 및 시간 초과 실패와 일치합니다. | +| `retry_policies.http_status([...])` | 선택된 HTTP 상태 코드와 일치합니다. | +| `retry_policies.retry_after()` | retry-after 힌트가 제공될 때만 해당 지연을 사용해 재시도합니다. 이 헬퍼는 retry-after 값을 명시적 정책 지연으로 취급하므로 `backoff.max_delay`가 이를 제한하지 않습니다. | +| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 선택하면 재시도합니다. | +| `retry_policies.all(...)` | 중첩된 모든 정책이 선택할 때만 재시도합니다. | -정책을 조합할 때 `provider_suggested()`는 provider가 이를 구분할 수 있는 경우 provider veto와 replay-safety 승인을 보존하므로 가장 안전한 첫 번째 구성 요소입니다. +정책을 조합할 때 `provider_suggested()`가 가장 안전한 첫 구성 요소입니다. 프로바이더가 구분할 수 있는 경우 프로바이더의 거부와 재실행 안전성 승인을 보존하기 때문입니다. ##### 안전 경계 -일부 실패는 자동으로 retry되지 않습니다. +일부 실패는 자동으로 재시도되지 않습니다. - Abort 오류 -- Provider 조언이 replay를 안전하지 않다고 표시한 요청 -- replay를 안전하지 않게 만들 방식으로 출력이 이미 시작된 후의 스트리밍 실행 +- 프로바이더 조언이 재실행을 안전하지 않은 것으로 표시한 요청 +- 출력이 이미 시작되어 재실행이 안전하지 않게 되는 방식으로 진행된 스트리밍 실행 -`previous_response_id` 또는 `conversation_id`를 사용하는 stateful 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청에서는 `network_error()` 또는 `http_status([500])` 같은 비 provider predicate만으로는 충분하지 않습니다. retry 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 provider의 replay-safe 승인이 포함되어야 합니다. +`previous_response_id` 또는 `conversation_id`를 사용하는 상태 저장형 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청의 경우 `network_error()` 또는 `http_status([500])` 같은 비 프로바이더 조건만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 프로바이더의 재실행 안전성 승인이 포함되어야 합니다. ##### Runner와 에이전트 병합 동작 -`retry`는 runner 수준 및 에이전트 수준 `ModelSettings` 사이에서 deep-merge됩니다. +`retry`는 러너 수준 및 에이전트 수준 `ModelSettings` 사이에서 깊은 병합됩니다. -- 에이전트는 `retry.max_retries`만 override하고 runner의 `policy`는 계속 상속할 수 있습니다. -- 에이전트는 `retry.backoff`의 일부만 override하고 runner의 sibling backoff 필드는 유지할 수 있습니다. -- `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries`와 `backoff`를 유지하지만 콜백 자체는 생략합니다. +- 에이전트는 `retry.max_retries`만 재정의하고도 러너의 `policy`를 상속할 수 있습니다. +- 에이전트는 `retry.backoff`의 일부만 재정의하고 러너의 형제 backoff 필드는 유지할 수 있습니다. +- `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries` 및 `backoff`를 유지하지만 콜백 자체는 생략합니다. -더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 retry 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요. +더 완전한 예제는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예제](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요. -## 비 OpenAI provider 문제 해결 +## 비 OpenAI 프로바이더 문제 해결 ### 트레이싱 클라이언트 오류 401 -트레이싱 관련 오류가 발생한다면 trace가 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 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)의 키여야 합니다. -3. 비 OpenAI trace 프로세서를 사용합니다. [트레이싱 문서](../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 provider가 아직 이를 지원하지 않습니다. 그 결과 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 지원 -일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 같은 오류가 발생합니다. +일부 모델 프로바이더는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 비슷한 오류가 발생합니다. ``` @@ -481,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -이는 일부 모델 provider의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정할 수는 없습니다. 이 문제를 수정하는 작업을 진행 중이지만, 그렇지 않으면 앱이 잘못된 형식의 JSON 때문에 자주 중단될 수 있으므로 JSON schema 출력을 지원하는 provider에 의존하는 것을 권장합니다. +이는 일부 모델 프로바이더의 한계입니다. 이들은 JSON 출력을 지원하지만 출력에 사용할 `json_schema`를 지정하도록 허용하지 않습니다. 이 문제에 대한 수정 작업을 진행 중이지만, JSON 스키마 출력을 지원하는 프로바이더에 의존하는 것을 권장합니다. 그렇지 않으면 잘못된 형식의 JSON 때문에 앱이 자주 중단될 수 있습니다. -## Provider 간 모델 혼합 +## 프로바이더 간 모델 혼합 -모델 provider 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, multimodal input, 호스티드 file search 및 웹 검색을 지원하지만, 많은 다른 provider는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요. +모델 프로바이더 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 file search 및 web search를 지원하지만, 다른 많은 프로바이더는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요. -- 지원되지 않는 `tools`를 이를 이해하지 못하는 provider에 보내지 마세요 -- text-only 모델을 호출하기 전에 multimodal input을 필터링하세요 -- structured JSON outputs를 지원하지 않는 provider는 가끔 유효하지 않은 JSON을 생성할 수 있음을 유의하세요. +- 지원되지 않는 `tools`를 이해하지 못하는 프로바이더에 보내지 마세요 +- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하세요 +- structured JSON 출력을 지원하지 않는 프로바이더는 가끔 유효하지 않은 JSON을 생성할 수 있음을 유의하세요. ## 서드파티 어댑터 -SDK의 내장 provider 통합 지점이 충분하지 않은 경우에만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 비 OpenAI provider와 결합해야 하거나 내장 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 upstream 모델 provider 사이에 또 하나의 호환성 계층을 추가하므로 기능 지원과 요청 의미가 provider별로 달라질 수 있습니다. SDK에는 현재 best-effort 베타 어댑터 통합으로 Any-LLM과 LiteLLM이 포함되어 있습니다. +SDK의 내장 프로바이더 통합 지점만으로 충분하지 않을 때만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 비 OpenAI 프로바이더와 결합해야 하거나, 내장 경로가 제공하지 않는 어댑터 관리형 프로바이더 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 상위 모델 프로바이더 사이에 또 다른 호환성 계층을 추가하므로, 기능 지원과 요청 의미 체계는 프로바이더별로 달라질 수 있습니다. SDK는 현재 Any-LLM 및 LiteLLM을 최선 노력(best-effort) 기반의 베타 어댑터 통합으로 포함합니다. ### Any-LLM -Any-LLM 지원은 Any-LLM 관리 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다. +Any-LLM 지원은 Any-LLM 관리형 프로바이더 범위 또는 라우팅이 필요한 경우를 위해 최선 노력(best-effort) 기반의 베타로 포함되어 있습니다. -Upstream provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환성 계층을 사용할 수 있습니다. +상위 프로바이더 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 프로바이더별 호환성 계층을 사용할 수 있습니다. -Any-LLM이 필요하면 `openai-agents[any-llm]`을 설치한 다음 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)에서 시작하세요. [`MultiProvider`][agents.MultiProvider]에서 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 한다면 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요. +Any-LLM이 필요하면 `openai-agents[any-llm]`을 설치한 다음 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)부터 시작하세요. [`MultiProvider`][agents.MultiProvider]와 함께 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 하는 경우 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요. -Any-LLM은 서드파티 어댑터 계층이므로 provider 의존성과 capability gap은 SDK가 아니라 upstream의 Any-LLM이 정의합니다. Upstream provider가 사용량 metrics를 반환하면 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 사용량 chunk를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, tool calling, 사용량 보고 또는 Responses별 동작에 의존한다면 배포하려는 정확한 provider backend를 검증하세요. +Any-LLM은 계속 서드파티 어댑터 계층이므로, 프로바이더 의존성과 기능 격차는 SDK가 아니라 상위의 Any-LLM에 의해 정의됩니다. 상위 프로바이더가 사용량 지표를 반환하면 사용량 지표는 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 사용량 청크를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, 도구 호출, 사용량 보고 또는 Responses 특정 동작에 의존한다면 배포하려는 정확한 프로바이더 백엔드를 검증하세요. ### LiteLLM -LiteLLM 지원은 LiteLLM별 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다. +LiteLLM 지원은 LiteLLM 특정 프로바이더 범위 또는 라우팅이 필요한 경우를 위해 최선 노력(best-effort) 기반의 베타로 포함되어 있습니다. -LiteLLM이 필요하면 `openai-agents[litellm]`을 설치한 다음 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)에서 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다. +LiteLLM이 필요하면 `openai-agents[litellm]`을 설치한 다음 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)부터 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다. -일부 LiteLLM 기반 provider는 기본적으로 SDK 사용량 metrics를 채우지 않습니다. 사용량 보고가 필요하다면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, tool calling, 사용량 보고 또는 어댑터별 라우팅 동작에 의존하는 경우 배포하려는 정확한 provider backend를 검증하세요. \ No newline at end of file +일부 LiteLLM 기반 프로바이더는 기본적으로 SDK 사용량 지표를 채우지 않습니다. 사용량 보고가 필요하면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, 도구 호출, 사용량 보고 또는 어댑터 특정 라우팅 동작에 의존하는 경우 배포하려는 정확한 프로바이더 백엔드를 검증하세요. \ No newline at end of file diff --git a/docs/ko/multi_agent.md b/docs/ko/multi_agent.md index a2bf73f83c..fb10e32834 100644 --- a/docs/ko/multi_agent.md +++ b/docs/ko/multi_agent.md @@ -4,61 +4,61 @@ search: --- # 에이전트 오케스트레이션 -오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트가 실행되고, 어떤 순서로 실행되며, 다음에 무엇이 일어날지를 어떻게 결정할까요? 에이전트를 오케스트레이션하는 주요 방법은 두 가지입니다 +오케스트레이션은 앱에서 에이전트가 흐르는 방식을 의미합니다. 어떤 에이전트가 어떤 순서로 실행되며, 다음에 무엇이 일어날지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 주요 방법은 두 가지입니다. -1. LLM이 의사결정을 하도록 허용: LLM의 지능을 활용해 계획하고, 추론하고, 이를 바탕으로 어떤 단계를 수행할지 결정합니다 -2. 코드를 통한 오케스트레이션: 코드로 에이전트의 흐름을 결정합니다 +1. LLM이 결정을 내리도록 허용: LLM의 지능을 사용해 계획하고, 추론하고, 이를 바탕으로 어떤 단계를 수행할지 결정합니다. +2. 코드를 통한 오케스트레이션: 코드로 에이전트의 흐름을 결정합니다. -이 패턴들은 함께 조합해 사용할 수 있습니다. 각각에는 아래에 설명된 고유한 트레이드오프가 있습니다 +이러한 패턴은 함께 조합해 사용할 수 있습니다. 각 방식에는 아래에 설명된 고유한 장단점이 있습니다. ## LLM을 통한 오케스트레이션 -에이전트는 instructions, tools, handoffs를 갖춘 LLM입니다. 즉, 개방형 작업이 주어지면 LLM은 도구를 사용해 행동을 수행하고 데이터를 수집하며, 핸드오프를 사용해 하위 에이전트에 작업을 위임하면서 작업을 어떻게 해결할지 자율적으로 계획할 수 있습니다. 예를 들어, 리서치 에이전트에는 다음과 같은 도구를 갖출 수 있습니다 +에이전트는 instructions, tools 및 핸드오프를 갖춘 LLM입니다. 즉, 개방형 작업이 주어지면 LLM은 tools를 사용해 작업을 수행하고 데이터를 얻으며, 핸드오프를 사용해 하위 에이전트에게 작업을 위임하면서, 작업을 어떻게 처리할지 자율적으로 계획할 수 있습니다. 예를 들어 연구 에이전트에는 다음과 같은 도구를 장착할 수 있습니다. -- 온라인 정보를 찾기 위한 웹 검색 -- 독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색 결과 가져오기 +- 온라인에서 정보를 찾기 위한 웹 검색 +- 독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색 - 컴퓨터에서 작업을 수행하기 위한 컴퓨터 사용 -- 데이터 분석을 수행하기 위한 코드 실행 -- 계획 수립, 보고서 작성 등에 뛰어난 전문 에이전트로의 핸드오프 +- 데이터 분석을 위한 코드 실행 +- 기획, 보고서 작성 등에 뛰어난 전문 에이전트로의 핸드오프 ### 핵심 SDK 패턴 -Python SDK에서는 두 가지 오케스트레이션 패턴이 가장 자주 사용됩니다 +Python SDK에서는 두 가지 오케스트레이션 패턴이 가장 자주 사용됩니다. -| 패턴 | 작동 방식 | 적합한 경우 | +| 패턴 | 작동 방식 | 가장 적합한 경우 | | --- | --- | --- | -| Agents as tools | 관리자 에이전트가 대화의 제어권을 유지하고 `Agent.as_tool()`을 통해 전문 에이전트를 호출합니다 | 하나의 에이전트가 최종 답변을 책임지고, 여러 전문 에이전트의 출력을 결합하거나, 공통 가드레일을 한곳에서 적용하고 싶을 때 | -| 핸드오프 | 트리아지 에이전트가 대화를 전문 에이전트로 라우팅하고, 해당 전문 에이전트가 해당 턴의 나머지 동안 활성 에이전트가 됩니다 | 전문 에이전트가 직접 응답하고, 프롬프트를 집중되게 유지하거나, 관리자가 결과를 설명하지 않고 instructions를 전환하고 싶을 때 | +| Agents as tools | 관리자 에이전트가 대화의 제어권을 유지하고 `Agent.as_tool()`을 통해 전문 에이전트를 호출합니다. | 하나의 에이전트가 최종 답변을 담당하거나, 여러 전문가의 출력을 결합하거나, 공유 가드레일을 한곳에서 적용하도록 하고 싶을 때 | +| 핸드오프 | 트리아지 에이전트가 대화를 전문가에게 라우팅하고, 해당 전문가가 나머지 턴 동안 활성 에이전트가 됩니다. | 전문가가 직접 응답하거나, 프롬프트를 집중된 상태로 유지하거나, 관리자가 결과를 설명하지 않고 instructions를 전환하도록 하고 싶을 때 | -전문 에이전트가 제한된 하위 작업을 돕되 사용자 대상 대화를 넘겨받지 않아야 한다면 **agents as tools**를 사용하세요. 라우팅 자체가 워크플로의 일부이고 선택된 전문 에이전트가 다음 상호작용 구간을 맡아야 한다면 **handoffs**를 사용하세요 +전문가가 제한된 하위 작업을 도와야 하지만 사용자와 직접 마주하는 대화를 인수해서는 안 되는 경우 **agents as tools**를 사용합니다. 라우팅 자체가 워크플로의 일부이고 선택된 전문가가 상호작용의 다음 부분을 담당하도록 하고 싶을 때는 **핸드오프**를 사용합니다. -두 가지를 결합할 수도 있습니다. 트리아지 에이전트가 전문 에이전트로 핸드오프한 뒤에도, 해당 전문 에이전트는 좁은 하위 작업을 위해 다른 에이전트를 도구로 호출할 수 있습니다 +두 가지를 조합할 수도 있습니다. 트리아지 에이전트가 전문가에게 핸드오프할 수 있으며, 해당 전문가는 여전히 좁은 범위의 하위 작업을 위해 다른 에이전트를 도구로 호출할 수 있습니다. -이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고 싶을 때 매우 유용합니다. 여기서 가장 중요한 전술은 다음과 같습니다 +이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고자 할 때 유용합니다. 여기서 가장 중요한 전략은 다음과 같습니다. -1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 그리고 반드시 지켜야 하는 매개변수 범위를 명확히 하세요 -2. 앱을 모니터링하고 반복 개선하세요. 문제가 발생하는 지점을 확인하고 프롬프트를 반복 개선하세요 -3. 에이전트가 스스로 점검하고 개선하도록 하세요. 예를 들어 루프로 실행하고 자기 비평을 하게 하거나, 오류 메시지를 제공해 개선하게 하세요 -4. 어떤 작업이든 잘해야 하는 범용 에이전트 하나보다, 단일 작업에 뛰어난 전문 에이전트를 두세요 -5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 훈련해 작업 수행 능력을 개선하고 향상시킬 수 있습니다 +1. 좋은 프롬프트에 투자합니다. 어떤 도구를 사용할 수 있는지, 어떻게 사용해야 하는지, 어떤 매개변수 범위 내에서 작동해야 하는지 명확히 합니다. +2. 앱을 모니터링하고 반복적으로 개선합니다. 문제가 발생하는 지점을 파악하고 프롬프트를 반복 개선합니다. +3. 에이전트가 스스로 성찰하고 개선하도록 허용합니다. 예를 들어 루프 안에서 실행하고 스스로 비평하게 하거나, 오류 메시지를 제공하고 개선하게 합니다. +4. 무엇이든 잘하도록 기대되는 범용 에이전트보다, 하나의 작업에 탁월한 전문 에이전트를 둡니다. +5. [평가](https://platform.openai.com/docs/guides/evals)에 투자합니다. 이를 통해 에이전트를 훈련해 작업 수행 능력을 개선하고 향상시킬 수 있습니다. -이 스타일의 오케스트레이션을 뒷받침하는 핵심 SDK 기본 구성 요소를 원한다면 [tools](tools.md), [handoffs](handoffs.md), [running agents](running_agents.md)부터 시작하세요 +이러한 오케스트레이션 방식의 핵심 SDK 기본 구성 요소를 알고 싶다면 [도구](tools.md), [핸드오프](handoffs.md), [에이전트 실행](running_agents.md)부터 시작하세요. ## 코드를 통한 오케스트레이션 -LLM을 통한 오케스트레이션은 강력하지만, 코드를 통한 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정론적이고 예측 가능하게 만듭니다. 여기서의 일반적인 패턴은 다음과 같습니다 +LLM을 통한 오케스트레이션은 강력하지만, 코드를 통한 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정적이고 예측 가능하게 만듭니다. 여기서 흔히 사용되는 패턴은 다음과 같습니다. -- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성하기. 예를 들어 에이전트에게 작업을 몇 가지 카테고리로 분류하게 한 다음, 카테고리에 따라 다음 에이전트를 선택할 수 있습니다 -- 한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝하기. 블로그 글 작성 같은 작업을 리서치, 개요 작성, 본문 작성, 비평, 개선 같은 일련의 단계로 분해할 수 있습니다 -- 작업을 수행하는 에이전트를 평가 및 피드백을 제공하는 에이전트와 함께 `while` 루프로 실행하고, 평가자가 출력이 특정 기준을 통과한다고 말할 때까지 반복하기 -- 여러 에이전트를 병렬로 실행하기(예: `asyncio.gather` 같은 Python 기본 구성 요소 사용). 서로 의존하지 않는 여러 작업이 있을 때 속도 측면에서 유용합니다 +- [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성합니다. 예를 들어 에이전트에게 작업을 몇 가지 카테고리로 분류하게 한 다음, 해당 카테고리를 바탕으로 다음 에이전트를 선택할 수 있습니다. +- 하나의 에이전트 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝합니다. 블로그 게시물 작성 같은 작업을 연구하기, 개요 작성하기, 블로그 게시물 작성하기, 비평하기, 개선하기와 같은 일련의 단계로 분해할 수 있습니다. +- 평가하고 피드백을 제공하는 에이전트와 함께, 작업을 수행하는 에이전트를 `while` 루프에서 실행하여 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복합니다. +- 여러 에이전트를 병렬로 실행합니다. 예를 들어 `asyncio.gather` 같은 Python 기본 구성 요소를 사용할 수 있습니다. 서로 의존하지 않는 여러 작업이 있을 때 속도 측면에서 유용합니다. -[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 다양한 예제가 있습니다 +[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 코드 예제가 있습니다. ## 관련 가이드 -- 구성 패턴과 에이전트 설정은 [Agents](agents.md)를 참고하세요 -- `Agent.as_tool()` 및 관리자 스타일 오케스트레이션은 [Tools](tools.md#agents-as-tools)를 참고하세요 -- 전문 에이전트 간 위임은 [Handoffs](handoffs.md)를 참고하세요 -- 실행별 오케스트레이션 제어 및 대화 상태는 [Running agents](running_agents.md)를 참고하세요 -- 최소한의 엔드투엔드 핸드오프 예제는 [Quickstart](quickstart.md)를 참고하세요 \ No newline at end of file +- 구성 패턴과 에이전트 설정은 [에이전트](agents.md)를 참조하세요. +- `Agent.as_tool()` 및 관리자 스타일 오케스트레이션은 [도구](tools.md#agents-as-tools)를 참조하세요. +- 전문 에이전트 간 위임은 [핸드오프](handoffs.md)를 참조하세요. +- 실행별 오케스트레이션 제어와 대화 상태는 [에이전트 실행](running_agents.md)을 참조하세요. +- 최소한의 엔드투엔드 핸드오프 예제는 [빠른 시작](quickstart.md)을 참조하세요. \ No newline at end of file diff --git a/docs/ko/quickstart.md b/docs/ko/quickstart.md index a80b526399..c543ad7139 100644 --- a/docs/ko/quickstart.md +++ b/docs/ko/quickstart.md @@ -38,7 +38,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 키를 생성하세요. +API 키가 없다면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)에 따라 OpenAI API 키를 생성하세요. 이 명령은 현재 터미널 세션에 키를 설정합니다. @@ -54,7 +54,7 @@ Windows PowerShell: $env:OPENAI_API_KEY = "sk-..." ``` -Windows 명령 프롬프트: +Windows Command Prompt: ```cmd set "OPENAI_API_KEY=sk-..." @@ -62,7 +62,7 @@ set "OPENAI_API_KEY=sk-..." ## 첫 에이전트 생성 -에이전트는 instructions, 이름, 특정 모델 같은 선택적 구성으로 정의됩니다. +에이전트는 instructions, 이름, 특정 모델과 같은 선택적 구성으로 정의됩니다. ```python from agents import Agent @@ -75,7 +75,7 @@ agent = Agent( ## 첫 에이전트 실행 -에이전트를 실행하고 [`RunResult`][agents.result.RunResult]를 돌려받으려면 [`Runner`][agents.run.Runner]를 사용하세요. +[`Runner`][agents.run.Runner]를 사용해 에이전트를 실행하고 [`RunResult`][agents.result.RunResult]를 반환받습니다. ```python import asyncio @@ -94,23 +94,23 @@ if __name__ == "__main__": asyncio.run(main()) ``` -두 번째 턴에서는 `result.to_input_list()`를 `Runner.run(...)`에 다시 전달하거나, [세션](sessions/index.md)을 연결하거나, `conversation_id` / `previous_response_id`로 OpenAI 서버 관리 상태를 재사용할 수 있습니다. [에이전트 실행](running_agents.md) 가이드에서는 이러한 접근 방식을 비교합니다. +두 번째 턴에서는 `result.to_input_list()`를 다시 `Runner.run(...)`에 전달하거나, [세션](sessions/index.md)을 연결하거나, `conversation_id` / `previous_response_id`를 사용해 OpenAI 서버 관리 상태를 재사용할 수 있습니다. [에이전트 실행](running_agents.md) 가이드에서는 이러한 접근 방식을 비교합니다. 다음 경험칙을 사용하세요. -| 원하는 경우... | 다음으로 시작하세요... | +| 원하는 경우... | 시작점... | | --- | --- | -| 완전한 수동 제어와 공급자에 구애받지 않는 기록 | `result.to_input_list()` | -| SDK가 기록을 로드하고 저장해 주기를 원하는 경우 | [`session=...`](sessions/index.md) | +| 전체 수동 제어와 제공자에 독립적인 기록 | `result.to_input_list()` | +| SDK가 기록을 로드하고 저장하도록 함 | [`session=...`](sessions/index.md) | | OpenAI가 관리하는 서버 측 이어가기 | `previous_response_id` 또는 `conversation_id` | -트레이드오프와 정확한 동작은 [에이전트 실행](running_agents.md#choose-a-memory-strategy)을 참조하세요. +절충점과 정확한 동작은 [에이전트 실행](running_agents.md#choose-a-memory-strategy)을 참고하세요. -작업이 주로 프롬프트, 도구, 대화 상태에 머문다면 일반 `Agent`와 `Runner`를 사용하세요. 에이전트가 격리된 워크스페이스에서 실제 파일을 검사하거나 수정해야 한다면 [Sandbox 에이전트 빠른 시작](sandbox_agents.md)으로 이동하세요. +작업이 주로 프롬프트, 도구, 대화 상태 안에서 이루어진다면 일반 `Agent`와 `Runner`를 사용하세요. 에이전트가 격리된 워크스페이스에서 실제 파일을 검사하거나 수정해야 한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)으로 이동하세요. ## 에이전트에 도구 제공 -에이전트에 정보를 조회하거나 작업을 수행할 도구를 제공할 수 있습니다. +에이전트에 정보를 조회하거나 작업을 수행할 수 있는 도구를 제공할 수 있습니다. ```python import asyncio @@ -142,16 +142,16 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 에이전트 몇 개 추가 +## 에이전트 몇 개 더 추가 -멀티 에이전트 패턴을 선택하기 전에 최종 답변의 소유자가 누구인지 결정하세요. +멀티 에이전트 패턴을 선택하기 전에, 최종 답변을 누가 담당할지 결정하세요. -- **핸드오프**: 해당 턴의 그 부분에 대해 전문가가 대화를 이어받습니다. -- **Agents as tools**: 오케스트레이터가 제어를 유지하고 전문가를 도구로 호출합니다. +- **핸드오프**: 해당 턴의 해당 부분에 대해 전문가가 대화를 이어받습니다. +- **Agents as tools**: 오케스트레이터가 제어를 유지하며 전문가를 도구로 호출합니다. -이 빠른 시작에서는 첫 예제로 가장 짧기 때문에 **핸드오프**를 계속 사용합니다. 매니저 스타일 패턴은 [에이전트 오케스트레이션](multi_agent.md) 및 [도구: agents as tools](tools.md#agents-as-tools)를 참조하세요. +이 빠른 시작에서는 첫 예제로 가장 짧기 때문에 **핸드오프**를 계속 사용합니다. 매니저 스타일 패턴은 [에이전트 오케스트레이션](multi_agent.md) 및 [도구: agents as tools](tools.md#agents-as-tools)를 참고하세요. -추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_description`은 라우팅 에이전트에 언제 위임할지에 대한 추가 컨텍스트를 제공합니다. +추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_description`은 라우팅 에이전트가 언제 위임할지에 대한 추가 컨텍스트를 제공합니다. ```python from agents import Agent @@ -171,7 +171,7 @@ math_tutor_agent = Agent( ## 핸드오프 정의 -에이전트에서는 작업을 해결하는 동안 선택할 수 있는 나가는 핸드오프 옵션 목록을 정의할 수 있습니다. +에이전트에서는 작업을 해결하는 동안 선택할 수 있는 발신 핸드오프 옵션 목록을 정의할 수 있습니다. ```python triage_agent = Agent( @@ -203,17 +203,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 참조 코드 예제 +## 참조 예제 저장소에는 동일한 핵심 패턴에 대한 전체 스크립트가 포함되어 있습니다. -- 첫 실행용 [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) -- 함수 도구용 [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) -- 멀티 에이전트 라우팅용 [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) +- [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py): 첫 실행 +- [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py): 함수 도구 +- [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py): 멀티 에이전트 라우팅 ## 트레이스 보기 -에이전트 실행 중 발생한 일을 검토하려면 [OpenAI Dashboard의 Trace viewer](https://platform.openai.com/traces)로 이동하여 에이전트 실행 트레이스를 확인하세요. +에이전트 실행 중 발생한 일을 검토하려면 [OpenAI Dashboard의 Trace viewer](https://platform.openai.com/traces)로 이동해 에이전트 실행 트레이스를 확인하세요. ## 다음 단계 @@ -221,5 +221,5 @@ if __name__ == "__main__": - [에이전트](agents.md) 구성 방법 알아보기 - [에이전트 실행](running_agents.md) 및 [세션](sessions/index.md) 알아보기 -- 실제 워크스페이스 안에서 작업이 이루어져야 한다면 [Sandbox 에이전트](sandbox_agents.md) 알아보기 +- 실제 워크스페이스 안에서 작업이 이루어져야 하는 경우 [샌드박스 에이전트](sandbox_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 d6343fc2cd..f2fc1f3271 100644 --- a/docs/ko/realtime/guide.md +++ b/docs/ko/realtime/guide.md @@ -4,26 +4,26 @@ search: --- # 실시간 에이전트 가이드 -이 가이드는 OpenAI Agents SDK의 실시간 레이어가 OpenAI Realtime API에 어떻게 매핑되는지, 그리고 Python SDK가 그 위에 어떤 추가 동작을 더하는지 설명합니다. +이 가이드는 OpenAI Agents SDK의 실시간 레이어가 OpenAI Realtime API에 어떻게 대응되는지, 그리고 Python SDK가 그 위에 어떤 추가 동작을 더하는지 설명합니다. !!! warning "베타 기능" 실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다. -!!! note "여기서 시작" +!!! note "시작점" - 기본 Python 경로를 원한다면 먼저 [빠른 시작](quickstart.md)을 읽으세요. 앱에서 서버 측 WebSocket 또는 SIP를 사용해야 할지 결정 중이라면 [실시간 전송](transport.md)을 읽으세요. 브라우저 WebRTC 전송은 Python SDK의 일부가 아닙니다. + 기본 Python 경로를 원한다면 먼저 [빠른 시작](quickstart.md)을 읽어보세요. 앱에서 서버 측 WebSocket 또는 SIP를 사용해야 할지 결정하는 중이라면 [실시간 전송](transport.md)을 읽어보세요. 브라우저 WebRTC 전송은 Python SDK의 일부가 아닙니다. ## 개요 -실시간 에이전트는 Realtime API와 장기 연결을 열어 둠으로써 모델이 텍스트와 오디오를 점진적으로 처리하고, 오디오 출력을 스트리밍하며, 도구를 호출하고, 매 턴마다 새 요청을 다시 시작하지 않고도 인터럽션(중단 처리)을 처리할 수 있게 합니다. +실시간 에이전트는 Realtime API에 오래 유지되는 연결을 열어 두어, 모델이 텍스트와 오디오를 점진적으로 처리하고, 오디오 출력을 스트리밍하고, 도구를 호출하고, 매 턴마다 새 요청을 다시 시작하지 않고도 인터럽션(중단 처리)을 처리할 수 있게 합니다. 주요 SDK 구성 요소는 다음과 같습니다. -- **RealtimeAgent**: 하나의 실시간 전문가를 위한 instructions, tools, 출력 가드레일 및 핸드오프 -- **RealtimeRunner**: 시작 에이전트를 실시간 전송에 연결하는 세션 팩터리 -- **RealtimeSession**: 입력을 보내고, 이벤트를 수신하고, 기록을 추적하며, 도구를 실행하는 라이브 세션 -- **RealtimeModel**: 전송 추상화입니다. 기본값은 OpenAI의 서버 측 WebSocket 구현입니다. +- **RealtimeAgent**: 한 명의 실시간 전문가를 위한 instructions, tools, 출력 가드레일 및 핸드오프 +- **RealtimeRunner**: 시작 에이전트를 실시간 전송에 연결하는 세션 팩토리 +- **RealtimeSession**: 입력을 보내고, 이벤트를 수신하고, 기록을 추적하고, 도구를 실행하는 라이브 세션 +- **RealtimeModel**: 전송 추상화입니다. 기본값은 OpenAI의 서버 측 WebSocket 구현입니다. ## 세션 수명 주기 @@ -31,25 +31,25 @@ search: 1. 하나 이상의 `RealtimeAgent`를 만듭니다. 2. 시작 에이전트로 `RealtimeRunner`를 만듭니다. -3. `await runner.run()`을 호출하여 `RealtimeSession`을 가져옵니다. +3. `await runner.run()`을 호출해 `RealtimeSession`을 가져옵니다. 4. `async with session:` 또는 `await session.enter()`로 세션에 진입합니다. 5. `send_message()` 또는 `send_audio()`로 사용자 입력을 보냅니다. -6. 대화가 끝날 때까지 세션 이벤트를 반복 처리합니다. +6. 대화가 끝날 때까지 세션 이벤트를 순회합니다. -텍스트 전용 실행과 달리, `runner.run()`은 즉시 최종 결과를 생성하지 않습니다. 대신 로컬 기록, 백그라운드 도구 실행, 가드레일 상태, 활성 에이전트 구성을 전송 레이어와 동기화 상태로 유지하는 라이브 세션 객체를 반환합니다. +텍스트 전용 실행과 달리, `runner.run()`은 최종 결과를 즉시 생성하지 않습니다. 대신 로컬 기록, 백그라운드 도구 실행, 가드레일 상태, 활성 에이전트 구성을 전송 레이어와 동기화해 유지하는 라이브 세션 객체를 반환합니다. -기본적으로 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용하므로, 기본 Python 경로는 Realtime API에 대한 서버 측 WebSocket 연결입니다. 다른 `RealtimeModel`을 전달해도 동일한 세션 수명 주기와 에이전트 기능은 계속 적용되며, 연결 메커니즘만 달라질 수 있습니다. +기본적으로 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용하므로 기본 Python 경로는 Realtime API에 대한 서버 측 WebSocket 연결입니다. 다른 `RealtimeModel`을 전달하더라도 동일한 세션 수명 주기와 에이전트 기능은 그대로 적용되며, 연결 방식만 달라질 수 있습니다. ## 에이전트 및 세션 구성 -`RealtimeAgent`는 일반 `Agent` 타입보다 의도적으로 범위가 좁습니다. +`RealtimeAgent`는 일반 `Agent` 타입보다 의도적으로 범위가 더 좁습니다. -- 모델 선택은 에이전트별이 아니라 세션 수준에서 구성됩니다. -- structured outputs는 지원되지 않습니다. -- 음성은 구성할 수 있지만, 세션이 이미 음성 오디오를 생성한 후에는 변경할 수 없습니다. -- instructions, 함수 도구, 핸드오프, 훅, 출력 가드레일은 모두 계속 작동합니다. +- 모델 선택은 에이전트별이 아니라 세션 수준에서 구성됩니다. +- Structured outputs는 지원되지 않습니다. +- 음성은 구성할 수 있지만, 세션이 이미 음성 오디오를 생성한 후에는 변경할 수 없습니다. +- instructions, 함수 도구, 핸드오프, 훅, 출력 가드레일은 모두 계속 작동합니다. -`RealtimeSessionModelSettings`는 최신 중첩 `audio` 구성과 이전의 평면 별칭을 모두 지원합니다. 새 코드에는 중첩 형태를 권장하며, 새 실시간 에이전트에는 `gpt-realtime-2`로 시작하세요. +`RealtimeSessionModelSettings`는 최신 중첩 `audio` 구성과 기존 플랫 별칭을 모두 지원합니다. 새 코드에는 중첩 형태를 권장하며, 새 실시간 에이전트에는 `gpt-realtime-2`로 시작하세요. ```python runner = RealtimeRunner( @@ -73,31 +73,31 @@ runner = RealtimeRunner( 유용한 세션 수준 설정은 다음과 같습니다. -- `audio.input.format`, `audio.output.format` -- `audio.input.transcription` -- `audio.input.noise_reduction` -- `audio.input.turn_detection` -- `audio.output.voice`, `audio.output.speed` -- `output_modalities` -- `tool_choice` -- `prompt` -- `tracing` +- `audio.input.format`, `audio.output.format` +- `audio.input.transcription` +- `audio.input.noise_reduction` +- `audio.input.turn_detection` +- `audio.output.voice`, `audio.output.speed` +- `output_modalities` +- `tool_choice` +- `prompt` +- `tracing` -`RealtimeRunner(config=...)`에서 유용한 실행 수준 설정은 다음과 같습니다. +`RealtimeRunner(config=...)`에서 사용할 수 있는 유용한 실행 수준 설정은 다음과 같습니다. -- `async_tool_calls` -- `output_guardrails` -- `guardrails_settings.debounce_text_length` -- `tool_error_formatter` -- `tracing_disabled` +- `async_tool_calls` +- `output_guardrails` +- `guardrails_settings.debounce_text_length` +- `tool_error_formatter` +- `tracing_disabled` -전체 타입 지정 표면은 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참조하세요. +전체 타입 지정 인터페이스는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참고하세요. ## 입력 및 출력 ### 텍스트 및 구조화된 사용자 메시지 -일반 텍스트 또는 구조화된 실시간 메시지에는 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용하세요. +일반 텍스트 또는 구조화된 실시간 메시지를 보내려면 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용하세요. ```python from agents.realtime import RealtimeUserInputMessage @@ -115,7 +115,7 @@ message: RealtimeUserInputMessage = { await session.send_message(message) ``` -구조화된 메시지는 실시간 대화에 이미지 입력을 포함하는 주요 방법입니다. [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)의 예제 웹 데모는 이 방식으로 `input_image` 메시지를 전달합니다. +구조화된 메시지는 실시간 대화에 이미지 입력을 포함하는 주된 방법입니다. [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)의 예제 웹 데모는 이러한 방식으로 `input_image` 메시지를 전달합니다. ### 오디오 입력 @@ -125,21 +125,21 @@ await session.send_message(message) await session.send_audio(audio_bytes) ``` -서버 측 턴 감지가 비활성화된 경우, 턴 경계를 표시할 책임은 직접 져야 합니다. 상위 수준 편의 기능은 다음과 같습니다. +서버 측 턴 감지가 비활성화되어 있으면 턴 경계를 표시할 책임은 사용자에게 있습니다. 고수준 편의 메서드는 다음과 같습니다. ```python await session.send_audio(audio_bytes, commit=True) ``` -더 낮은 수준의 제어가 필요하다면 기본 모델 전송을 통해 `input_audio_buffer.commit` 같은 원문 클라이언트 이벤트를 보낼 수도 있습니다. +더 낮은 수준의 제어가 필요하다면 기본 모델 전송을 통해 `input_audio_buffer.commit` 같은 원문 클라이언트 이벤트도 보낼 수 있습니다. ### 수동 응답 제어 -`session.send_message()`는 상위 수준 경로를 사용해 사용자 입력을 보내고 응답을 시작해 줍니다. 원문 오디오 버퍼링은 모든 구성에서 **자동으로** 동일하게 동작하지는 않습니다. +`session.send_message()`는 고수준 경로를 사용해 사용자 입력을 보내고 응답을 시작합니다. 원문 오디오 버퍼링은 모든 구성에서 이와 동일한 작업을 자동으로 수행하지는 **않습니다**. Realtime API 수준에서 수동 턴 제어란 원문 `session.update`로 `turn_detection`을 지운 다음, `input_audio_buffer.commit` 및 `response.create`를 직접 보내는 것을 의미합니다. -턴을 수동으로 관리하는 경우, 모델 전송을 통해 원문 클라이언트 이벤트를 보낼 수 있습니다. +턴을 수동으로 관리하고 있다면 모델 전송을 통해 원문 클라이언트 이벤트를 보낼 수 있습니다. ```python from agents.realtime.model_inputs import RealtimeModelSendRawMessage @@ -155,37 +155,37 @@ await session.model.send_event( 이 패턴은 다음과 같은 경우에 유용합니다. -- `turn_detection`이 비활성화되어 있으며 모델이 언제 응답해야 할지 직접 결정하려는 경우 -- 응답을 트리거하기 전에 사용자 입력을 검사하거나 게이트하려는 경우 -- 대역 외 응답을 위한 사용자 지정 프롬프트가 필요한 경우 +- `turn_detection`이 비활성화되어 있고 모델이 언제 응답해야 할지 직접 결정하려는 경우 +- 응답을 트리거하기 전에 사용자 입력을 검사하거나 게이트하려는 경우 +- 대역 외 응답을 위한 사용자 지정 프롬프트가 필요한 경우 -[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)의 SIP 예제는 원문 `response.create`를 사용하여 첫 인사말을 강제로 생성합니다. +[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)의 SIP 예제는 원문 `response.create`를 사용해 시작 인사를 강제로 생성합니다. ## 이벤트, 기록 및 인터럽션(중단 처리) -`RealtimeSession`은 필요할 때 원문 모델 이벤트도 계속 전달하면서, 더 높은 수준의 SDK 이벤트를 내보냅니다. +`RealtimeSession`은 필요할 때 원문 모델 이벤트를 계속 전달하면서도 더 높은 수준의 SDK 이벤트를 내보냅니다. -가치가 높은 세션 이벤트는 다음과 같습니다. +유용한 세션 이벤트는 다음과 같습니다. -- `audio`, `audio_end`, `audio_interrupted` -- `agent_start`, `agent_end` -- `tool_start`, `tool_end`, `tool_approval_required` -- `handoff` -- `history_added`, `history_updated` -- `guardrail_tripped` -- `input_audio_timeout_triggered` -- `error` -- `raw_model_event` +- `audio`, `audio_end`, `audio_interrupted` +- `agent_start`, `agent_end` +- `tool_start`, `tool_end`, `tool_approval_required` +- `handoff` +- `history_added`, `history_updated` +- `guardrail_tripped` +- `input_audio_timeout_triggered` +- `error` +- `raw_model_event` -UI 상태에 가장 유용한 이벤트는 대개 `history_added`와 `history_updated`입니다. 이 이벤트들은 사용자 메시지, 어시스턴트 메시지, 도구 호출을 포함한 세션의 로컬 기록을 `RealtimeItem` 객체로 노출합니다. +UI 상태에 가장 유용한 이벤트는 일반적으로 `history_added`와 `history_updated`입니다. 이 이벤트들은 사용자 메시지, 어시스턴트 메시지, 도구 호출을 포함해 세션의 로컬 기록을 `RealtimeItem` 객체로 노출합니다. ### 인터럽션(중단 처리) 및 재생 추적 -사용자가 어시스턴트를 중단하면, 세션은 `audio_interrupted`를 내보내고 기록을 업데이트하여 서버 측 대화가 사용자가 실제로 들은 내용과 일치하도록 유지합니다. +사용자가 어시스턴트를 중단하면 세션은 `audio_interrupted`를 내보내고, 사용자가 실제로 들은 내용과 서버 측 대화가 일치하도록 기록을 업데이트합니다. -지연 시간이 낮은 로컬 재생에서는 기본 재생 추적기로 충분한 경우가 많습니다. 원격 또는 지연 재생 시나리오, 특히 전화 통신에서는 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]를 사용하여 인터럽션(중단 처리) 잘림이 생성된 모든 오디오가 이미 들렸다고 가정하는 대신 실제 재생 진행률을 기준으로 하도록 하세요. +지연 시간이 낮은 로컬 재생에서는 기본 재생 추적기로 충분한 경우가 많습니다. 원격 또는 지연된 재생 시나리오, 특히 전화 통신에서는 생성된 모든 오디오를 이미 들었다고 가정하는 대신 실제 재생 진행률을 기준으로 인터럽션(중단 처리) 잘라내기가 수행되도록 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]를 사용하세요. -[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py)의 Twilio 예제는 이 패턴을 보여 줍니다. +[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py)의 Twilio 예제는 이 패턴을 보여줍니다. ## 도구, 승인, 핸드오프 및 가드레일 @@ -220,11 +220,11 @@ async for event in session: await session.approve_tool_call(event.call_id) ``` -구체적인 서버 측 승인 루프는 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)를 참조하세요. 휴먼인더루프 (HITL) 문서도 [휴먼인더루프 (HITL)](../human_in_the_loop.md)에서 이 흐름을 다시 안내합니다. +구체적인 서버 측 승인 루프는 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)를 참고하세요. 휴먼인더루프 (HITL) 문서의 [휴먼인더루프 (HITL)](../human_in_the_loop.md) 섹션에서도 이 흐름을 참조합니다. ### 핸드오프 -실시간 핸드오프를 사용하면 한 에이전트가 라이브 대화를 다른 전문가에게 전달할 수 있습니다. +실시간 핸드오프를 사용하면 한 에이전트가 라이브 대화를 다른 전문가에게 넘길 수 있습니다. ```python from agents.realtime import RealtimeAgent, realtime_handoff @@ -241,11 +241,11 @@ main_agent = RealtimeAgent( ) ``` -단순 `RealtimeAgent` 핸드오프는 자동으로 래핑되며, `realtime_handoff(...)`를 사용하면 이름, 설명, 검증, 콜백, 사용 가능 여부를 사용자 지정할 수 있습니다. 실시간 핸드오프는 일반 핸드오프 `input_filter`를 지원하지 않습니다. +단독 `RealtimeAgent` 핸드오프는 자동으로 래핑되며, `realtime_handoff(...)`를 사용하면 이름, 설명, 검증, 콜백, 사용 가능 여부를 사용자 지정할 수 있습니다. 실시간 핸드오프는 일반 핸드오프의 `input_filter`를 지원하지 **않습니다**. ### 가드레일 -실시간 에이전트에는 출력 가드레일만 지원됩니다. 출력 가드레일은 모든 부분 토큰마다 실행되는 대신 디바운스된 트랜스크립트 누적에 대해 실행되며, 예외를 발생시키는 대신 `guardrail_tripped`를 내보냅니다. +실시간 에이전트는 출력 가드레일만 지원합니다. 출력 가드레일은 모든 부분 토큰마다가 아니라 디바운스된 트랜스크립트 누적에 대해 실행되며, 예외를 발생시키는 대신 `guardrail_tripped`를 내보냅니다. ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -265,17 +265,17 @@ agent = RealtimeAgent( ) ``` -실시간 출력 가드레일이 트립되면, 세션은 활성 응답을 중단하고 -`response.cancel`을 강제하며, `guardrail_tripped`를 내보내고, 트리거된 -가드레일의 이름을 포함한 후속 사용자 메시지를 보내 모델이 대체 응답을 생성할 수 있게 합니다. 오디오 플레이어는 여전히 -`audio_interrupted`를 수신하고 로컬 재생을 즉시 중지해야 합니다. 가드레일은 -디바운스된 트랜스크립트 텍스트에 대해 실행되며, 트립와이어가 발동할 때 일부 오디오가 이미 버퍼링되어 있을 수 있기 때문입니다. +실시간 출력 가드레일이 발동하면 세션은 활성 응답을 중단하고, +`response.cancel`을 강제하며, `guardrail_tripped`를 내보내고, 트리거된 가드레일의 이름을 포함한 +후속 사용자 메시지를 보내 모델이 대체 응답을 생성할 수 있게 합니다. 가드레일은 +디바운스된 트랜스크립트 텍스트에서 실행되고 트립와이어가 작동할 때 일부 오디오가 이미 버퍼링되어 있을 수 있으므로, 오디오 플레이어는 여전히 +`audio_interrupted`를 수신하고 로컬 재생을 즉시 중지해야 합니다. ## SIP 및 전화 통신 -Python SDK는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]를 통해 일급 SIP 연결 플로를 포함합니다. +Python SDK에는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]를 통한 일급 SIP 연결(attach) 흐름이 포함되어 있습니다. -Realtime Calls API를 통해 전화가 도착하고, 결과 `call_id`에 에이전트 세션을 연결하려는 경우 사용하세요. +Realtime Calls API를 통해 전화가 들어오고 그 결과 `call_id`에 에이전트 세션을 연결하려는 경우 사용하세요. ```python from agents.realtime import RealtimeRunner @@ -292,7 +292,7 @@ async with await runner.run( ... ``` -먼저 통화를 수락해야 하고 수락 페이로드가 에이전트에서 파생된 세션 구성과 일치하길 원한다면 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`를 사용하세요. 전체 흐름은 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)에 나와 있습니다. +먼저 전화를 수락해야 하고 accept 페이로드가 에이전트에서 파생된 세션 구성과 일치하길 원한다면 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`를 사용하세요. 전체 흐름은 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)에 나와 있습니다. ## 저수준 접근 및 사용자 지정 엔드포인트 @@ -300,23 +300,23 @@ async with await runner.run( 다음이 필요할 때 사용하세요. -- `session.model.add_listener(...)`를 통한 사용자 지정 리스너 -- `response.create` 또는 `session.update` 같은 원문 클라이언트 이벤트 -- `model_config`를 통한 사용자 지정 `url`, `headers` 또는 `api_key` 처리 -- 기존 실시간 통화에 `call_id` 연결 +- `session.model.add_listener(...)`를 통한 사용자 지정 리스너 +- `response.create` 또는 `session.update` 같은 원문 클라이언트 이벤트 +- `model_config`를 통한 사용자 지정 `url`, `headers` 또는 `api_key` 처리 +- 기존 실시간 호출에 대한 `call_id` 연결 `RealtimeModelConfig`는 다음을 지원합니다. -- `api_key` -- `url` -- `headers` -- `initial_model_settings` -- `playback_tracker` -- `call_id` +- `api_key` +- `url` +- `headers` +- `initial_model_settings` +- `playback_tracker` +- `call_id` -이 저장소에 포함된 `call_id` 예제는 SIP입니다. 더 넓은 Realtime API도 일부 서버 측 제어 흐름에서 `call_id`를 사용하지만, 여기에서는 Python 예제로 패키징되어 있지 않습니다. +이 리포지토리에 포함되어 제공되는 `call_id` 예제는 SIP입니다. 더 넓은 Realtime API에서도 일부 서버 측 제어 흐름에 `call_id`를 사용하지만, 여기에는 Python 예제로 패키징되어 있지 않습니다. -Azure OpenAI에 연결할 때는 GA Realtime 엔드포인트 URL과 명시적 헤더를 전달하세요. 예를 들면 다음과 같습니다. +Azure OpenAI에 연결할 때는 GA Realtime 엔드포인트 URL과 명시적인 헤더를 전달하세요. 예를 들면 다음과 같습니다. ```python session = await runner.run( @@ -327,7 +327,7 @@ session = await runner.run( ) ``` -토큰 기반 인증에는 `headers`에 전달자 토큰을 사용하세요. +토큰 기반 인증에는 `headers`에 베어러 토큰을 사용하세요. ```python session = await runner.run( @@ -338,12 +338,12 @@ session = await runner.run( ) ``` -`headers`를 전달하면 SDK는 `Authorization`을 자동으로 추가하지 않습니다. 실시간 에이전트와 함께 레거시 베타 경로(`/openai/realtime?api-version=...`)는 피하세요. +`headers`를 전달하면 SDK가 `Authorization`을 자동으로 추가하지 않습니다. 실시간 에이전트에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요. ## 추가 자료 -- [실시간 전송](transport.md) -- [빠른 시작](quickstart.md) -- [OpenAI Realtime 대화](https://developers.openai.com/api/docs/guides/realtime-conversations/) -- [OpenAI Realtime 서버 측 제어](https://developers.openai.com/api/docs/guides/realtime-server-controls/) -- [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) \ No newline at end of file +- [실시간 전송](transport.md) +- [빠른 시작](quickstart.md) +- [OpenAI Realtime 대화](https://developers.openai.com/api/docs/guides/realtime-conversations/) +- [OpenAI Realtime 서버 측 제어](https://developers.openai.com/api/docs/guides/realtime-server-controls/) +- [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) \ No newline at end of file diff --git a/docs/ko/realtime/quickstart.md b/docs/ko/realtime/quickstart.md index ba08973dbe..69b775e0e4 100644 --- a/docs/ko/realtime/quickstart.md +++ b/docs/ko/realtime/quickstart.md @@ -4,15 +4,15 @@ search: --- # 빠른 시작 -Python SDK의 실시간 에이전트는 WebSocket 전송 기반 OpenAI Realtime API 위에 구축된 서버 측 저지연 에이전트입니다. +Realtime agents는 WebSocket 전송을 통한 OpenAI Realtime API 기반의 서버 측 저지연 에이전트입니다. !!! warning "베타 기능" - 실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다. + Realtime agents는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다. !!! note "Python SDK 범위" - Python SDK는 브라우저 WebRTC 전송을 제공하지 **않습니다**. 이 페이지에서는 서버 측 WebSocket을 통한 Python 관리 실시간 세션만 다룹니다. 서버 측 오케스트레이션, 도구, 승인, 텔레포니 통합에는 이 SDK를 사용하세요. [실시간 전송](transport.md)도 참고하세요. + Python SDK는 브라우저 WebRTC 전송을 **제공하지 않습니다**. 이 페이지에서는 서버 측 WebSocket을 통한 Python 관리 실시간 세션만 다룹니다. 서버 측 오케스트레이션, 도구, 승인, 전화 통신 통합에는 이 SDK를 사용하세요. [Realtime 전송](transport.md)도 참조하세요. ## 사전 요구 사항 @@ -22,7 +22,7 @@ Python SDK의 실시간 에이전트는 WebSocket 전송 기반 OpenAI Realtime ## 설치 -아직 설치하지 않았다면 OpenAI Agents SDK를 설치하세요. +아직 설치하지 않았다면 OpenAI Agents SDK를 설치하세요: ```bash pip install openai-agents @@ -30,7 +30,7 @@ pip install openai-agents ## 서버 측 실시간 세션 생성 -### 1. 실시간 컴포넌트 가져오기 +### 1. realtime 구성 요소 가져오기 ```python import asyncio @@ -47,9 +47,9 @@ agent = RealtimeAgent( ) ``` -### 3. runner 구성 +### 3. 러너 구성 -새 코드에는 중첩된 `audio.input` / `audio.output` 세션 설정 형태를 권장합니다. 새 실시간 에이전트의 경우 `gpt-realtime-2`로 시작하세요. +새 코드에서는 중첩된 `audio.input` / `audio.output` 세션 설정 형식을 사용하는 것이 좋습니다. 새 Realtime agents에서는 `gpt-realtime-2`로 시작하세요. ```python runner = RealtimeRunner( @@ -104,59 +104,59 @@ if __name__ == "__main__": asyncio.run(main()) ``` -`session.send_message()`는 일반 문자열 또는 구조화된 실시간 메시지를 받습니다. 원문 오디오 청크의 경우 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요. +`session.send_message()`는 일반 문자열 또는 구조화된 실시간 메시지를 허용합니다. 원문 오디오 청크의 경우 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요. -## 이 빠른 시작에 포함되지 않는 항목 +## 이 빠른 시작에 포함되지 않는 내용 -- 마이크 캡처 및 스피커 재생 코드. [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 실시간 예제를 참고하세요. -- SIP / 텔레포니 연결 흐름. [실시간 전송](transport.md)과 [SIP 섹션](guide.md#sip-and-telephony)을 참고하세요. +- 마이크 캡처 및 스피커 재생 코드. [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 실시간 코드 예제를 참조하세요. +- SIP / 전화 통신 연결 흐름. [Realtime 전송](transport.md) 및 [SIP 섹션](guide.md#sip-and-telephony)을 참조하세요. ## 주요 설정 -기본 세션이 작동하면, 대부분의 사람들이 다음으로 찾는 설정은 다음과 같습니다. +기본 세션이 작동하면 대부분 다음 설정을 살펴봅니다: - `model_name` - `audio.input.format`, `audio.output.format` - `audio.input.transcription` - `audio.input.noise_reduction` -- 자동 턴 감지를 위한 `audio.input.turn_detection` +- `audio.input.turn_detection`: 자동 턴 감지용 - `audio.output.voice` - `tool_choice`, `prompt`, `tracing` - `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter` -`input_audio_format`, `output_audio_format`, `input_audio_transcription`, `turn_detection` 같은 이전의 평면 별칭도 여전히 작동하지만, 새 코드에는 중첩된 `audio` 설정을 권장합니다. +`input_audio_format`, `output_audio_format`, `input_audio_transcription`, `turn_detection` 같은 이전 플랫 별칭도 계속 작동하지만, 새 코드에는 중첩된 `audio` 설정을 사용하는 것이 좋습니다. -수동 턴 제어에는 [실시간 에이전트 가이드](guide.md#manual-response-control)에 설명된 것처럼 원문 `session.update` / `input_audio_buffer.commit` / `response.create` 흐름을 사용하세요. +수동 턴 제어에는 [Realtime agents 가이드](guide.md#manual-response-control)에 설명된 원문 `session.update` / `input_audio_buffer.commit` / `response.create` 흐름을 사용하세요. -전체 스키마는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참고하세요. +전체 스키마는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참조하세요. ## 연결 옵션 -환경에서 API 키를 설정하세요. +환경에 API 키를 설정하세요: ```bash export OPENAI_API_KEY="your-api-key-here" ``` -또는 세션을 시작할 때 직접 전달하세요. +또는 세션을 시작할 때 직접 전달하세요: ```python session = await runner.run(model_config={"api_key": "your-api-key"}) ``` -`model_config`는 다음도 지원합니다. +`model_config`는 다음도 지원합니다: - `url`: 사용자 지정 WebSocket 엔드포인트 - `headers`: 사용자 지정 요청 헤더 -- `call_id`: 기존 실시간 호출에 연결합니다. 이 저장소에서 문서화된 연결 흐름은 SIP입니다. -- `playback_tracker`: 사용자가 실제로 들은 오디오 양을 보고합니다 +- `call_id`: 기존 실시간 호출에 연결합니다. 이 리포지토리에서 문서화된 연결 흐름은 SIP입니다. +- `playback_tracker`: 사용자가 실제로 들은 오디오의 양을 보고합니다 -`headers`를 명시적으로 전달하면 SDK가 `Authorization` 헤더를 대신 삽입하지 **않습니다**. +`headers`를 명시적으로 전달하면 SDK가 `Authorization` 헤더를 **삽입하지 않습니다**. -Azure OpenAI에 연결할 때는 `model_config["url"]`에 GA Realtime 엔드포인트 URL과 명시적 헤더를 전달하세요. 실시간 에이전트에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요. 자세한 내용은 [실시간 에이전트 가이드](guide.md#low-level-access-and-custom-endpoints)를 참고하세요. +Azure OpenAI에 연결할 때는 `model_config["url"]`에 GA Realtime 엔드포인트 URL과 명시적 헤더를 전달하세요. Realtime agents에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요. 자세한 내용은 [Realtime agents 가이드](guide.md#low-level-access-and-custom-endpoints)를 참조하세요. ## 다음 단계 -- 서버 측 WebSocket과 SIP 중 선택하려면 [실시간 전송](transport.md)을 읽어보세요. -- 수명 주기, 구조화된 입력, 승인, 핸드오프, 가드레일, 저수준 제어에 대해서는 [실시간 에이전트 가이드](guide.md)를 읽어보세요. -- [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 예제를 살펴보세요. \ No newline at end of file +- 서버 측 WebSocket과 SIP 중 선택하려면 [Realtime 전송](transport.md)을 읽어보세요. +- 생명주기, 구조화된 입력, 승인, 핸드오프, 가드레일, 저수준 제어는 [Realtime agents 가이드](guide.md)를 읽어보세요. +- [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 코드 예제를 살펴보세요. \ No newline at end of file diff --git a/docs/ko/realtime/transport.md b/docs/ko/realtime/transport.md index 5cfc7ea3f6..3eed05a87f 100644 --- a/docs/ko/realtime/transport.md +++ b/docs/ko/realtime/transport.md @@ -2,75 +2,75 @@ search: exclude: true --- -# 실시간 전송 +# 실시간 전송 방식 -이 페이지를 사용해 실시간 에이전트가 Python 애플리케이션에 어떻게 맞는지 결정하세요 +이 페이지를 사용하여 실시간 에이전트가 Python 애플리케이션에 어떻게 적합한지 결정하세요. !!! note "Python SDK 경계" - Python SDK에는 브라우저 WebRTC 전송이 **포함되지 않습니다**. 이 페이지는 Python SDK 전송 선택지만 다룹니다: 서버 측 WebSocket 및 SIP 연결 플로우. 브라우저 WebRTC는 별도의 플랫폼 주제이며, 공식 [WebRTC와 함께하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 가이드에 문서화되어 있습니다. + Python SDK에는 브라우저 WebRTC 전송이 **포함되지 않습니다**. 이 페이지는 Python SDK 전송 선택지, 즉 서버 측 WebSocket 및 SIP 연결 플로우만 다룹니다. 브라우저 WebRTC는 별도의 플랫폼 주제이며, 공식 [WebRTC를 사용하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 가이드에 문서화되어 있습니다. ## 결정 가이드 -| 목표 | 시작점 | 이유 | +| 목표 | 시작 위치 | 이유 | | --- | --- | --- | -| 서버에서 관리하는 실시간 앱 구축 | [빠른 시작](quickstart.md) | 기본 Python 경로는 `RealtimeRunner`가 관리하는 서버 측 WebSocket 세션입니다. | -| 어떤 전송 및 배포 형태를 선택할지 이해 | 이 페이지 | 전송 또는 배포 형태를 확정하기 전에 이 페이지를 사용하세요. | -| 전화 또는 SIP 통화에 에이전트 연결 | [실시간 가이드](guide.md) 및 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 이 저장소는 `call_id`로 구동되는 SIP 연결 플로우를 제공합니다. | +| 서버가 관리하는 실시간 앱 빌드 | [빠른 시작](quickstart.md) | 기본 Python 경로는 `RealtimeRunner`가 관리하는 서버 측 WebSocket 세션입니다. | +| 어떤 전송 방식과 배포 형태를 선택해야 하는지 이해 | 이 페이지 | 전송 방식이나 배포 형태를 확정하기 전에 이 페이지를 사용하세요. | +| 에이전트를 전화 또는 SIP 통화에 연결 | [실시간 가이드](guide.md) 및 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 이 저장소에는 `call_id`로 구동되는 SIP 연결 플로우가 포함되어 있습니다. | -## 서버 측 WebSocket 기본 Python 경로 +## 기본 Python 경로인 서버 측 WebSocket -`RealtimeRunner`는 사용자 정의 `RealtimeModel`을 전달하지 않는 한 `OpenAIRealtimeWebSocketModel`을 사용합니다. +커스텀 `RealtimeModel`을 전달하지 않으면 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용합니다. -즉, 표준 Python 토폴로지는 다음과 같습니다: +즉, 표준 Python 토폴로지는 다음과 같습니다. 1. Python 서비스가 `RealtimeRunner`를 생성합니다. 2. `await runner.run()`이 `RealtimeSession`을 반환합니다. -3. 세션에 진입하고 텍스트, structured outputs 메시지 또는 오디오를 전송합니다. -4. `RealtimeSessionEvent` 항목을 소비하고 오디오 또는 전사본을 애플리케이션으로 전달합니다. +3. 세션에 진입하여 텍스트, 구조화된 메시지 또는 오디오를 전송합니다. +4. `RealtimeSessionEvent` 항목을 소비하고 오디오 또는 대본을 애플리케이션으로 전달합니다. -이 토폴로지는 핵심 데모 앱, CLI 예제, Twilio Media Streams 예제에서 사용됩니다: +이 토폴로지는 핵심 데모 앱, CLI 예제, Twilio Media Streams 예제에서 사용됩니다. - [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app) - [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli) - [`examples/realtime/twilio`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio) -서버가 오디오 파이프라인, 도구 실행, 승인 플로우, 히스토리 처리를 소유하는 경우 이 경로를 사용하세요. +서버가 오디오 파이프라인, 도구 실행, 승인 플로우, 기록 처리를 담당할 때 이 경로를 사용하세요. -## SIP 연결 전화 통신 경로 +## 전화 통신 경로인 SIP 연결 -이 저장소에 문서화된 전화 통신 플로우에서는 Python SDK가 `call_id`를 통해 기존 실시간 통화에 연결됩니다. +이 저장소에 문서화된 전화 통신 플로우에서 Python SDK는 `call_id`를 통해 기존 실시간 통화에 연결합니다. -이 토폴로지는 다음과 같습니다: +이 토폴로지는 다음과 같습니다. -1. OpenAI가 `realtime.call.incoming` 같은 webhook을 서비스로 보냅니다. +1. OpenAI가 `realtime.call.incoming`과 같은 웹훅을 서비스로 보냅니다. 2. 서비스가 Realtime Calls API를 통해 통화를 수락합니다. -3. Python 서비스가 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`를 시작합니다. -4. 세션이 `model_config={"call_id": ...}`로 연결된 뒤, 다른 실시간 세션과 동일하게 이벤트를 처리합니다. +3. Python 서비스가 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`을 시작합니다. +4. 세션이 `model_config={"call_id": ...}`로 연결된 다음, 다른 실시간 세션과 마찬가지로 이벤트를 처리합니다. 이 토폴로지는 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip)에 나와 있습니다. 더 넓은 Realtime API도 일부 서버 측 제어 패턴에 `call_id`를 사용하지만, 이 저장소에서 제공되는 연결 예제는 SIP입니다. -## 이 SDK 범위 외 브라우저 WebRTC +## 이 SDK 범위 밖의 브라우저 WebRTC -앱의 기본 클라이언트가 Realtime WebRTC를 사용하는 브라우저인 경우: +앱의 주 클라이언트가 Realtime WebRTC를 사용하는 브라우저인 경우: -- 이 저장소의 Python SDK 문서 범위 밖으로 간주하세요 -- 클라이언트 측 플로우와 이벤트 모델은 공식 [WebRTC와 함께하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 및 [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) 문서를 사용하세요 -- 브라우저 WebRTC 클라이언트 위에 사이드밴드 서버 연결이 필요하면 공식 [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 가이드를 사용하세요 -- 이 저장소에서 브라우저 측 `RTCPeerConnection` 추상화나 즉시 사용 가능한 브라우저 WebRTC 샘플을 제공한다고 기대하지 마세요 +- 이 저장소의 Python SDK 문서 범위 밖으로 간주하세요. +- 클라이언트 측 플로우와 이벤트 모델에는 공식 [WebRTC를 사용하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 및 [실시간 대화](https://developers.openai.com/api/docs/guides/realtime-conversations/) 문서를 사용하세요. +- 브라우저 WebRTC 클라이언트 위에 사이드밴드 서버 연결이 필요한 경우 공식 [실시간 서버 측 제어](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 가이드를 사용하세요. +- 이 저장소가 브라우저 측 `RTCPeerConnection` 추상화나 바로 사용할 수 있는 브라우저 WebRTC 샘플을 제공한다고 기대하지 마세요. 또한 이 저장소는 현재 브라우저 WebRTC와 Python 사이드밴드를 함께 사용하는 예제를 제공하지 않습니다. -## 사용자 정의 엔드포인트 및 연결 지점 +## 커스텀 엔드포인트 및 연결 지점 -[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig]의 전송 구성 표면을 통해 기본 경로를 조정할 수 있습니다: +[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig]의 전송 구성 인터페이스를 사용하면 기본 경로를 조정할 수 있습니다. - `url`: WebSocket 엔드포인트 재정의 -- `headers`: Azure 인증 헤더 같은 명시적 헤더 제공 +- `headers`: Azure 인증 헤더와 같은 명시적 헤더 제공 - `api_key`: API 키를 직접 또는 콜백을 통해 전달 -- `call_id`: 기존 실시간 통화에 연결. 이 저장소에서 문서화된 예제는 SIP입니다 +- `call_id`: 기존 실시간 통화에 연결. 이 저장소에서 문서화된 예제는 SIP입니다. - `playback_tracker`: 인터럽션(중단 처리)을 위해 실제 재생 진행 상황 보고 -토폴로지를 선택한 후 자세한 수명 주기 및 기능 표면은 [실시간 에이전트 가이드](guide.md)를 참조하세요. \ No newline at end of file +토폴로지를 선택한 후의 상세한 생명주기와 기능 범위는 [실시간 에이전트 가이드](guide.md)를 참조하세요. \ No newline at end of file diff --git a/docs/ko/release.md b/docs/ko/release.md index a3015d7715..2eaacb0d3a 100644 --- a/docs/ko/release.md +++ b/docs/ko/release.md @@ -4,30 +4,30 @@ 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.17.0 -이 버전에서는 소스 경로가 `Manifest.extra_path_grants`에 의해 포함되지 않는 한, 샌드박스 로컬 소스 구체화가 `LocalFile.src`와 `LocalDir.src`를 구체화 `base_dir` 안에 유지합니다. `base_dir`은 매니페스트가 적용될 때 SDK 프로세스의 현재 작업 디렉터리입니다. 상대 로컬 소스는 해당 디렉터리에서 해석되며, 절대 로컬 소스는 이미 그 안에 있거나 명시적 허가 아래에 있어야 합니다. 이는 로컬 아티팩트 경계 문제를 해결하지만, 해당 기본 디렉터리 외부의 신뢰할 수 있는 호스트 파일이나 디렉터리를 샌드박스 작업 공간으로 의도적으로 복사하는 애플리케이션에 영향을 줄 수 있습니다. +이 버전에서는 샌드박스 로컬 소스 구체화가 소스 경로가 `Manifest.extra_path_grants`에 포함되지 않는 한 `LocalFile.src`와 `LocalDir.src`를 구체화 `base_dir` 내에 유지합니다. `base_dir`는 매니페스트가 적용될 때 SDK 프로세스의 현재 작업 디렉터리입니다. 상대 로컬 소스는 이 디렉터리를 기준으로 해석되며, 절대 로컬 소스는 이미 그 안에 있거나 명시적 허용 범위 아래에 있어야 합니다. 이는 로컬 아티팩트 경계 문제를 해결하지만, 해당 기본 디렉터리 밖의 신뢰할 수 있는 호스트 파일이나 디렉터리를 샌드박스 워크스페이스로 의도적으로 복사하는 애플리케이션에는 영향을 줄 수 있습니다. -마이그레이션하려면 `SandboxPathGrant`를 사용해 매니페스트 수준에서 신뢰할 수 있는 호스트 루트에 권한을 부여하고, 샌드박스가 해당 파일을 읽기만 하면 되는 경우에는 읽기 전용으로 설정하는 것이 좋습니다. +마이그레이션하려면 매니페스트 수준에서 `SandboxPathGrant`로 신뢰할 수 있는 호스트 루트를 허용하세요. 샌드박스가 해당 파일을 읽기만 하면 되는 경우 읽기 전용으로 설정하는 것이 좋습니다. ```python from pathlib import Path @@ -54,28 +54,28 @@ manifest = Manifest( ) ``` -`extra_path_grants`는 신뢰할 수 있는 애플리케이션 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않은 한, 모델 출력이나 기타 신뢰할 수 없는 매니페스트 입력에서 권한 부여 항목을 채우지 마세요. +`extra_path_grants`를 신뢰할 수 있는 애플리케이션 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인한 경우가 아니라면 모델 출력이나 기타 신뢰할 수 없는 매니페스트 입력에서 허용 범위를 채우지 마세요. ### 0.16.0 -이 버전에서는 SDK 기본 모델이 `gpt-4.1` 대신 `gpt-5.4-mini`가 되었습니다. 이는 모델을 명시적으로 설정하지 않은 에이전트와 실행에 영향을 줍니다. 새 기본값이 GPT-5 모델이므로, 암시적 기본 모델 설정에는 이제 `reasoning.effort="none"` 및 `verbosity="low"` 같은 GPT-5 기본값이 포함됩니다. +이 버전에서는 SDK 기본 모델이 `gpt-4.1` 대신 `gpt-5.4-mini`로 변경되었습니다. 이는 모델을 명시적으로 설정하지 않은 에이전트와 실행에 영향을 줍니다. 새 기본값이 GPT-5 모델이므로, 암시적 기본 모델 설정에는 이제 `reasoning.effort="none"` 및 `verbosity="low"` 같은 GPT-5 기본값이 포함됩니다. -이전 기본 모델 동작을 유지해야 한다면, 에이전트 또는 실행 구성에 모델을 명시적으로 설정하거나 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. +이전 기본 모델 동작을 유지해야 하는 경우 에이전트나 실행 구성에서 모델을 명시적으로 설정하거나 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요. ```python agent = Agent(name="Assistant", model="gpt-4.1") ``` -주요 내용: +주요 사항: -- `Runner.run`, `Runner.run_sync`, `Runner.run_streamed`는 이제 턴 제한을 비활성화하기 위해 `max_turns=None`을 허용합니다. -- 샌드박스 작업 공간 하이드레이션은 이제 로컬, Docker, 제공자 지원 샌드박스 구현 전반에서 절대 심볼릭 링크 대상을 포함하여 아카이브 루트 외부를 가리키는 심볼릭 링크가 있는 tar 아카이브를 거부합니다. +- 이제 `Runner.run`, `Runner.run_sync`, `Runner.run_streamed`는 턴 제한을 비활성화하기 위해 `max_turns=None`을 허용합니다. +- 이제 샌드박스 워크스페이스 하이드레이션은 로컬, Docker, 공급자 기반 샌드박스 구현 전반에서 절대 심볼릭 링크 대상을 포함해 아카이브 루트 밖을 가리키는 심볼릭 링크가 있는 tar 아카이브를 거부합니다. ### 0.15.0 -이 버전에서는 모델 거부가 빈 텍스트 출력으로 처리되거나, structured outputs의 경우 실행 루프가 `MaxTurnsExceeded`가 될 때까지 재시도하게 하는 대신, `ModelRefusalError`로 명시적으로 드러납니다. +이 버전에서는 모델 거부가 빈 텍스트 출력으로 처리되거나, structured outputs의 경우 실행 루프가 `MaxTurnsExceeded`까지 재시도하게 하는 대신 `ModelRefusalError`로 명시적으로 노출됩니다. -이는 이전에 거부만 포함된 모델 응답이 `final_output == ""`로 완료될 것으로 기대하던 코드에 영향을 줍니다. 예외를 발생시키지 않고 거부를 처리하려면 `model_refusal` 실행 오류 핸들러를 제공하세요. +이전에는 거부만 포함된 모델 응답이 `final_output == ""`로 완료되기를 기대하던 코드에 영향을 줍니다. 예외를 발생시키지 않고 거부를 처리하려면 `model_refusal` 실행 오류 핸들러를 제공하세요. ```python result = Runner.run_sync( @@ -85,81 +85,81 @@ result = Runner.run_sync( ) ``` -structured-output 에이전트의 경우, 핸들러는 에이전트의 출력 스키마와 일치하는 값을 반환할 수 있으며 SDK는 이를 다른 실행 오류 핸들러의 최종 출력과 마찬가지로 검증합니다. +structured-output 에이전트의 경우 핸들러는 에이전트의 출력 스키마와 일치하는 값을 반환할 수 있으며, SDK는 다른 실행 오류 핸들러의 최종 출력과 마찬가지로 이를 검증합니다. ### 0.14.0 -이 마이너 릴리스는 호환성이 깨지는 변경을 도입하지는 **않지만**, 주요한 새 베타 기능 영역인 Sandbox Agents와 이를 로컬, 컨테이너화된 환경, 호스팅 환경 전반에서 사용하는 데 필요한 런타임, 백엔드, 문서 지원을 추가합니다. +이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, 주요 새 베타 기능 영역인 샌드박스 에이전트와 이를 로컬, 컨테이너화된 환경, 호스팅 환경 전반에서 사용하는 데 필요한 런타임, 백엔드, 문서 지원을 추가합니다. -주요 내용: +주요 사항: -- `SandboxAgent`, `Manifest`, `SandboxRunConfig`를 중심으로 한 새로운 베타 샌드박스 런타임 표면을 추가하여, 에이전트가 파일, 디렉터리, Git 리포지터리, 마운트, 스냅샷, 재개 지원이 있는 영구 격리 작업 공간 안에서 작업할 수 있게 했습니다. -- `UnixLocalSandboxClient` 및 `DockerSandboxClient`를 통해 로컬 및 컨테이너화된 개발을 위한 샌드박스 실행 백엔드를 추가했으며, 선택적 extras를 통해 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel에 대한 호스팅 제공자 통합을 추가했습니다. -- 향후 실행이 이전 실행의 교훈을 재사용할 수 있도록 샌드박스 메모리 지원을 추가했으며, 점진적 공개, 멀티 턴 그룹화, 구성 가능한 격리 경계, S3 기반 워크플로를 포함한 영속 메모리 예제를 제공합니다. -- 로컬 및 합성 작업 공간 항목, S3/R2/GCS/Azure Blob Storage/S3 Files용 원격 스토리지 마운트, 이식 가능한 스냅샷, `RunState`, `SandboxSessionState` 또는 저장된 스냅샷을 통한 재개 흐름을 포함하여 더 넓은 작업 공간 및 재개 모델을 추가했습니다. -- `examples/sandbox/` 아래에 기술을 사용한 코딩 작업, 핸드오프, 메모리, 제공자별 설정, 코드 리뷰, 데이터룸 QA, 웹사이트 클로닝 같은 엔드투엔드 워크플로를 다루는 상당한 규모의 샌드박스 예제와 튜토리얼을 추가했습니다. -- 샌드박스 인식 세션 준비, 기능 바인딩, 상태 직렬화, 통합 트레이싱, 프롬프트 캐시 키 기본값, 더 안전한 민감한 MCP 출력 비식별화를 통해 코어 런타임과 트레이싱 스택을 확장했습니다. +- `SandboxAgent`, `Manifest`, `SandboxRunConfig`를 중심으로 하는 새로운 베타 샌드박스 런타임 표면을 추가하여 에이전트가 파일, 디렉터리, Git 리포지토리, 마운트, 스냅샷, 재개 지원이 있는 지속적인 격리 워크스페이스 내에서 작업할 수 있게 했습니다. +- `UnixLocalSandboxClient`와 `DockerSandboxClient`를 통한 로컬 및 컨테이너화된 개발용 샌드박스 실행 백엔드를 추가했으며, 선택적 extras를 통해 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel용 호스팅 공급자 통합을 추가했습니다. +- 이후 실행에서 이전 실행의 교훈을 재사용할 수 있도록 샌드박스 메모리 지원을 추가했으며, 점진적 공개, 멀티턴 그룹화, 구성 가능한 격리 경계, S3 기반 워크플로를 포함한 지속 메모리 예제를 제공합니다. +- 로컬 및 합성 워크스페이스 항목, S3/R2/GCS/Azure Blob Storage/S3 Files용 원격 스토리지 마운트, 이식 가능한 스냅샷, `RunState`, `SandboxSessionState` 또는 저장된 스냅샷을 통한 재개 흐름을 포함하여 더 넓은 워크스페이스 및 재개 모델을 추가했습니다. +- `examples/sandbox/` 아래에 풍부한 샌드박스 코드 예제와 튜토리얼을 추가했으며, 스킬, 핸드오프, 메모리, 공급자별 설정을 사용하는 코딩 작업과 코드 리뷰, 데이터룸 QA, 웹사이트 클로닝 같은 엔드투엔드 워크플로를 다룹니다. +- 샌드박스를 인식하는 세션 준비, 기능 바인딩, 상태 직렬화, 통합 트레이싱, 프롬프트 캐시 키 기본값, 더 안전한 민감한 MCP 출력 가리기를 통해 코어 런타임과 트레이싱 스택을 확장했습니다. ### 0.13.0 -이 마이너 릴리스는 호환성이 깨지는 변경을 도입하지는 **않지만**, 주목할 만한 Realtime 기본값 업데이트와 새로운 MCP 기능, 런타임 안정성 수정 사항을 포함합니다. +이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, 주목할 만한 Realtime 기본값 업데이트와 새로운 MCP 기능, 런타임 안정성 수정이 포함되어 있습니다. -주요 내용: +주요 사항: -- 기본 websocket Realtime 모델이 이제 `gpt-realtime-1.5`이므로, 새로운 Realtime 에이전트 설정은 추가 구성 없이 더 새로운 모델을 사용합니다. -- `MCPServer`는 이제 `list_resources()`, `list_resource_templates()`, `read_resource()`를 노출하며, `MCPServerStreamableHttp`는 이제 `session_id`를 노출하여 streamable HTTP 세션을 재연결 또는 상태 비저장 워커 간에 재개할 수 있습니다. -- Chat Completions 통합은 이제 `should_replay_reasoning_content`를 통해 reasoning-content replay를 선택적으로 사용할 수 있어, LiteLLM/DeepSeek 같은 어댑터에서 제공자별 추론/도구 호출 연속성이 향상됩니다. -- `SQLAlchemySession`의 동시 첫 쓰기, reasoning 제거 후 고아 assistant 메시지 ID가 있는 compaction 요청, `remove_all_tools()`가 MCP/reasoning 항목을 남기는 문제, 함수 도구 배치 실행기의 경합 등 여러 런타임 및 세션 엣지 케이스를 수정했습니다. +- 기본 websocket Realtime 모델이 이제 `gpt-realtime-1.5`이므로, 새 Realtime 에이전트 설정은 추가 구성 없이 더 새로운 모델을 사용합니다. +- 이제 `MCPServer`는 `list_resources()`, `list_resource_templates()`, `read_resource()`를 노출하며, `MCPServerStreamableHttp`는 `session_id`를 노출하여 streamable HTTP 세션을 재연결 또는 상태 비저장 워커 전반에서 재개할 수 있습니다. +- 이제 Chat Completions 통합은 `should_replay_reasoning_content`를 통해 추론 콘텐츠 재생을 선택할 수 있으며, LiteLLM/DeepSeek 같은 어댑터에서 공급자별 reasoning/tool-call 연속성을 개선합니다. +- `SQLAlchemySession`의 동시 최초 쓰기, reasoning 제거 후 고아가 된 어시스턴트 메시지 ID가 있는 압축 요청, `remove_all_tools()`가 MCP/reasoning 항목을 남기는 문제, 함수 도구 배치 실행기의 레이스를 포함한 여러 런타임 및 세션 엣지 케이스를 수정했습니다. ### 0.12.0 -이 마이너 릴리스는 호환성이 깨지는 변경을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)를 확인하세요. +이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)를 확인하세요. ### 0.11.0 -이 마이너 릴리스는 호환성이 깨지는 변경을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)를 확인하세요. +이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)를 확인하세요. ### 0.10.0 -이 마이너 릴리스는 호환성이 깨지는 변경을 도입하지는 **않지만**, OpenAI Responses 사용자를 위한 중요한 새 기능 영역인 Responses API용 websocket 전송 지원을 포함합니다. +이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, OpenAI Responses 사용자에게 중요한 새 기능 영역인 Responses API용 websocket 전송 지원을 포함합니다. -주요 내용: +주요 사항: -- OpenAI Responses 모델을 위한 websocket 전송 지원을 추가했습니다(옵트인; HTTP는 기본 전송으로 유지됩니다). -- 멀티 턴 실행 전반에서 공유 websocket 지원 제공자와 `RunConfig`를 재사용하기 위한 `responses_websocket_session()` 헬퍼 / `ResponsesWebSocketSession`을 추가했습니다. -- 스트리밍, 도구, 승인, 후속 턴을 다루는 새로운 websocket 스트리밍 예제(`examples/basic/stream_ws.py`)를 추가했습니다. +- OpenAI Responses 모델에 대한 websocket 전송 지원을 추가했습니다(옵트인 방식이며, HTTP는 기본 전송으로 유지됩니다). +- 멀티턴 실행 전반에서 websocket을 사용할 수 있는 공유 공급자와 `RunConfig`를 재사용하기 위한 `responses_websocket_session()` 헬퍼 / `ResponsesWebSocketSession`을 추가했습니다. +- 스트리밍, 도구, 승인, 후속 턴을 다루는 새 websocket 스트리밍 예제(`examples/basic/stream_ws.py`)를 추가했습니다. ### 0.9.0 -이 버전에서는 Python 3.9가 더 이상 지원되지 않습니다. 이 주 버전은 3개월 전에 EOL에 도달했습니다. 더 최신 런타임 버전으로 업그레이드하세요. +이 버전에서는 Python 3.9가 더 이상 지원되지 않습니다. 이 주요 버전은 3개월 전에 EOL에 도달했기 때문입니다. 더 새로운 런타임 버전으로 업그레이드하세요. -또한 `Agent#as_tool()` 메서드에서 반환되는 값의 타입 힌트가 `Tool`에서 `FunctionTool`로 좁혀졌습니다. 이 변경은 일반적으로 호환성 문제를 일으키지 않지만, 코드가 더 넓은 유니온 타입에 의존하는 경우 일부 조정이 필요할 수 있습니다. +또한 `Agent#as_tool()` 메서드에서 반환되는 값의 타입 힌트가 `Tool`에서 `FunctionTool`로 좁혀졌습니다. 이 변경 사항은 일반적으로 호환성 문제를 일으키지 않지만, 코드가 더 넓은 유니언 타입에 의존하는 경우에는 일부 조정이 필요할 수 있습니다. ### 0.8.0 -이 버전에서는 두 가지 런타임 동작 변경으로 마이그레이션 작업이 필요할 수 있습니다. +이 버전에서는 두 가지 런타임 동작 변경으로 인해 마이그레이션 작업이 필요할 수 있습니다. -- **동기** Python 호출 가능 객체를 래핑하는 함수 도구는 이제 이벤트 루프 스레드에서 실행되는 대신 `asyncio.to_thread(...)`를 통해 워커 스레드에서 실행됩니다. 도구 로직이 스레드 로컬 상태 또는 스레드 종속 리소스에 의존한다면, 비동기 도구 구현으로 마이그레이션하거나 도구 코드에서 스레드 종속성을 명시적으로 처리하세요. -- 로컬 MCP 도구 실패 처리가 이제 구성 가능하며, 기본 동작은 전체 실행을 실패시키는 대신 모델에 보이는 오류 출력을 반환할 수 있습니다. 빠른 실패(fail-fast) 의미 체계에 의존한다면 `mcp_config={"failure_error_function": None}`을 설정하세요. 서버 수준 `failure_error_function` 값은 에이전트 수준 설정을 재정의하므로, 명시적 핸들러가 있는 각 로컬 MCP 서버에 `failure_error_function=None`을 설정하세요. +- **동기** Python 호출 가능 객체를 래핑하는 함수 도구는 이제 이벤트 루프 스레드에서 실행되는 대신 `asyncio.to_thread(...)`를 통해 워커 스레드에서 실행됩니다. 도구 로직이 스레드 로컬 상태 또는 스레드 종속 리소스에 의존하는 경우 비동기 도구 구현으로 마이그레이션하거나 도구 코드에서 스레드 종속성을 명시하세요. +- 로컬 MCP 도구 실패 처리를 이제 구성할 수 있으며, 기본 동작은 전체 실행을 실패시키는 대신 모델에 표시되는 오류 출력을 반환할 수 있습니다. fail-fast 동작에 의존하는 경우 `mcp_config={"failure_error_function": None}`을 설정하세요. 서버 수준 `failure_error_function` 값은 에이전트 수준 설정을 재정의하므로, 명시적 핸들러가 있는 각 로컬 MCP 서버에서 `failure_error_function=None`을 설정하세요. ### 0.7.0 -이 버전에는 기존 애플리케이션에 영향을 줄 수 있는 몇 가지 동작 변경이 있었습니다. +이 버전에서는 기존 애플리케이션에 영향을 줄 수 있는 몇 가지 동작 변경이 있었습니다. - 중첩 핸드오프 기록은 이제 **옵트인**입니다(기본적으로 비활성화됨). v0.6.x의 기본 중첩 동작에 의존했다면 `RunConfig(nest_handoff_history=True)`를 명시적으로 설정하세요. -- `gpt-5.1` / `gpt-5.2`의 기본 `reasoning.effort`가 `"none"`으로 변경되었습니다(SDK 기본값으로 구성된 이전 기본값 `"low"`에서 변경). 프롬프트 또는 품질/비용 프로필이 `"low"`에 의존했다면 `model_settings`에서 명시적으로 설정하세요. +- `gpt-5.1` / `gpt-5.2`의 기본 `reasoning.effort`가 `"none"`으로 변경되었습니다(SDK 기본값으로 구성되던 이전 기본값 `"low"`에서 변경). 프롬프트나 품질/비용 프로필이 `"low"`에 의존했다면 `model_settings`에서 이를 명시적으로 설정하세요. ### 0.6.0 -이 버전에서는 기본 핸드오프 기록이 이제 원문 사용자/assistant 턴을 노출하는 대신 하나의 assistant 메시지로 패키징되어, 다운스트림 에이전트에 간결하고 예측 가능한 요약을 제공합니다 -- 기존 단일 메시지 핸드오프 transcript는 이제 기본적으로 `` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하므로, 다운스트림 에이전트가 명확히 라벨링된 요약을 받습니다 +이 버전에서는 기본 핸드오프 기록이 원문 사용자/어시스턴트 턴을 노출하는 대신 단일 어시스턴트 메시지로 패키징되어, 다운스트림 에이전트에 간결하고 예측 가능한 요약을 제공합니다 +- 기존 단일 메시지 핸드오프 트랜스크립트는 이제 기본적으로 `` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하므로, 다운스트림 에이전트는 명확히 라벨링된 요약을 받습니다. ### 0.5.0 -이 버전은 눈에 보이는 호환성이 깨지는 변경을 도입하지 않지만, 새로운 기능과 내부의 몇 가지 중요한 업데이트를 포함합니다. +이 버전은 눈에 보이는 호환성을 깨는 변경 사항을 도입하지 않지만, 내부적으로 새 기능과 몇 가지 중요한 업데이트를 포함합니다. -- `RealtimeRunner`가 [SIP 프로토콜 연결](https://platform.openai.com/docs/guides/realtime-sip)을 처리할 수 있도록 지원을 추가했습니다 -- Python 3.14 호환성을 위해 `Runner#run_sync`의 내부 로직을 크게 개정했습니다 +- `RealtimeRunner`가 [SIP 프로토콜 연결](https://platform.openai.com/docs/guides/realtime-sip)을 처리하도록 지원을 추가했습니다. +- Python 3.14 호환성을 위해 `Runner#run_sync`의 내부 로직을 크게 수정했습니다. ### 0.4.0 @@ -167,12 +167,12 @@ structured-output 에이전트의 경우, 핸들러는 에이전트의 출력 ### 0.3.0 -이 버전에서는 Realtime API 지원이 gpt-realtime 모델과 그 API 인터페이스(GA 버전)로 마이그레이션됩니다. +이 버전에서는 Realtime API 지원이 gpt-realtime 모델과 해당 API 인터페이스(GA 버전)로 마이그레이션됩니다. ### 0.2.0 -이 버전에서는 이전에 `Agent`를 인수로 받던 몇몇 위치가 이제 대신 `AgentBase`를 인수로 받습니다. 예를 들어 MCP 서버의 `list_tools()` 호출이 있습니다. 이는 순수한 타입 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트하려면 `Agent`를 `AgentBase`로 바꾸어 타입 오류만 수정하면 됩니다. +이 버전에서는 이전에 `Agent`를 인자로 받던 몇몇 위치가 이제 대신 `AgentBase`를 인자로 받습니다. 예를 들어 MCP 서버의 `list_tools()` 호출이 있습니다. 이는 순수 타입 지정 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트하려면 `Agent`를 `AgentBase`로 교체하여 타입 오류만 수정하면 됩니다. ### 0.1.0 -이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 `run_context`와 `agent`라는 두 개의 새 매개변수가 있습니다. `MCPServer`를 서브클래싱하는 모든 클래스에 이 매개변수를 추가해야 합니다. \ No newline at end of file +이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 두 개의 새 매개변수 `run_context`와 `agent`가 추가되었습니다. `MCPServer`를 서브클래싱하는 모든 클래스에 이 매개변수들을 추가해야 합니다. \ No newline at end of file diff --git a/docs/ko/repl.md b/docs/ko/repl.md index e41f4c6ee3..01893a2a63 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 c5eeb4c9b5..583abd54d6 100644 --- a/docs/ko/results.md +++ b/docs/ko/results.md @@ -9,90 +9,90 @@ search: - `Runner.run(...)` 또는 `Runner.run_sync(...)`의 [`RunResult`][agents.result.RunResult] - `Runner.run_streamed(...)`의 [`RunResultStreaming`][agents.result.RunResultStreaming] -둘 다 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()` 같은 공통 결과 표면을 노출합니다. +둘 다 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()`와 같은 공통 결과 접근 지점을 제공합니다. -`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어를 추가합니다. +`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어 기능을 추가합니다. -## 적절한 결과 표면 선택 +## 적절한 결과 접근 지점 선택 대부분의 애플리케이션에는 몇 가지 결과 속성이나 헬퍼만 필요합니다. -| 필요한 경우... | 사용 | +| 필요한 항목 | 사용 | | --- | --- | | 사용자에게 보여줄 최종 답변 | `final_output` | -| 전체 로컬 transcript가 포함된, 재생 준비가 된 다음 턴 입력 목록 | `to_input_list()` | +| 전체 로컬 대화 기록이 포함된, 재생 가능한 다음 턴 입력 목록 | `to_input_list()` | | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 실행 항목 | `new_items` | | 일반적으로 다음 사용자 턴을 처리해야 하는 에이전트 | `last_agent` | | `previous_response_id`를 사용한 OpenAI Responses API 체이닝 | `last_response_id` | -| 대기 중인 승인과 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` | -| 현재 중첩된 `Agent.as_tool()` 호출에 대한 메타데이터 | `agent_tool_invocation` | +| 대기 중인 승인 및 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` | +| 현재 중첩 `Agent.as_tool()` 호출에 대한 메타데이터 | `agent_tool_invocation` | | 원문 모델 호출 또는 가드레일 진단 | `raw_responses` 및 가드레일 결과 배열 | ## 최종 출력 -[`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` 타입의 객체 - 예를 들어 승인 인터럽션(중단 처리)에서 일시 중지되어 최종 출력이 생성되기 전에 실행이 중단된 경우 `None` !!! note - `final_output`은 `Any`로 타입이 지정되어 있습니다. 핸드오프는 어떤 에이전트가 실행을 완료하는지 바꿀 수 있으므로, SDK는 가능한 전체 출력 타입 집합을 정적으로 알 수 없습니다. + `final_output`은 `Any` 타입으로 지정되어 있습니다. 핸드오프는 어떤 에이전트가 실행을 완료할지 바꿀 수 있으므로, SDK는 가능한 출력 타입의 전체 집합을 정적으로 알 수 없습니다. -스트리밍 모드에서는 스트림 처리가 완료될 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [스트리밍](streaming.md)을 참조하세요. +스트리밍 모드에서는 스트림 처리가 완료될 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [스트리밍](streaming.md)을 참고하세요. -## 입력, 다음 턴 히스토리, 새 항목 +## 입력, 다음 턴 기록 및 새 항목 -이 표면들은 서로 다른 질문에 답합니다. +이 접근 지점들은 서로 다른 질문에 답합니다. -| 속성 또는 헬퍼 | 포함 내용 | 최적의 용도 | +| 속성 또는 헬퍼 | 포함 내용 | 적합한 용도 | | --- | --- | --- | -| [`input`][agents.result.RunResultBase.input] | 이 실행 구간의 기본 입력입니다. 핸드오프 입력 필터가 히스토리를 다시 썼다면, 실행이 계속된 필터링된 입력을 반영합니다. | 이 실행이 실제로 입력으로 사용한 내용을 감사 | -| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 항목 뷰입니다. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 히스토리를 유지합니다. `mode="normalized"`는 핸드오프 필터링이 모델 히스토리를 다시 쓸 때 표준 계속 입력을 우선합니다. | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 항목 히스토리 검사 | +| [`input`][agents.result.RunResultBase.input] | 이 실행 구간의 기본 입력입니다. 핸드오프 입력 필터가 기록을 다시 작성한 경우, 실행이 이어서 사용한 필터링된 입력을 반영합니다. | 이 실행이 실제로 입력으로 사용한 내용 감사 | +| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 항목 뷰입니다. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 기록을 유지합니다. `mode="normalized"`는 핸드오프 필터링이 모델 기록을 다시 작성할 때 표준 이어가기 입력을 우선합니다. | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 항목 기록 검사 | | [`new_items`][agents.result.RunResultBase.new_items] | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 [`RunItem`][agents.items.RunItem] 래퍼입니다. | 로그, UI, 감사, 디버깅 | -| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행 중 각 모델 호출에서 나온 원문 [`ModelResponse`][agents.items.ModelResponse] 객체입니다. | 제공자 수준 진단 또는 원문 응답 검사 | +| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행의 각 모델 호출에서 나온 원문 [`ModelResponse`][agents.items.ModelResponse] 객체입니다. | 프로바이더 수준 진단 또는 원문 응답 검사 | -실제로는 다음과 같습니다. +실제로는 다음과 같이 사용합니다. -- 실행의 일반 입력 항목 뷰가 필요할 때는 `to_input_list()`를 사용하세요. -- 핸드오프 필터링 또는 중첩 핸드오프 히스토리 재작성 후 다음 `Runner.run(..., input=...)` 호출을 위한 표준 로컬 입력이 필요할 때는 `to_input_list(mode="normalized")`를 사용하세요. -- SDK가 히스토리를 로드하고 저장해 주기를 원할 때는 [`session=...`](sessions/index.md)을 사용하세요. -- `conversation_id` 또는 `previous_response_id`로 OpenAI 서버 관리 상태를 사용하는 경우, 일반적으로 `to_input_list()`를 다시 보내는 대신 새 사용자 입력만 전달하고 저장된 ID를 재사용하세요. -- 로그, UI, 감사에 사용할 전체 변환 히스토리가 필요할 때는 기본 `to_input_list()` 모드 또는 `new_items`를 사용하세요. +- 실행의 일반 입력 항목 뷰가 필요할 때는 `to_input_list()`를 사용합니다. +- 핸드오프 필터링 또는 중첩 핸드오프 기록 재작성 이후 다음 `Runner.run(..., input=...)` 호출에 사용할 표준 로컬 입력이 필요할 때는 `to_input_list(mode="normalized")`를 사용합니다. +- SDK가 기록을 로드하고 저장해 주기를 원할 때는 [`session=...`](sessions/index.md)을 사용합니다. +- `conversation_id` 또는 `previous_response_id`와 함께 OpenAI 서버 관리 상태를 사용하는 경우, 보통 `to_input_list()`를 다시 보내는 대신 새 사용자 입력만 전달하고 저장된 ID를 재사용합니다. +- 로그, UI, 감사에 사용할 변환된 전체 기록이 필요할 때는 기본 `to_input_list()` 모드 또는 `new_items`를 사용합니다. JavaScript SDK와 달리 Python은 모델 형태의 델타만을 위한 별도의 `output` 속성을 노출하지 않습니다. SDK 메타데이터가 필요할 때는 `new_items`를 사용하고, 원문 모델 페이로드가 필요할 때는 `raw_responses`를 검사하세요. -컴퓨터 도구 재생은 원문 Responses 페이로드 형태를 따릅니다. 프리뷰 모델 `computer_call` 항목은 단일 `action`을 보존하는 반면, `gpt-5.5` 컴퓨터 호출은 배치된 `actions[]`를 보존할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 transcript가 프리뷰 및 GA 컴퓨터 도구 호출 모두에서 계속 작동합니다. 로컬 실행 결과는 여전히 `new_items`에 `computer_call_output` 항목으로 표시됩니다. +컴퓨터 도구 재생은 원문 Responses 페이로드 형태를 따릅니다. 프리뷰 모델의 `computer_call` 항목은 단일 `action`을 보존하고, `gpt-5.5` 컴퓨터 호출은 배치된 `actions[]`를 보존할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 대화 기록이 프리뷰 및 GA 컴퓨터 도구 호출 모두에서 계속 작동합니다. 로컬 실행 결과는 여전히 `new_items`의 `computer_call_output` 항목으로 나타납니다. ### 새 항목 -[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 일어난 일을 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다. +[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 발생한 일을 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다. - 어시스턴트 메시지용 [`MessageOutputItem`][agents.items.MessageOutputItem] - 추론 항목용 [`ReasoningItem`][agents.items.ReasoningItem] - Responses 도구 검색 요청 및 로드된 도구 검색 결과용 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 및 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem] - 도구 호출 및 그 결과용 [`ToolCallItem`][agents.items.ToolCallItem] 및 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] -- 승인 대기 중 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem] -- 핸드오프 요청 및 완료된 전환용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem] +- 승인을 위해 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem] +- 핸드오프 요청 및 완료된 전달용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem] -에이전트 연결, 도구 출력, 핸드오프 경계 또는 승인 경계가 필요할 때마다 `to_input_list()` 대신 `new_items`를 선택하세요. +에이전트 연결, 도구 출력, 핸드오프 경계 또는 승인 경계가 필요할 때는 항상 `to_input_list()`보다 `new_items`를 선택하세요. -호스티드 툴 검색을 사용할 때는 모델이 내보낸 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을 검사하고, 해당 턴에 로드된 네임스페이스, 함수 또는 호스티드 MCP 서버를 보려면 `ToolSearchOutputItem.raw_item`을 검사하세요. +호스티드 툴 검색을 사용할 때는 모델이 내보낸 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을 검사하고, 해당 턴에 어떤 네임스페이스, 함수 또는 호스티드 MCP 서버가 로드되었는지 보려면 `ToolSearchOutputItem.raw_item`을 검사하세요. ## 대화 계속 또는 재개 ### 다음 턴 에이전트 -[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 들어 있습니다. 이는 핸드오프 후 다음 사용자 턴에 재사용하기 가장 좋은 에이전트인 경우가 많습니다. +[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 포함됩니다. 이는 핸드오프 후 다음 사용자 턴에 재사용하기 가장 좋은 에이전트인 경우가 많습니다. -스트리밍 모드에서는 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 실행 진행에 따라 업데이트되므로, 스트림이 끝나기 전에 핸드오프를 관찰할 수 있습니다. +스트리밍 모드에서는 실행이 진행됨에 따라 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 업데이트되므로, 스트림이 끝나기 전에 핸드오프를 관찰할 수 있습니다. ### 인터럽션(중단 처리) 및 실행 상태 -도구에 승인이 필요한 경우, 대기 중인 승인은 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구, 핸드오프 후 도달한 도구 또는 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다. +도구에 승인이 필요한 경우, 대기 중인 승인은 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구, 핸드오프 후 도달한 도구 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다. -[`to_state()`][agents.result.RunResult.to_state]를 호출해 재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하고, 대기 중인 항목을 승인하거나 거부한 다음 `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요. +[`to_state()`][agents.result.RunResult.to_state]를 호출하여 재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하고, 대기 중인 항목을 승인하거나 거부한 다음 `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요. ```python from agents import Agent, Runner @@ -107,48 +107,48 @@ if result.interruptions: result = await Runner.run(agent, state) ``` -스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음 `result.interruptions`를 검사하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md)를 참조하세요. +스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음, `result.interruptions`를 검사하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md)를 참고하세요. -### 서버 관리 계속 +### 서버 관리 지속 -[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행의 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 계속하려면 다음 턴에서 `previous_response_id`로 다시 전달하세요. +[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행에서 나온 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 계속하려면 다음 턴에 이를 `previous_response_id`로 다시 전달하세요. -이미 `to_input_list()`, `session` 또는 `conversation_id`로 대화를 계속하고 있다면 일반적으로 `last_response_id`가 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하다면 대신 `raw_responses`를 검사하세요. +이미 `to_input_list()`, `session` 또는 `conversation_id`로 대화를 계속하고 있다면 보통 `last_response_id`가 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하면 대신 `raw_responses`를 검사하세요. ## Agent-as-tool 메타데이터 -결과가 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 외부 도구 호출에 대한 불변 메타데이터를 노출합니다. +결과가 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 나온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 외부 도구 호출에 대한 불변 메타데이터를 노출합니다. - `tool_name` - `tool_call_id` - `tool_arguments` -일반적인 최상위 실행의 경우 `agent_tool_invocation`은 `None`입니다. +일반적인 최상위 실행에서는 `agent_tool_invocation`이 `None`입니다. -이는 중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 수 있는 `custom_output_extractor` 내부에서 특히 유용합니다. 관련 `Agent.as_tool()` 패턴은 [도구](tools.md)를 참조하세요. +이는 특히 `custom_output_extractor` 내부에서 유용합니다. 중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 수 있기 때문입니다. 관련 `Agent.as_tool()` 패턴은 [도구](tools.md)를 참고하세요. -해당 중첩 실행의 파싱된 structured input도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 [`RunState`][agents.run_state.RunState]가 중첩 도구 입력을 일반적으로 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출에 대한 실시간 결과 접근자입니다. +해당 중첩 실행의 파싱된 구조화 입력도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 [`RunState`][agents.run_state.RunState]가 중첩 도구 입력을 위해 일반화하여 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출에 대한 라이브 결과 접근자입니다. ## 스트리밍 수명 주기 및 진단 -[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 표면을 상속하지만, 스트리밍 전용 제어를 추가합니다. +[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 접근 지점을 상속하지만, 스트리밍 전용 제어 기능을 추가합니다. -- 의미론적 스트림 이벤트를 소비하기 위한 [`stream_events()`][agents.result.RunResultStreaming.stream_events] -- 실행 중 활성 에이전트를 추적하기 위한 [`current_agent`][agents.result.RunResultStreaming.current_agent] -- 스트리밍된 실행이 완전히 완료되었는지 확인하기 위한 [`is_complete`][agents.result.RunResultStreaming.is_complete] -- 실행을 즉시 또는 현재 턴 이후 중지하기 위한 [`cancel(...)`][agents.result.RunResultStreaming.cancel] +- 의미론적 스트림 이벤트를 소비하는 [`stream_events()`][agents.result.RunResultStreaming.stream_events] +- 실행 중 활성 에이전트를 추적하는 [`current_agent`][agents.result.RunResultStreaming.current_agent] +- 스트리밍 실행이 완전히 끝났는지 확인하는 [`is_complete`][agents.result.RunResultStreaming.is_complete] +- 실행을 즉시 또는 현재 턴 이후에 중지하는 [`cancel(...)`][agents.result.RunResultStreaming.cancel] -비동기 이터레이터가 끝날 때까지 `stream_events()` 소비를 계속하세요. 스트리밍 실행은 해당 이터레이터가 종료되기 전까지 완료되지 않으며, `final_output`, `interruptions`, `raw_responses` 같은 요약 속성과 세션 지속성 부작용은 마지막으로 보이는 토큰이 도착한 후에도 아직 정리 중일 수 있습니다. +비동기 이터레이터가 끝날 때까지 `stream_events()`를 계속 소비하세요. 해당 이터레이터가 종료되기 전까지 스트리밍 실행은 완료된 것이 아니며, `final_output`, `interruptions`, `raw_responses` 같은 요약 속성과 세션 영속화 부수 효과는 마지막으로 보이는 토큰이 도착한 뒤에도 아직 확정되는 중일 수 있습니다. -`cancel()`을 호출했다면 취소와 정리가 올바르게 완료될 수 있도록 `stream_events()` 소비를 계속하세요. +`cancel()`을 호출한 경우에도 취소와 정리가 올바르게 완료될 수 있도록 `stream_events()`를 계속 소비하세요. -Python은 별도의 스트리밍된 `completed` promise나 `error` 속성을 노출하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외를 발생시키는 방식으로 표시되며, `is_complete`는 실행이 최종 상태에 도달했는지 여부를 반영합니다. +Python은 별도의 스트리밍 `completed` 프라미스나 `error` 속성을 노출하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외가 발생하는 방식으로 표면화되며, `is_complete`는 실행이 종료 상태에 도달했는지 여부를 반영합니다. ### 원문 응답 -[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원문 모델 응답이 들어 있습니다. 다단계 실행은 예를 들어 핸드오프 또는 반복되는 모델/도구/모델 사이클 전반에서 둘 이상의 응답을 생성할 수 있습니다. +[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원문 모델 응답이 포함됩니다. 다단계 실행은 예를 들어 핸드오프 또는 반복되는 모델/도구/모델 사이클을 거치며 둘 이상의 응답을 생성할 수 있습니다. -[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목에서 나온 ID일 뿐입니다. +[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목에서 가져온 ID일 뿐입니다. ### 가드레일 결과 @@ -156,10 +156,10 @@ Python은 별도의 스트리밍된 `completed` promise나 `error` 속성을 노 도구 가드레일은 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 및 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results]로 별도로 노출됩니다. -이 배열들은 실행 전반에 걸쳐 누적되므로, 의사결정 로깅, 추가 가드레일 메타데이터 저장 또는 실행이 차단된 이유 디버깅에 유용합니다. +이 배열들은 실행 전반에 걸쳐 누적되므로, 결정 사항을 기록하거나 추가 가드레일 메타데이터를 저장하거나 실행이 차단된 이유를 디버깅하는 데 유용합니다. ### 컨텍스트 및 사용량 [`context_wrapper`][agents.result.RunResultBase.context_wrapper]는 승인, 사용량, 중첩 `tool_input` 같은 SDK 관리 런타임 메타데이터와 함께 앱 컨텍스트를 노출합니다. -사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행의 경우 사용량 합계는 스트림의 마지막 청크가 처리될 때까지 지연될 수 있습니다. 전체 래퍼 형태와 지속성 관련 주의사항은 [컨텍스트 관리](context.md)를 참조하세요. \ No newline at end of file +사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행의 경우 스트림의 최종 청크가 처리될 때까지 사용량 합계가 지연될 수 있습니다. 전체 래퍼 형태와 지속성 관련 주의 사항은 [컨텍스트 관리](context.md)를 참고하세요. \ No newline at end of file diff --git a/docs/ko/running_agents.md b/docs/ko/running_agents.md index ad2ec20a97..6985a36f8d 100644 --- a/docs/ko/running_agents.md +++ b/docs/ko/running_agents.md @@ -4,11 +4,11 @@ search: --- # 에이전트 실행 -[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 3가지 옵션이 있습니다. +[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 세 가지 옵션이 있습니다. 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,46 +23,46 @@ async def main(): # Infinite loop's dance ``` -자세한 내용은 [결과 가이드](results.md)를 읽어보세요. +자세한 내용은 [결과 가이드](results.md)를 참조하세요. -## Runner 수명 주기 및 구성 +## Runner 수명 주기와 구성 ### 에이전트 루프 -`Runner`의 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다. +`Runner`에서 run 메서드를 사용할 때 시작 에이전트와 입력을 전달합니다. 입력은 다음 중 하나일 수 있습니다. - 문자열(사용자 메시지로 처리됨) - OpenAI Responses API 형식의 입력 항목 목록 - 중단된 실행을 재개할 때의 [`RunState`][agents.run_state.RunState] -그러면 runner가 루프를 실행합니다. +그런 다음 runner는 루프를 실행합니다. 1. 현재 입력으로 현재 에이전트에 대해 LLM을 호출합니다. 2. LLM이 출력을 생성합니다. 1. LLM이 `final_output`을 반환하면 루프가 종료되고 결과를 반환합니다. 2. LLM이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 다시 실행합니다. - 3. LLM이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프를 다시 실행합니다. + 3. LLM이 도구 호출을 생성하면 해당 도구 호출을 실행하고, 결과를 추가한 뒤 루프를 다시 실행합니다. 3. 전달된 `max_turns`를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생시킵니다. 이 턴 제한을 비활성화하려면 `max_turns=None`을 전달하세요. !!! note - LLM 출력이 "최종 출력"으로 간주되는 규칙은, 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없는 경우입니다. + LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없는 경우입니다. ### 스트리밍 -스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에는 생성된 모든 새 출력을 포함해 실행에 대한 전체 정보가 포함됩니다. 스트리밍 이벤트는 `.stream_events()`를 호출해 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 읽어보세요. +스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트도 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에 생성된 모든 새 출력을 포함하여 실행에 대한 전체 정보가 포함됩니다. 스트리밍 이벤트를 받으려면 `.stream_events()`를 호출할 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참조하세요. #### Responses WebSocket 전송(선택적 헬퍼) -OpenAI Responses websocket 전송을 활성화하면 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼가 권장되지만 필수는 아닙니다. +OpenAI Responses websocket 전송을 활성화해도 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼 사용을 권장하지만 필수는 아닙니다. 이는 websocket 전송을 통한 Responses API이며, [Realtime API](realtime/guide.md)가 아닙니다. -전송 선택 규칙과 구체적인 모델 객체 또는 사용자 지정 제공자 관련 주의 사항은 [모델](models/index.md#responses-websocket-transport)을 참조하세요. +구체적인 모델 객체 또는 사용자 지정 provider와 관련된 전송 선택 규칙 및 주의 사항은 [모델](models/index.md#responses-websocket-transport)을 참조하세요. -##### 패턴 1: 세션 헬퍼 없음(동작함) +##### 패턴 1: 세션 헬퍼 없음(작동) -websocket 전송만 원하고 SDK가 공유 제공자/세션을 관리할 필요가 없을 때 사용하세요. +websocket 전송만 필요하고 SDK가 공유 provider/session을 관리할 필요가 없을 때 사용하세요. ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -이 패턴은 단일 실행에는 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복해서 호출하면 동일한 `RunConfig` / 제공자 인스턴스를 수동으로 재사용하지 않는 한 각 실행이 다시 연결될 수 있습니다. +이 패턴은 단일 실행에는 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복 호출하면 동일한 `RunConfig` / provider 인스턴스를 수동으로 재사용하지 않는 한 각 실행에서 다시 연결할 수 있습니다. -##### 패턴 2: `responses_websocket_session()` 사용(다중 턴 재사용에 권장) +##### 패턴 2: `responses_websocket_session()` 사용(멀티턴 재사용 권장) -여러 실행에서(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함) 공유 websocket 지원 제공자와 `RunConfig`를 사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요. +여러 실행(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함)에서 공유 websocket 지원 provider와 `RunConfig`를 원할 때 [`responses_websocket_session()`][agents.responses_websocket_session]를 사용하세요. ```python import asyncio @@ -119,55 +119,55 @@ async def main(): asyncio.run(main()) ``` -컨텍스트가 종료되기 전에 스트리밍 결과 소비를 마치세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다. +컨텍스트가 종료되기 전에 스트리밍된 결과 소비를 완료하세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다. -긴 추론 턴에서 websocket keepalive 타임아웃이 발생하면 `ping_timeout`을 늘리거나 `ping_timeout=None`으로 설정해 heartbeat 타임아웃을 비활성화하세요. 신뢰성이 websocket 지연 시간보다 중요한 실행에는 HTTP/SSE 전송을 사용하세요. +긴 reasoning 턴에서 websocket keepalive timeout이 발생하면 `ping_timeout`을 늘리거나 `ping_timeout=None`으로 설정해 heartbeat timeout을 비활성화하세요. websocket 지연 시간보다 안정성이 더 중요한 실행에는 HTTP/SSE 전송을 사용하세요. -### Run config +### 실행 구성 `run_config` 매개변수를 사용하면 에이전트 실행에 대한 일부 전역 설정을 구성할 수 있습니다. -#### 일반적인 run config 카테고리 +#### 일반 실행 구성 카테고리 각 에이전트 정의를 변경하지 않고 단일 실행의 동작을 재정의하려면 `RunConfig`를 사용하세요. -##### 모델, 제공자 및 세션 기본값 +##### 모델, provider, 세션 기본값 -- [`model`][agents.run.RunConfig.model]: 각 Agent가 가진 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다. -- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름 조회에 사용할 모델 제공자이며 기본값은 OpenAI입니다. +- [`model`][agents.run.RunConfig.model]: 각 에이전트가 가진 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다. +- [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름을 조회하기 위한 모델 provider이며, 기본값은 OpenAI입니다. - [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예를 들어 전역 `temperature` 또는 `top_p`를 설정할 수 있습니다. - [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 기록을 가져올 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다. - [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions를 사용할 때 각 턴 전에 새 사용자 입력이 세션 기록과 병합되는 방식을 사용자 지정합니다. 콜백은 동기 또는 비동기일 수 있습니다. -##### 가드레일, 핸드오프 및 모델 입력 형성 +##### 가드레일, 핸드오프, 모델 입력 구성 - [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록입니다. -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참조하세요. -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 대화 기록을 단일 assistant 메시지로 축약하는 옵트인 베타입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하고, 원문 대화 기록을 그대로 전달하려면 `False`로 둡니다. 모든 [Runner 메서드][agents.run.Runner]는 전달된 `RunConfig`가 없을 때 자동으로 `RunConfig`를 생성하므로, 빠른 시작과 예제는 기본적으로 꺼진 상태를 유지하며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다. -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`에 옵트인할 때마다 정규화된 대화 기록(기록 + 핸드오프 항목)을 받는 선택적 callable입니다. 다음 에이전트로 전달할 정확한 입력 항목 목록을 반환해야 하며, 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다. -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 훅입니다. 예를 들어 기록을 줄이거나 시스템 프롬프트를 삽입할 수 있습니다. -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 보존할지 생략할지 제어합니다. +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 아직 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter]의 문서를 참조하세요. +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 transcript를 단일 assistant 메시지로 축소하는 선택형 베타 기능입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하고, 원문 transcript를 그대로 전달하려면 `False`로 둡니다. 모든 [Runner 메서드][agents.run.Runner]는 전달된 값이 없을 때 자동으로 `RunConfig`를 생성하므로 quickstart와 예제에서는 기본값이 꺼진 상태로 유지되며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다. +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 선택했을 때마다 정규화된 transcript(기록 + 핸드오프 항목)를 받는 선택적 callable입니다. 다음 에이전트로 전달할 입력 항목의 정확한 목록을 반환해야 하며, 이를 통해 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다. +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 후크입니다. 예를 들어 기록을 줄이거나 시스템 프롬프트를 주입할 수 있습니다. +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 보존할지 생략할지를 제어합니다. -##### 트레이싱 및 관측 가능성 +##### 트레이싱과 관찰 가능성 - [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md)을 비활성화할 수 있습니다. - [`tracing`][agents.run.RunConfig.tracing]: 실행별 트레이싱 API 키와 같은 trace 내보내기 설정을 재정의하려면 [`TracingConfig`][agents.tracing.TracingConfig]를 전달합니다. - [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace에 LLM 및 도구 호출 입력/출력과 같이 잠재적으로 민감한 데이터를 포함할지 여부를 구성합니다. -- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID 및 trace 그룹 ID를 설정합니다. 최소한 `workflow_name`은 설정하는 것을 권장합니다. 그룹 ID는 여러 실행 간 trace를 연결할 수 있는 선택적 필드입니다. +- [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID 및 trace group ID를 설정합니다. 최소한 `workflow_name`은 설정하는 것을 권장합니다. group ID는 여러 실행 간 trace를 연결할 수 있게 해주는 선택적 필드입니다. - [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 trace에 포함할 메타데이터입니다. -##### 도구 실행, 승인 및 도구 오류 동작 +##### 도구 실행, 승인, 도구 오류 동작 -- [`tool_execution`][agents.run.RunConfig.tool_execution]: 한 번에 실행되는 함수 도구 수 제한과 같이 로컬 도구 호출에 대한 SDK 측 실행 동작을 구성합니다. -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 흐름 중 도구 호출이 거부될 때 모델에 표시되는 메시지를 사용자 지정합니다. +- [`tool_execution`][agents.run.RunConfig.tool_execution]: 한 번에 실행되는 함수 도구 수 제한 등 로컬 도구 호출에 대한 SDK 측 실행 동작을 구성합니다. +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 플로 중 도구 호출이 거부되었을 때 모델에 표시되는 메시지를 사용자 지정합니다. -중첩 핸드오프는 옵트인 베타로 제공됩니다. 축약된 대화 기록 동작을 활성화하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 대화 기록을 유지하려는 경우(기본값), 플래그를 설정하지 않거나 필요한 방식 그대로 대화를 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값으로 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]). +중첩 핸드오프는 선택형 베타로 제공됩니다. 축소된 transcript 동작을 활성화하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 켜려면 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 transcript를 유지하려는 경우(기본값), 플래그를 설정하지 않거나 필요한 방식으로 대화를 정확히 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에 사용되는 wrapper 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값을 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 호출). -#### Run config 세부 정보 +#### 실행 구성 세부 정보 ##### `tool_execution` -실행에 대해 SDK가 로컬 함수 도구 동시성을 제한하도록 하려면 `tool_execution`을 사용하세요. +SDK가 실행에 대해 로컬 함수 도구 동시성을 제한하도록 하려면 `tool_execution`을 사용하세요. ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,22 +183,22 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None`은 기본 동작을 유지합니다. 모델이 한 턴에 여러 함수 도구 호출을 내보내면 SDK는 내보낸 모든 로컬 함수 도구 호출을 시작합니다. 동시에 실행되는 로컬 함수 도구 수를 제한하려면 정수 값을 설정하세요. +`max_function_tool_concurrency=None`은 기본 동작을 유지합니다. 모델이 한 턴에서 여러 함수 도구 호출을 내보내면 SDK는 내보낸 모든 로컬 함수 도구 호출을 시작합니다. 정수 값을 설정하면 동시에 실행되는 로컬 함수 도구 수를 제한할 수 있습니다. -이는 제공자 측 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]와 별개입니다. `parallel_tool_calls`는 모델이 단일 응답에서 여러 도구 호출을 내보낼 수 있는지 여부를 제어합니다. `tool_execution.max_function_tool_concurrency`는 모델이 도구 호출을 내보낸 후 SDK가 로컬 함수 도구 호출을 실행하는 방식을 제어합니다. +이는 provider 측 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]와 별개입니다. `parallel_tool_calls`는 모델이 단일 응답에서 여러 도구 호출을 내보낼 수 있는지 제어합니다. `tool_execution.max_function_tool_concurrency`는 모델이 도구 호출을 내보낸 후 SDK가 로컬 함수 도구 호출을 실행하는 방식을 제어합니다. ##### `tool_error_formatter` -승인 흐름에서 도구 호출이 거부될 때 모델에 반환되는 메시지를 사용자 지정하려면 `tool_error_formatter`를 사용하세요. +승인 플로에서 도구 호출이 거부되었을 때 모델에 반환되는 메시지를 사용자 지정하려면 `tool_error_formatter`를 사용하세요. formatter는 다음을 포함하는 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]를 받습니다. -- `kind`: 오류 카테고리입니다. 현재 이는 `"approval_rejected"`입니다. -- `tool_type`: 도구 런타임입니다(`"function"`, `"computer"`, `"shell"`, `"apply_patch"` 또는 `"custom"`). +- `kind`: 오류 카테고리입니다. 현재는 `"approval_rejected"`입니다. +- `tool_type`: 도구 런타임(`"function"`, `"computer"`, `"shell"`, `"apply_patch"` 또는 `"custom"`)입니다. - `tool_name`: 도구 이름입니다. - `call_id`: 도구 호출 ID입니다. - `default_message`: SDK의 기본 모델 표시 메시지입니다. -- `run_context`: 활성 실행 컨텍스트 래퍼입니다. +- `run_context`: 활성 실행 컨텍스트 wrapper입니다. 메시지를 대체하려면 문자열을 반환하고, SDK 기본값을 사용하려면 `None`을 반환하세요. @@ -225,56 +225,56 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy`는 runner가 기록을 다음으로 전달할 때(예: `RunResult.to_input_list()` 또는 세션 기반 실행 사용 시) reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다. +`reasoning_item_id_policy`는 runner가 기록을 앞으로 전달할 때(예: `RunResult.to_input_list()` 또는 세션 기반 실행을 사용할 때) reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다. - `None` 또는 `"preserve"`(기본값): reasoning 항목 ID를 유지합니다. - `"omit"`: 생성된 다음 턴 입력에서 reasoning 항목 ID를 제거합니다. -`"omit"`는 주로 reasoning 항목이 `id`와 함께 전송되었지만 필수 후속 항목이 없는 경우 발생하는 Responses API 400 오류 범주에 대한 옵트인 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`). +`"omit"`은 주로 reasoning 항목이 `id`와 함께 전송되지만 필수 후속 항목 없이 전송되는 경우 발생하는 Responses API 400 오류 계열에 대한 선택적 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`). -이는 SDK가 이전 출력에서 후속 입력을 구성하는 다중 턴 에이전트 실행에서 발생할 수 있습니다(세션 지속성, 서버 관리 대화 델타, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함). 이때 reasoning 항목 ID는 보존되지만 제공자는 해당 ID가 대응되는 후속 항목과 계속 짝을 이루도록 요구합니다. +이는 SDK가 이전 출력에서 후속 입력을 구성할 때(세션 영속성, 서버 관리 대화 delta, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함) reasoning 항목 ID가 보존되지만 provider가 해당 ID가 대응하는 후속 항목과 계속 쌍을 이루도록 요구하는 멀티턴 에이전트 실행에서 발생할 수 있습니다. -`reasoning_item_id_policy="omit"`를 설정하면 reasoning 내용은 유지하되 reasoning 항목 `id`를 제거하여, SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 방지합니다. +`reasoning_item_id_policy="omit"`을 설정하면 reasoning 콘텐츠는 유지하되 reasoning 항목 `id`를 제거하여 SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 방지합니다. -범위 참고 사항: +범위 참고: - 이는 SDK가 후속 입력을 빌드할 때 생성/전달하는 reasoning 항목만 변경합니다. - 사용자가 제공한 초기 입력 항목은 다시 작성하지 않습니다. - `call_model_input_filter`는 이 정책이 적용된 후에도 의도적으로 reasoning ID를 다시 도입할 수 있습니다. -## 상태 및 대화 관리 +## 상태와 대화 관리 ### 메모리 전략 선택 -다음 턴으로 상태를 전달하는 일반적인 방법은 네 가지입니다. +상태를 다음 턴으로 전달하는 일반적인 방법은 네 가지입니다. -| 전략 | 상태가 있는 위치 | 적합한 용도 | 다음 턴에 전달하는 내용 | +| 전략 | 상태가 위치하는 곳 | 적합한 경우 | 다음 턴에 전달하는 것 | | --- | --- | --- | --- | -| `result.to_input_list()` | 앱 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 제공자 | `result.to_input_list()`의 목록과 다음 사용자 메시지 | -| `session` | 사용자의 스토리지와 SDK | 지속형 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 | -| `conversation_id` | OpenAI Conversations API | 작업자나 서비스 간 공유하려는 명명된 서버 측 대화 | 동일한 `conversation_id`와 새 사용자 턴만 | -| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 경량 서버 관리형 이어가기 | `result.last_response_id`와 새 사용자 턴만 | +| `result.to_input_list()` | 앱 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 provider | `result.to_input_list()`의 목록과 다음 사용자 메시지 | +| `session` | 사용자의 저장소와 SDK | 영속적인 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 | +| `conversation_id` | OpenAI Conversations API | 작업자나 서비스 간에 공유하려는 이름 있는 서버 측 대화 | 동일한 `conversation_id`와 새 사용자 턴만 | +| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 경량 서버 관리 연속 처리 | `result.last_response_id`와 새 사용자 턴만 | -`result.to_input_list()`와 `session`은 클라이언트 관리형입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리형이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화당 하나의 지속성 전략을 선택하세요. 두 계층을 의도적으로 조정하지 않는 한 클라이언트 관리 기록과 OpenAI 관리 상태를 혼합하면 컨텍스트가 중복될 수 있습니다. +`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화마다 하나의 영속성 전략을 선택하세요. 두 계층을 의도적으로 조정하지 않는 한 클라이언트 관리 기록과 OpenAI 관리 상태를 섞으면 컨텍스트가 중복될 수 있습니다. !!! note - 세션 지속성은 동일한 실행에서 서버 관리 대화 설정 - (`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`)과 함께 사용할 수 없습니다. - 호출마다 하나의 접근 방식을 선택하세요. + 세션 영속성은 동일한 실행에서 서버 관리 대화 설정 + (`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`)과 + 결합할 수 없습니다. 호출마다 하나의 접근 방식을 선택하세요. ### 대화/채팅 스레드 -run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출이 발생할 수 있음), 이는 채팅 대화에서 하나의 논리적 턴을 나타냅니다. 예를 들면 다음과 같습니다. +run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있으므로 하나 이상의 LLM 호출이 발생할 수 있지만, 이는 채팅 대화의 단일 논리 턴을 나타냅니다. 예를 들어: 1. 사용자 턴: 사용자가 텍스트 입력 -2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고 도구를 실행하며 두 번째 에이전트로 핸드오프하고, 두 번째 에이전트가 더 많은 도구를 실행한 뒤 출력을 생성합니다. +2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고, 도구를 실행하고, 두 번째 에이전트로 핸드오프하며, 두 번째 에이전트가 더 많은 도구를 실행한 다음 출력을 생성합니다. -에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 사용자에게 보여줄 수도 있고, 최종 출력만 보여줄 수도 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 이 경우 run 메서드를 다시 호출할 수 있습니다. +에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 사용자에게 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 이 경우 run 메서드를 다시 호출할 수 있습니다. #### 수동 대화 관리 -다음 턴의 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용하여 대화 기록을 수동으로 관리할 수 있습니다. +다음 턴의 입력을 가져오려면 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용해 대화 기록을 수동으로 관리할 수 있습니다. ```python async def main(): @@ -294,9 +294,9 @@ async def main(): # California ``` -#### 세션을 사용한 자동 대화 관리 +#### 세션을 통한 자동 대화 관리 -더 간단한 접근 방식으로, `.to_input_list()`를 수동으로 호출하지 않고도 대화 기록을 자동으로 처리하기 위해 [Sessions](sessions/index.md)를 사용할 수 있습니다. +더 간단한 접근 방식으로 [Sessions](sessions/index.md)를 사용하면 `.to_input_list()`를 수동으로 호출하지 않고도 대화 기록을 자동으로 처리할 수 있습니다. ```python from agents import Agent, Runner, SQLiteSession @@ -322,16 +322,16 @@ async def main(): Sessions는 자동으로 다음을 수행합니다. -- 각 실행 전에 대화 기록을 가져옵니다. -- 각 실행 후 새 메시지를 저장합니다. -- 서로 다른 세션 ID에 대해 별도의 대화를 유지합니다. +- 각 실행 전에 대화 기록 가져오기 +- 각 실행 후 새 메시지 저장 +- 서로 다른 세션 ID에 대해 별도의 대화 유지 자세한 내용은 [Sessions 문서](sessions/index.md)를 참조하세요. #### 서버 관리 대화 -`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신, OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이를 통해 과거 메시지를 모두 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 아래 서버 관리 접근 방식 중 어느 것이든 각 요청에는 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI Conversation 상태 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. +`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신 OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이를 통해 모든 과거 메시지를 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 아래의 서버 관리 접근 방식 중 어느 것을 사용하든 각 요청에는 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI 대화 상태 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요. OpenAI는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다. @@ -360,7 +360,7 @@ async def main(): ##### 2. `previous_response_id` 사용 -또 다른 옵션은 **응답 체이닝**으로, 각 턴이 이전 턴의 응답 ID에 명시적으로 연결됩니다. +또 다른 옵션은 각 턴이 이전 턴의 응답 ID에 명시적으로 연결되는 **응답 체이닝**입니다. ```python from agents import Agent, Runner @@ -389,28 +389,29 @@ async def main(): SDK는 저장된 `conversation_id` / `previous_response_id` / `auto_previous_response_id` 설정을 유지하므로 재개된 턴은 동일한 서버 관리 대화에서 계속됩니다. -`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 여러 시스템 간 공유할 수 있는 명명된 대화 리소스를 원하면 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API 이어가기 기본 구성 요소를 원하면 `previous_response_id`를 사용하세요. +`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간에 공유할 수 있는 이름 있는 대화 리소스를 원하면 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API 연속 처리 기본 구성 요소를 원하면 `previous_response_id`를 사용하세요. !!! note - SDK는 `conversation_locked` 오류를 backoff로 자동 재시도합니다. 서버 관리 - 대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 - 동일하게 준비된 항목을 깔끔하게 다시 전송할 수 있도록 합니다. + SDK는 `conversation_locked` 오류를 backoff와 함께 자동으로 재시도합니다. 서버 관리 + 대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 동일한 준비된 항목을 + 깔끔하게 다시 전송할 수 있게 합니다. 로컬 세션 기반 실행(`conversation_id`, - `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용할 수 없음)에서도 SDK는 재시도 후 중복 기록 항목을 줄이기 위해 최근 지속된 입력 항목을 최선의 노력으로 + `previous_response_id` 또는 `auto_previous_response_id`와 결합할 수 없음)에서도 SDK는 재시도 후 + 중복 기록 항목을 줄이기 위해 최근 영속화된 입력 항목을 best-effort 방식으로 롤백합니다. 이 호환성 재시도는 `ModelSettings.retry`를 구성하지 않아도 발생합니다. 모델 요청에 대한 - 더 폭넓은 옵트인 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참조하세요. + 더 넓은 선택형 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참조하세요. -## 훅 및 사용자 지정 +## 후크와 사용자 지정 -### 모델 입력 필터 호출 +### 모델 호출 입력 필터 -모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새로운 `ModelInputData`를 반환합니다. +모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 후크는 현재 에이전트, 컨텍스트 및 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새 `ModelInputData`를 반환합니다. -반환 값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다. +반환값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다. ```python from agents import Agent, Runner, RunConfig @@ -429,19 +430,19 @@ result = Runner.run_sync( ) ``` -runner는 준비된 입력 목록의 복사본을 훅에 전달하므로 호출자의 원본 목록을 제자리에서 변경하지 않고도 이를 줄이거나, 교체하거나, 재정렬할 수 있습니다. +runner는 준비된 입력 목록의 복사본을 후크에 전달하므로 호출자의 원래 목록을 제자리에서 변경하지 않고도 줄이거나, 대체하거나, 순서를 바꿀 수 있습니다. -세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후에 실행됩니다. 해당 이전 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. +세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후에 실행됩니다. 더 이른 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. -`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 OpenAI 서버 관리 대화 상태를 사용하는 경우, 훅은 다음 Responses API 호출을 위해 준비된 페이로드에서 실행됩니다. 해당 페이로드는 이전 기록 전체를 재생한 것이 아니라 이미 새 턴 델타만 나타낼 수 있습니다. 반환하는 항목만 해당 서버 관리 이어가기에서 전송된 것으로 표시됩니다. +`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 OpenAI 서버 관리 대화 상태를 사용하는 경우, 후크는 다음 Responses API 호출을 위해 준비된 payload에서 실행됩니다. 해당 payload는 이전 기록의 전체 replay가 아니라 새 턴 delta만 이미 나타낼 수 있습니다. 반환한 항목만 해당 서버 관리 연속 처리에 전송된 것으로 표시됩니다. -민감한 데이터를 수정하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 삽입하려면 실행별로 `run_config`를 통해 훅을 설정하세요. +민감한 데이터를 redact하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 주입하려면 `run_config`를 통해 실행별로 후크를 설정하세요. -## 오류 및 복구 +## 오류와 복구 -### 오류 핸들러 +### 오류 처리기 -모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 받습니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요. +모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 허용합니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요. ```python from agents import ( @@ -470,7 +471,7 @@ result = Runner.run_sync( print(result.final_output) ``` -대체 출력이 대화 기록에 추가되지 않도록 하려면 `include_in_history=False`를 설정하세요. +대체 출력이 대화 기록에 추가되는 것을 원하지 않으면 `include_in_history=False`를 설정하세요. 모델 거부가 `ModelRefusalError`로 실행을 종료하는 대신 애플리케이션별 대체 출력을 생성해야 하는 경우 `"model_refusal"`을 사용하세요. @@ -504,37 +505,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## 내구성 있는 실행 통합 및 휴먼인더루프 +## 내구성 있는 실행 통합과 휴먼인더루프 (HITL) -도구 승인 일시 중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)부터 시작하세요. -아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸칠 수 있는 내구성 있는 오케스트레이션을 위한 것입니다. +도구 승인 일시 중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)에서 시작하세요. +아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸쳐 이어질 수 있는 경우의 내구성 있는 오케스트레이션을 위한 것입니다. ### Dapr -Agents SDK [Dapr](https://dapr.io) Diagrid 통합을 사용하면 휴먼인더루프 지원으로 장애에서 자동 복구되는 내구성 있고 장기 실행되는 에이전트를 실행할 수 있습니다. Dapr은 벤더 중립적인 [CNCF](https://cncf.io) 워크플로 오케스트레이터입니다. Dapr 및 OpenAI 에이전트를 [여기](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)에서 시작하세요. +Agents SDK [Dapr](https://dapr.io) Diagrid 통합을 사용하면 휴먼인더루프 지원으로 장애에서 자동 복구되는 내구성 있고 장시간 실행되는 에이전트를 실행할 수 있습니다. Dapr는 벤더 중립적인 [CNCF](https://cncf.io) 워크플로 오케스트레이터입니다. Dapr와 OpenAI 에이전트 시작하기는 [여기](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)에서 확인하세요. ### Temporal -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)에서 확인하세요. ### Restate -Agents SDK [Restate](https://restate.dev/) 통합을 사용하면 사람 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 있는 에이전트를 사용할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 종속성으로 필요로 하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다. -자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)를 읽거나 [문서](https://docs.restate.dev/ai)를 확인하세요. +Agents SDK [Restate](https://restate.dev/) 통합을 사용하면 사람 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 있는 에이전트를 실행할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 의존성으로 필요로 하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다. +자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)를 읽거나 [문서](https://docs.restate.dev/ai)를 참조하세요. ### DBOS -Agents SDK [DBOS](https://dbos.dev/) 통합을 사용하면 장애 및 재시작 전반에서 진행 상황을 보존하는 신뢰할 수 있는 에이전트를 실행할 수 있습니다. 장기 실행 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 확인하세요. +Agents SDK [DBOS](https://dbos.dev/) 통합을 사용하면 장애와 재시작 전반에 걸쳐 진행 상황을 보존하는 신뢰성 있는 에이전트를 실행할 수 있습니다. 장시간 실행되는 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/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` 제한을 초과할 때 발생합니다. 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료하지 못했음을 나타냅니다. 제한을 비활성화하려면 `max_turns=None`을 설정하세요. -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기본 모델(LLM)이 예기치 않거나 잘못된 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다. - - 잘못된 JSON: 모델이 도구 호출 또는 직접 출력에서 잘못된 JSON 구조를 제공하는 경우, 특히 특정 `output_type`이 정의된 경우 - - 예기치 않은 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못하는 경우 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 이 예외는 함수 도구 호출이 구성된 타임아웃을 초과하고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다. -- [`UserError`][agents.exceptions.UserError]: 이 예외는 (SDK를 사용해 코드를 작성하는) 사용자가 SDK 사용 중 오류를 만들 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성 또는 SDK API의 오용으로 인해 발생합니다. +- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 이 예외는 에이전트 실행이 `Runner.run`, `Runner.run_sync` 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 이는 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료할 수 없었음을 나타냅니다. 제한을 비활성화하려면 `max_turns=None`을 설정하세요. +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기반 모델(LLM)이 예상치 못한 출력 또는 유효하지 않은 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다. + - 잘못된 형식의 JSON: 모델이 도구 호출 또는 직접 출력에서 잘못된 형식의 JSON 구조를 제공하는 경우, 특히 특정 `output_type`이 정의된 경우 + - 예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못하는 경우 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 이 예외는 함수 도구 호출이 구성된 timeout을 초과하고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다. +- [`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/sandbox/clients.md b/docs/ko/sandbox/clients.md index 4d9b3e1f83..b5cd21677c 100644 --- a/docs/ko/sandbox/clients.md +++ b/docs/ko/sandbox/clients.md @@ -4,40 +4,40 @@ search: --- # 샌드박스 클라이언트 -이 페이지를 사용해 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 동일하게 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. +이 페이지를 사용하여 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 그대로 두고, [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 클라이언트별 옵션만 변경합니다. !!! warning "베타 기능" - 샌드박스 에이전트는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. + 샌드박스 에이전트는 베타입니다. API의 세부 사항, 기본값, 지원 기능은 정식 출시 전 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다. -## 선택 가이드 +## 결정 가이드
-| 목표 | 시작점 | 이유 | +| 목표 | 시작 대상 | 이유 | | --- | --- | --- | -| macOS 또는 Linux에서 가장 빠른 로컬 반복 작업 | `UnixLocalSandboxClient` | 추가 설치가 필요 없고, 로컬 파일시스템 개발이 간단합니다. | -| 기본적인 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지를 사용해 Docker 내부에서 작업을 실행합니다. | -| 호스팅 실행 또는 프로덕션 수준 격리 | 호스팅 샌드박스 클라이언트 | 작업공간 경계를 공급자가 관리하는 환경으로 옮깁니다. | +| macOS 또는 Linux에서 가장 빠른 로컬 반복 개발 | `UnixLocalSandboxClient` | 추가 설치가 필요 없고, 로컬 파일 시스템 개발이 간단합니다. | +| 기본 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지로 Docker 내부에서 작업을 실행합니다. | +| 호스티드 실행 또는 프로덕션 스타일 격리 | 호스티드 샌드박스 클라이언트 | 워크스페이스 경계를 제공자가 관리하는 환경으로 이동합니다. |
## 로컬 클라이언트 -대부분의 사용자에게는 다음 두 가지 샌드박스 클라이언트 중 하나로 시작하는 것을 권장합니다. +대부분의 사용자는 다음 두 샌드박스 클라이언트 중 하나로 시작하는 것이 좋습니다.
-| 클라이언트 | 설치 | 이런 경우 선택 | 예제 | +| 클라이언트 | 설치 | 선택 시점 | 예시 | | --- | --- | --- | --- | -| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 작업이 필요할 때. 로컬 개발에 좋은 기본값입니다. | [Unix-local 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | -| `DockerSandboxClient` | `openai-agents[docker]` | 컨테이너 격리 또는 로컬 환경 일치를 위한 특정 이미지가 필요할 때 | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) | +| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 개발이 필요할 때. 로컬 개발의 좋은 기본값입니다. | [Unix-local 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | +| `DockerSandboxClient` | `openai-agents[docker]` | 컨테이너 격리 또는 로컬 환경과의 동등성을 위한 특정 이미지가 필요할 때. | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
-Unix-local은 로컬 파일시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강력한 환경 격리나 프로덕션 수준의 환경 일치가 필요하면 Docker 또는 호스팅 공급자로 이동하세요. +Unix-local은 로컬 파일 시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강력한 환경 격리 또는 프로덕션 스타일의 동등성이 필요할 때 Docker나 호스티드 제공자로 이동하세요. -Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하면 됩니다. +Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하세요. ```python from docker import from_env as docker_from_env @@ -54,74 +54,74 @@ run_config = RunConfig( ) ``` -컨테이너 격리 또는 이미지 일치가 필요할 때 이 방식을 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요. +컨테이너 격리 또는 이미지 동등성이 필요할 때 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요. ## 마운트와 원격 스토리지 -마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 내장 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스팅 공급자 전략은 `agents.extensions.sandbox` 또는 공급자별 확장 패키지에서 사용할 수 있습니다. +마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 기본 제공 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스티드 제공자 전략은 `agents.extensions.sandbox` 또는 제공자별 확장 패키지에서 사용할 수 있습니다. 일반적인 마운트 옵션: - `mount_path`: 샌드박스에서 스토리지가 나타나는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다. -- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 하는 경우에만 `False`로 설정하세요. +- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 할 때만 `False`로 설정하세요. - `mount_strategy`: 필수입니다. 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요. -마운트는 일시적인 작업공간 항목으로 처리됩니다. 스냅샷 및 영속화 흐름에서는 마운트된 원격 스토리지를 저장된 작업공간에 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다. +마운트는 임시 워크스페이스 항목으로 취급됩니다. 스냅샷 및 지속성 플로우는 마운트된 원격 스토리지를 저장된 워크스페이스로 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다. 일반 로컬/컨테이너 전략:
-| 전략 또는 패턴 | 사용 시점 | 참고 | +| 전략 또는 패턴 | 사용 시점 | 참고 사항 | | --- | --- | --- | -| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone`을 실행할 수 있을 때 | S3, GCS, R2, Azure Blob, Box를 지원합니다. `RcloneMountPattern`은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다. | -| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3`가 있고 Mountpoint 방식의 S3 또는 S3 호환 액세스를 원할 때 | `S3Mount`와 `GCSMount`를 지원합니다. | -| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2`와 FUSE 지원이 있을 때 | `AzureBlobMount`를 지원합니다. | -| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files`가 있고 기존 S3 Files 마운트 대상에 접근할 수 있을 때 | `S3FilesMount`를 지원합니다. | -| `DockerVolumeMountStrategy(driver=...)` | Docker가 컨테이너 시작 전에 볼륨 드라이버 기반 마운트를 연결해야 할 때 | Docker 전용입니다. S3, GCS, R2, Azure Blob, Box는 `rclone`을 지원하며, S3와 GCS는 `mountpoint`도 지원합니다. | +| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone`을 실행할 수 있을 때. | S3, GCS, R2, Azure Blob, Box를 지원합니다. `RcloneMountPattern`은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다. | +| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3`가 있고 Mountpoint 스타일의 S3 또는 S3 호환 액세스를 원할 때. | `S3Mount` 및 `GCSMount`를 지원합니다. | +| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2`와 FUSE 지원이 있을 때. | `AzureBlobMount`를 지원합니다. | +| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files`가 있고 기존 S3 Files 마운트 대상에 접근할 수 있을 때. | `S3FilesMount`를 지원합니다. | +| `DockerVolumeMountStrategy(driver=...)` | Docker가 컨테이너 시작 전에 볼륨 드라이버 기반 마운트를 연결해야 할 때. | Docker 전용입니다. S3, GCS, R2, Azure Blob, Box는 `rclone`을 지원하며, S3와 GCS는 `mountpoint`도 지원합니다. |
-## 지원되는 호스팅 플랫폼 +## 지원되는 호스티드 플랫폼 -호스팅 환경이 필요할 때는 동일한 `SandboxAgent` 정의를 그대로 사용할 수 있으며, 일반적으로 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트만 변경하면 됩니다. +호스티드 환경이 필요한 경우 동일한 `SandboxAgent` 정의를 대개 그대로 사용할 수 있으며 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트만 변경하면 됩니다. -이 저장소 체크아웃이 아니라 배포된 SDK를 사용 중이라면, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요. +이 저장소 체크아웃 대신 배포된 SDK를 사용하는 경우, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 종속성을 설치하세요. -공급자별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참고하세요. +제공자별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참고하세요.
-| 클라이언트 | 설치 | 예제 | +| 클라이언트 | 설치 | 예시 | | --- | --- | --- | -| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) | -| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) | -| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) | -| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) | -| `ModalSandboxClient` | `openai-agents[modal]` | [Modal 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) | -| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) | -| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel 실행기](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) | +| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) | +| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) | +| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) | +| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) | +| `ModalSandboxClient` | `openai-agents[modal]` | [Modal 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) | +| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) | +| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
-호스팅 샌드박스 클라이언트는 공급자별 마운트 전략을 제공합니다. 스토리지 공급자에 가장 적합한 백엔드와 마운트 전략을 선택하세요. +호스티드 샌드박스 클라이언트는 제공자별 마운트 전략을 노출합니다. 사용 중인 스토리지 제공자에 가장 적합한 백엔드와 마운트 전략을 선택하세요.
| 백엔드 | 마운트 참고 사항 | | --- | --- | -| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy`와 같은 로컬 전략을 사용해 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount`를 지원합니다. | -| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `ModalCloudBucketMountStrategy`를 사용한 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름 있는 Modal Secret을 사용할 수 있습니다. | -| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `CloudflareBucketMountStrategy`를 사용한 Cloudflare 버킷 마운트를 지원합니다. | -| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 사용한 영구 Blaxel Drive도 지원합니다. | -| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | -| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | -| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | -| `VercelSandboxClient` | 현재 호스팅 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소 또는 기타 작업공간 입력을 사용하세요. | +| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy` 같은 로컬 전략으로 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount`를 지원합니다. | +| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `ModalCloudBucketMountStrategy`로 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다. | +| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `CloudflareBucketMountStrategy`로 Cloudflare 버킷 마운트를 지원합니다. | +| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`로 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 통해 영구 Blaxel Drives도 지원합니다. | +| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | +| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | +| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. | +| `VercelSandboxClient` | 현재 노출된 호스티드 전용 마운트 전략은 없습니다. 대신 매니페스트 파일, 리포지토리 또는 기타 워크스페이스 입력을 사용하세요. |
-아래 표는 각 백엔드가 어떤 원격 스토리지 항목을 직접 마운트할 수 있는지 요약합니다. +아래 표는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목을 요약합니다.
@@ -138,4 +138,4 @@ run_config = RunConfig(
-실행 가능한 예제를 더 보려면 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴은 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)를, 호스팅 샌드박스 클라이언트는 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)를 살펴보세요. \ No newline at end of file +실행 가능한 더 많은 예제는 로컬, 코딩, 메모리, 핸드오프 및 에이전트 구성 패턴에 대해 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)를, 호스티드 샌드박스 클라이언트에 대해 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)를 둘러보세요. \ No newline at end of file diff --git a/docs/ko/sandbox/guide.md b/docs/ko/sandbox/guide.md index 174bfeec65..7873dc01e9 100644 --- a/docs/ko/sandbox/guide.md +++ b/docs/ko/sandbox/guide.md @@ -6,35 +6,35 @@ search: !!! warning "베타 기능" - 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 출시 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. + 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. -최신 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **샌드박스 에이전트**는 특화된 도구와 셸 명령을 사용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 산출물을 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델이 사용자를 대신해 작업하는 데 사용할 수 있는 지속적인 작업공간을 제공합니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 짝을 이룬 에이전트를 쉽게 실행하도록 도와주며, 적절한 파일을 파일시스템에 배치하고 샌드박스를 오케스트레이션해 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다. +현대적인 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. **샌드박스 에이전트**는 특화된 도구와 셸 명령을 사용하여 대규모 문서 세트를 검색 및 조작하고, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 작업 공간을 제공하며, 에이전트는 이를 사용해 사용자를 대신하여 작업을 수행할 수 있습니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 결합된 에이전트를 쉽게 실행할 수 있도록 도와주며, 파일 시스템에 적절한 파일을 배치하고 샌드박스를 조율하여 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다. -에이전트에 필요한 데이터를 중심으로 작업공간을 정의합니다. GitHub 리포지토리, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다. +에이전트가 필요로 하는 데이터를 중심으로 작업 공간을 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일 시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
-![컴퓨트가 포함된 샌드박스 에이전트 하네스](../assets/images/harness_with_compute.png) +![컴퓨팅이 포함된 샌드박스 에이전트 하네스](../assets/images/harness_with_compute.png)
-`SandboxAgent`도 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다. +`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다: -- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다. -- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함해 새 샌드박스 작업공간의 원하는 시작 콘텐츠와 레이아웃을 선언합니다. -- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 살아 있는 격리 환경입니다. -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 얻을지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 재연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성합니다. -- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행이 이전 작업에 재연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시드할 수 있습니다. +- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값과 파일 시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다. +- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함하여 새 샌드박스 작업 공간의 원하는 시작 콘텐츠와 레이아웃을 선언합니다. +- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 라이브 격리 환경입니다. +- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성하는 방식으로 실행이 해당 샌드박스 세션을 얻는 방법을 결정합니다. +- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 시드할 수 있습니다. -`Manifest`는 새 세션 작업공간 계약이지, 모든 라이브 샌드박스의 전체 진실 공급원이 아닙니다. 실행의 실제 작업공간은 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시 선택된 스냅샷에서 올 수 있습니다. +`Manifest`는 새 세션 작업 공간 계약이지, 모든 라이브 샌드박스에 대한 전체 기준 정보는 아닙니다. 실행의 유효 작업 공간은 대신 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시 선택된 스냅샷에서 올 수 있습니다. -이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 살아 있는 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에 설명된 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와 다릅니다. +이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 라이브 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에 설명된 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와 다릅니다. -외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 기록을 소유합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 소유합니다. 이 분리는 모델의 핵심 요소입니다. +외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 bookkeeping을 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 이 모델의 핵심입니다. ### 구성 요소의 결합 방식 -샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 살아 있는 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다. +샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. runner는 에이전트를 준비하고, 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다. ```mermaid flowchart LR @@ -52,31 +52,31 @@ flowchart LR 샌드박스별 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다. -생명주기는 세 단계로 생각할 수 있습니다. +수명 주기를 세 단계로 생각해 보세요: -1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 작업공간 계약을 정의합니다. -2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공해 실행을 수행합니다. -3. 러너가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 작업공간 스냅샷에서 나중에 계속합니다. +1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 작업 공간 계약을 정의합니다. +2. `Runner`에 샌드박스 세션을 주입, 재개, 또는 생성하는 `SandboxRunConfig`를 제공하여 실행을 수행합니다. +3. runner가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 작업 공간 스냅샷에서 나중에 이어서 진행합니다. -셸 접근이 가끔 쓰는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 작업공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. +셸 접근이 가끔 사용하는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸로 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 선택하세요. ## 사용 시점 -샌드박스 에이전트는 다음과 같은 작업공간 중심 워크플로에 적합합니다. +샌드박스 에이전트는 작업 공간 중심 워크플로에 적합합니다. 예를 들면 다음과 같습니다: -- 코딩과 디버깅, 예를 들어 GitHub 리포지토리의 이슈 보고서에 대한 자동 수정 오케스트레이션 및 대상 테스트 실행 -- 문서 처리와 편집, 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성된 세금 양식 초안 생성 -- 파일 기반 검토 또는 분석, 예를 들어 답변 전 온보딩 패킷, 생성된 보고서, 산출물 번들 확인 -- 격리된 멀티 에이전트 패턴, 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 작업공간 제공 -- 다단계 작업공간 작업, 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개 +- 코딩 및 디버깅, 예를 들어 GitHub 리포지토리의 이슈 보고에 대한 자동 수정 조율과 대상 테스트 실행 +- 문서 처리 및 편집, 예를 들어 사용자의 재무 문서에서 정보를 추출하고 완성된 세금 양식 초안 작성 +- 파일 기반 검토 또는 분석, 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 아티팩트 번들 확인 +- 격리된 멀티 에이전트 패턴, 예를 들어 각 검토자나 코딩 하위 에이전트에 자체 작업 공간 제공 +- 다단계 작업 공간 태스크, 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개 -파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 작업공간 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요. +파일이나 살아 있는 파일 시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 작업 공간 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요. ## 샌드박스 클라이언트 선택 -로컬 개발에는 `UnixLocalSandboxClient`부터 시작하세요. 컨테이너 격리 또는 이미지 동등성이 필요하면 `DockerSandboxClient`로 이동하세요. 공급자 관리 실행이 필요하면 호스티드 공급자로 이동하세요. +로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리나 이미지 일관성이 필요하면 `DockerSandboxClient`로 이동하세요. 제공자 관리 실행이 필요하면 호스티드 제공자로 이동하세요. -대부분의 경우 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 해당 옵션만 변경하고 `SandboxAgent` 정의는 그대로 유지됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요. +대부분의 경우 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 그 옵션만 변경되며, `SandboxAgent` 정의는 그대로 유지됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참고하세요. ## 핵심 구성 요소 @@ -84,68 +84,68 @@ flowchart LR | 계층 | 주요 SDK 구성 요소 | 답하는 질문 | | --- | --- | --- | -| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트를 실행하며, 어떤 새 세션 작업공간 계약에서 시작해야 하나요? | -| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 살아 있는 샌드박스 세션 | 이 실행은 살아 있는 샌드박스 세션을 어떻게 얻고, 작업은 어디에서 실행되나요? | -| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 재연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시드하나요? | +| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 작업 공간 계약에서 시작해야 하나요? | +| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 어떻게 라이브 샌드박스 세션을 얻으며, 작업은 어디에서 실행되나요? | +| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 어떻게 이전 샌드박스 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 시드하나요? | -주요 SDK 구성 요소는 다음과 같이 이러한 계층에 매핑됩니다. +주요 SDK 구성 요소는 이러한 계층에 다음과 같이 대응됩니다:
-| 구성 요소 | 소유하는 것 | 물어볼 질문 | +| 구성 요소 | 담당 범위 | 질문 | | --- | --- | --- | | [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 이동해야 하나요? | -| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 작업공간 파일과 폴더 | 실행이 시작될 때 파일시스템에 어떤 파일과 폴더가 있어야 하나요? | -| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 어떤 도구, 지침 조각, 또는 런타임 동작을 이 에이전트에 붙여야 하나요? | -| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트와 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 또는 생성해야 하나요? | -| [`RunState`][agents.run_state.RunState] | 러너 관리 저장 샌드박스 상태 | 이전 러너 관리 워크플로를 재개하며 그 샌드박스 상태를 자동으로 이어가고 있나요? | -| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적 직렬화 샌드박스 세션 상태 | `RunState` 외부에서 이미 직렬화한 샌드박스 상태에서 재개하고 싶나요? | -| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션을 위한 저장된 작업공간 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 산출물에서 시작해야 하나요? | +| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 작업 공간 파일 및 폴더 | 실행이 시작될 때 파일 시스템에 어떤 파일과 폴더가 있어야 하나요? | +| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 이 에이전트에 어떤 도구, 지침 조각, 또는 런타임 동작을 연결해야 하나요? | +| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트 및 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 또는 생성해야 하나요? | +| [`RunState`][agents.run_state.RunState] | runner가 관리하는 저장된 샌드박스 상태 | 이전 runner 관리 워크플로를 재개하고 그 샌드박스 상태를 자동으로 이어받고 있나요? | +| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적으로 직렬화된 샌드박스 세션 상태 | `RunState` 외부에서 이미 직렬화한 샌드박스 상태에서 재개하고 싶나요? | +| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션을 위한 저장된 작업 공간 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하나요? |
-실용적인 설계 순서는 다음과 같습니다. +실용적인 설계 순서는 다음과 같습니다: -1. `Manifest`로 새 세션 작업공간 계약을 정의합니다. +1. `Manifest`로 새 세션 작업 공간 계약을 정의합니다. 2. `SandboxAgent`로 에이전트를 정의합니다. 3. 기본 제공 또는 사용자 지정 기능을 추가합니다. -4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 어떻게 얻을지 결정합니다. +4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 얻는 방식을 결정합니다. ## 샌드박스 실행 준비 방식 -실행 시 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다. +실행 시 runner는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다: -1. `SandboxRunConfig`에서 샌드박스 세션을 해석합니다. - `session=...`을 전달하면 해당 살아 있는 샌드박스 세션을 재사용합니다. - 그렇지 않으면 `client=...`를 사용해 하나를 생성하거나 재개합니다. -2. 실행의 실제 작업공간 입력을 결정합니다. - 실행이 샌드박스 세션을 주입하거나 재개하면 기존 샌드박스 상태가 우선합니다. - 그렇지 않으면 러너는 일회성 매니페스트 오버라이드 또는 `agent.default_manifest`에서 시작합니다. - 이것이 `Manifest`만으로 모든 실행의 최종 라이브 작업공간이 정의되지 않는 이유입니다. -3. 기능이 결과 매니페스트를 처리하게 합니다. - 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 작업공간 범위 동작을 추가할 수 있습니다. -4. 고정된 순서로 최종 instructions를 구성합니다. - SDK의 기본 샌드박스 프롬프트 또는 명시적으로 오버라이드한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 지침 조각, 그다음 원격 마운트 정책 텍스트, 그다음 렌더링된 파일시스템 트리입니다. -5. 기능 도구를 살아 있는 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다. +1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다. + `session=...`을 전달하면 해당 라이브 샌드박스 세션을 재사용합니다. + 그렇지 않으면 `client=...`를 사용해 세션을 생성하거나 재개합니다. +2. 실행의 유효 작업 공간 입력을 결정합니다. + 실행이 샌드박스 세션을 주입하거나 재개하는 경우, 기존 샌드박스 상태가 우선합니다. + 그렇지 않으면 runner는 일회성 매니페스트 오버라이드 또는 `agent.default_manifest`에서 시작합니다. + 이 때문에 `Manifest`만으로 모든 실행의 최종 라이브 작업 공간이 정의되지는 않습니다. +3. 기능이 결과 매니페스트를 처리하도록 합니다. + 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 작업 공간 범위 동작을 추가할 수 있습니다. +4. 고정된 순서로 최종 instructions를 구성합니다: + SDK의 기본 샌드박스 프롬프트, 또는 명시적으로 오버라이드한 경우 `base_instructions`, 그다음 `instructions`, 기능 지침 조각, 원격 마운트 정책 텍스트, 렌더링된 파일 시스템 트리 순서입니다. +5. 기능 도구를 라이브 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다. -샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 모델 단계이지, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 안에 남을 수 있고, 다른 작업은 도구 결과, 승인, 또는 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실용적인 규칙으로, 샌드박스 작업이 발생한 후 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 다른 턴이 소비됩니다. +샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 동작이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머무를 수 있고, 다른 작업은 또 다른 모델 단계가 필요한 도구 결과, 승인, 또는 기타 상태를 반환할 수 있습니다. 실용적인 규칙으로는, 샌드박스 작업이 발생한 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 턴이 소비됩니다. -이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 고려해야 할 주요 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다. +이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 주로 고려해야 하는 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다. ## `SandboxAgent` 옵션 -일반적인 `Agent` 필드에 더해 제공되는 샌드박스별 옵션은 다음과 같습니다. +다음은 일반적인 `Agent` 필드에 더해 제공되는 샌드박스별 옵션입니다:
-| 옵션 | 최적 사용 | +| 옵션 | 권장 사용처 | | --- | --- | -| `default_manifest` | 러너가 생성하는 새 샌드박스 세션의 기본 작업공간 | +| `default_manifest` | runner가 생성하는 새 샌드박스 세션의 기본 작업 공간 | | `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 | -| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 | -| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구와 동작 | +| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 우회 수단 | +| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구 및 동작 | | `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
@@ -154,101 +154,101 @@ flowchart LR ### `default_manifest` -`default_manifest`는 러너가 이 에이전트에 대해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요. +`default_manifest`는 runner가 이 에이전트를 위해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요. -이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 오버라이드할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 작업공간 상태를 유지합니다. +이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 오버라이드할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 작업 공간 상태를 유지합니다. ### `instructions` 및 `base_instructions` -다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 안내를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다. +여러 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 안내를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다. SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정하지 않아야 합니다.
-| 넣을 위치 | 용도 | 예시 | +| 위치 | 용도 | 예시 | | --- | --- | --- | | `instructions` | 에이전트를 위한 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검사한 다음 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." | | `base_instructions` | SDK 샌드박스 기본 프롬프트의 전체 대체 | 사용자 지정 저수준 샌드박스 래퍼 프롬프트 | -| 사용자 프롬프트 | 이 실행을 위한 일회성 요청 | "이 작업공간을 요약하세요." | -| 매니페스트의 작업공간 파일 | 더 긴 작업 명세, 리포지토리 로컬 지침, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 | +| 사용자 프롬프트 | 이 실행을 위한 일회성 요청 | "이 작업 공간을 요약하세요." | +| 매니페스트의 작업 공간 파일 | 더 긴 작업 사양, 리포지토리 로컬 지침, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
-`instructions`의 좋은 사용 예는 다음과 같습니다. +`instructions`의 좋은 사용 예는 다음과 같습니다: -- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트를 하나의 상호작용 프로세스에 유지합니다. -- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 검사 후 샌드박스 리뷰어가 사용자에게 직접 답변하지 못하도록 합니다. -- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성 파일이 실제로 `output/`에 위치하도록 요구합니다. -- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 작업공간 루트 기준 패치 경로를 명확히 합니다. +- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요한 경우 에이전트를 하나의 인터랙티브 프로세스 안에 유지합니다. +- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 검사 후 샌드박스 검토자가 사용자에게 직접 답변하는 것을 금지합니다. +- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성 파일이 실제로 `output/`에 저장되도록 요구합니다. +- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 작업 공간 루트 기준 패치 경로를 명확히 합니다. -사용자의 일회성 작업을 `instructions`에 복사하거나, 매니페스트에 있어야 할 긴 참고 자료를 포함하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 다시 설명하거나, 모델이 실행 시 필요로 하지 않는 로컬 설치 메모를 섞는 것은 피하세요. +사용자의 일회성 작업을 `instructions`에 복사하거나, 매니페스트에 속해야 하는 긴 참고 자료를 삽입하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시 필요로 하지 않는 로컬 설치 노트를 섞지 마세요. -`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적 `instructions`를 제공해야 합니다. +`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다. ### `capabilities` -기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 붙입니다. 실행이 시작되기 전에 작업공간을 형성하고, 샌드박스별 instructions를 추가하고, 살아 있는 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다. +기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 기능은 실행이 시작되기 전에 작업 공간을 구성하고, 샌드박스별 지침을 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하고, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다. -기본 제공 기능은 다음과 같습니다. +기본 제공 기능에는 다음이 포함됩니다:
-| 기능 | 추가 시점 | 참고 | +| 기능 | 추가할 때 | 참고 | | --- | --- | --- | -| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가합니다. | -| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 작업공간 루트 기준입니다. | -| `Skills` | 샌드박스에서 스킬 발견과 구체화를 원할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이를 선호하세요. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화합니다. | -| `Memory` | 후속 실행이 메모리 산출물을 읽거나 생성해야 할 때 | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. | -| `Compaction` | 장기 실행 흐름에서 컴팩션 항목 이후 컨텍스트 정리가 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다. | +| `Shell` | 에이전트에 셸 접근이 필요합니다. | `exec_command`를 추가하고, 샌드박스 클라이언트가 PTY 상호작용을 지원하는 경우 `write_stdin`도 추가합니다. | +| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 합니다. | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 작업 공간 루트 기준 상대 경로입니다. | +| `Skills` | 샌드박스에서 스킬 탐색과 구체화를 사용하고 싶습니다. | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 대신 이를 선호하세요. `Skills`는 스킬을 인덱싱하고 샌드박스 안에 구체화해 줍니다. | +| `Memory` | 후속 실행에서 메모리 아티팩트를 읽거나 생성해야 합니다. | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. | +| `Compaction` | 장기 실행 흐름에서 컴팩션 항목 이후 컨텍스트 줄이기가 필요합니다. | 모델 샘플링과 입력 처리를 조정합니다. |
-기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능을 포함하세요. +기본적으로 `SandboxAgent.capabilities`는 `Capabilities.default()`를 사용하며, 여기에는 `Filesystem()`, `Shell()`, `Compaction()`이 포함됩니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 계속 사용하려는 기본 기능을 포함하세요. -스킬의 경우, 어떻게 구체화할지에 따라 소스를 선택하세요. +스킬의 경우 원하는 구체화 방식에 따라 소스를 선택하세요: -- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있으므로 더 큰 로컬 스킬 디렉터리에 좋은 기본값입니다. -- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 작업공간 내부에만 존재하는 경로가 아니라 원래 호스트 측 스킬 디렉터리를 전달하세요. +- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 큰 로컬 스킬 디렉터리에 적합한 기본값입니다. 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있기 때문입니다. +- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일 시스템에서 읽습니다. 샌드박스 이미지나 작업 공간 내부에만 존재하는 경로가 아니라, 원래의 호스트 측 스킬 디렉터리를 전달하세요. - `Skills(from_=LocalDir(src=...))`는 미리 스테이징하려는 작은 로컬 번들에 더 적합합니다. - `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다. -`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 작업공간 내부의 상대 대상 경로입니다. +`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 작업 공간 내부의 상대 대상 경로입니다. -스킬이 이미 디스크의 `.agents/skills//SKILL.md` 같은 위치에 있다면, `LocalDir(...)`가 해당 소스 루트를 가리키게 하고 그래도 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 작업공간 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요. +스킬이 이미 `.agents/skills//SKILL.md` 같은 위치 아래 디스크에 있다면, `LocalDir(...)`가 해당 소스 루트를 가리키도록 하고 그래도 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 작업 공간 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요. -적합할 때는 기본 제공 기능을 선호하세요. 기본 제공 기능이 다루지 않는 샌드박스별 도구 또는 지침 표면이 필요할 때만 사용자 지정 기능을 작성하세요. +적합한 경우 기본 제공 기능을 선호하세요. 기본 제공 기능이 다루지 않는 샌드박스별 도구나 지침 표면이 필요할 때만 사용자 지정 기능을 작성하세요. ## 개념 ### 매니페스트 -[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 작업공간을 설명합니다. 작업공간 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자 또는 그룹을 정의하고, 작업공간 외부의 특정 절대 경로에 대한 접근을 부여할 수 있습니다. +[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 작업 공간을 설명합니다. 작업 공간 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사해 넣고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 작업 공간 외부의 특정 절대 경로에 대한 접근 권한을 부여할 수 있습니다. -매니페스트 항목 경로는 작업공간 기준 상대 경로입니다. 절대 경로일 수 없고 `..`로 작업공간을 벗어날 수 없습니다. 이를 통해 작업공간 계약이 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다. +매니페스트 항목 경로는 작업 공간 기준 상대 경로입니다. 절대 경로일 수 없으며 `..`로 작업 공간을 벗어날 수 없습니다. 이를 통해 작업 공간 계약이 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다. -작업이 시작되기 전에 에이전트에 필요한 자료에는 매니페스트 항목을 사용하세요. +작업이 시작되기 전에 에이전트가 필요로 하는 자료에는 매니페스트 항목을 사용하세요:
| 매니페스트 항목 | 용도 | | --- | --- | | `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 | -| `LocalFile`, `LocalDir` | 샌드박스에 구체화되어야 하는 호스트 파일 또는 디렉터리 | -| `GitRepo` | 작업공간으로 가져와야 하는 리포지토리 | +| `LocalFile`, `LocalDir` | 샌드박스 안에 구체화해야 하는 호스트 파일 또는 디렉터리 | +| `GitRepo` | 작업 공간으로 가져와야 하는 리포지토리 | | `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 마운트 | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
-`Dir`은 합성 자식에서 또는 출력 위치로 샌드박스 작업공간 내부에 디렉터리를 생성합니다. 호스트 파일시스템에서 읽지 않습니다. 기존 호스트 디렉터리를 샌드박스 작업공간으로 복사해야 할 때는 `LocalDir`를 사용하세요. +`Dir`는 합성 자식 항목에서 또는 출력 위치로 샌드박스 작업 공간 안에 디렉터리를 생성합니다. 호스트 파일 시스템에서 읽지는 않습니다. 기존 호스트 디렉터리를 샌드박스 작업 공간으로 복사해야 할 때는 `LocalDir`를 사용하세요. -`LocalFile.src`와 `LocalDir.src`는 기본적으로 SDK 프로세스 작업 디렉터리를 기준으로 해석됩니다. 소스는 `extra_path_grants`로 커버되지 않는 한 해당 기본 디렉터리 아래에 머물러야 합니다. 이렇게 하면 로컬 소스 구체화가 샌드박스 매니페스트의 나머지 부분과 동일한 호스트 경로 신뢰 경계 안에 유지됩니다. +`LocalFile.src`와 `LocalDir.src`는 기본적으로 SDK 프로세스 작업 디렉터리를 기준으로 확인됩니다. 소스는 `extra_path_grants`로 포함되지 않는 한 해당 기본 디렉터리 아래에 있어야 합니다. 이를 통해 로컬 소스 구체화가 나머지 샌드박스 매니페스트와 동일한 호스트 경로 신뢰 경계 안에 유지됩니다. -마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 공급자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요. +마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 제공자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참고하세요. -좋은 매니페스트 설계란 일반적으로 작업공간 계약을 좁게 유지하고, 긴 작업 레시피는 `repo/task.md` 같은 작업공간 파일에 넣으며, 지침에서 `repo/task.md` 또는 `output/report.md` 같은 상대 작업공간 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 작업공간 루트를 기준으로 한다는 점을 기억하세요. +좋은 매니페스트 설계란 일반적으로 작업 공간 계약을 좁게 유지하고, 긴 작업 지침은 `repo/task.md` 같은 작업 공간 파일에 넣고, 지침에서는 `repo/task.md` 또는 `output/report.md` 같은 작업 공간 상대 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 작업 공간 루트 기준 상대 경로임을 기억하세요. -`extra_path_grants`는 에이전트가 작업공간 외부의 구체적인 절대 경로를 필요로 하거나, 매니페스트가 SDK 프로세스 작업 디렉터리 외부의 신뢰할 수 있는 로컬 소스를 복사해야 할 때만 사용하세요. 예로는 임시 도구 출력을 위한 `/tmp`, 읽기 전용 런타임을 위한 `/opt/toolchain`, 또는 샌드박스에 구체화되어야 하는 생성된 스킬 디렉터리가 있습니다. 권한 부여는 로컬 소스 구체화, SDK 파일 API, 그리고 백엔드가 파일시스템 정책을 강제할 수 있는 경우 셸 실행에 적용됩니다. +`extra_path_grants`는 에이전트가 작업 공간 외부의 구체적인 절대 경로를 필요로 하거나, 매니페스트가 SDK 프로세스 작업 디렉터리 외부의 신뢰된 로컬 소스를 복사해야 할 때만 사용하세요. 예로는 임시 도구 출력을 위한 `/tmp`, 읽기 전용 런타임을 위한 `/opt/toolchain`, 또는 샌드박스에 구체화해야 하는 생성된 스킬 디렉터리가 있습니다. grant는 로컬 소스 구체화, SDK 파일 API, 그리고 백엔드가 파일 시스템 정책을 강제할 수 있는 경우 셸 실행에 적용됩니다: ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -261,15 +261,15 @@ manifest = Manifest( ) ``` -`extra_path_grants`가 포함된 매니페스트는 신뢰할 수 있는 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않은 한, 모델 출력이나 기타 신뢰할 수 없는 페이로드에서 권한 부여를 로드하지 마세요. +`extra_path_grants`가 포함된 매니페스트는 신뢰할 수 있는 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않은 한, 모델 출력이나 기타 신뢰할 수 없는 페이로드에서 grant를 로드하지 마세요. -스냅샷과 `persist_workspace()`는 여전히 작업공간 루트만 포함합니다. 추가로 권한이 부여된 경로는 런타임 접근이지, 지속 가능한 작업공간 상태가 아닙니다. +스냅샷과 `persist_workspace()`는 여전히 작업 공간 루트만 포함합니다. 추가로 grant된 경로는 런타임 접근 권한일 뿐, 지속되는 작업 공간 상태가 아닙니다. ### 권한 -`Permissions`는 매니페스트 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책, 또는 API 자격 증명에 관한 것이 아닙니다. +`Permissions`는 매니페스트 항목의 파일 시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책, API 자격 증명에 관한 것이 아닙니다. -기본적으로 매니페스트 항목은 소유자가 읽기/쓰기/실행 가능하고 그룹과 기타 사용자가 읽기/실행 가능합니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능해야 할 때 이를 오버라이드하세요. +기본적으로 매니페스트 항목은 소유자가 읽기/쓰기/실행할 수 있고, 그룹 및 기타 사용자가 읽기/실행할 수 있습니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능이어야 할 때 이를 오버라이드하세요: ```python from agents.sandbox import FileMode, Permissions @@ -285,9 +285,9 @@ private_notes = File( ) ``` -`Permissions`는 소유자, 그룹, 기타 비트를 별도로 저장하며, 항목이 디렉터리인지 여부도 저장합니다. 직접 빌드하거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다. +`Permissions`는 소유자, 그룹, 기타 권한 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 만들거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다. -사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 샌드박스에 해당 ID가 존재하게 하려면 매니페스트에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 해당 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 매니페스트에 아직 없는 사용자를 가리키면, 러너가 이를 실제 매니페스트에 자동으로 추가합니다. +사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 한다면 매니페스트에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 그 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 매니페스트에 아직 없는 사용자를 가리키면 runner가 유효 매니페스트에 이를 추가합니다. ```python from agents import Runner @@ -339,13 +339,13 @@ result = await Runner.run( ) ``` -파일 수준 공유 규칙도 필요하다면 사용자와 매니페스트 그룹 및 항목 `group` 메타데이터를 결합하세요. `run_as` 사용자는 샌드박스 네이티브 작업을 누가 실행하는지 제어하고, `Permissions`는 샌드박스가 작업공간을 구체화한 후 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지 제어합니다. +파일 수준 공유 규칙도 필요하다면 사용자와 매니페스트 그룹 및 항목 `group` 메타데이터를 조합하세요. `run_as` 사용자는 샌드박스 네이티브 작업을 실행하는 주체를 제어하고, `Permissions`는 샌드박스가 작업 공간을 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다. -### SnapshotSpec +### 스냅샷 사양 -`SnapshotSpec`은 저장된 작업공간 콘텐츠를 어디에서 복원하고 다시 어디에 영속화할지 새 샌드박스 세션에 알려줍니다. 이는 샌드박스 작업공간의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다. +`SnapshotSpec`은 새 샌드박스 세션이 저장된 작업 공간 콘텐츠를 어디에서 복원하고 어디로 다시 지속해야 하는지를 알려줍니다. 이는 샌드박스 작업 공간에 대한 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다. -로컬 지속 스냅샷에는 `LocalSnapshotSpec`를 사용하고, 앱이 원격 스냅샷 클라이언트를 제공할 때는 `RemoteSnapshotSpec`를 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 대체로 no-op 스냅샷이 사용되며, 고급 호출자는 작업공간 스냅샷 영속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다. +로컬 지속 스냅샷에는 `LocalSnapshotSpec`을 사용하고, 앱이 원격 스냅샷 클라이언트를 제공하는 경우 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 무작동 스냅샷이 fallback으로 사용되며, 고급 호출자는 작업 공간 스냅샷 지속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다. ```python from pathlib import Path @@ -362,13 +362,13 @@ run_config = RunConfig( ) ``` -러너가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트가 해당 세션의 스냅샷 인스턴스를 빌드합니다. 시작 시 스냅샷이 복원 가능하면, 샌드박스는 실행을 계속하기 전에 저장된 작업공간 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 작업공간을 아카이브하고 스냅샷을 통해 다시 영속화합니다. +runner가 새 샌드박스 세션을 만들면 샌드박스 클라이언트가 해당 세션을 위한 스냅샷 인스턴스를 빌드합니다. 시작 시 스냅샷을 복원할 수 있으면 샌드박스는 실행이 계속되기 전에 저장된 작업 공간 콘텐츠를 복원합니다. 정리 시 runner가 소유한 샌드박스 세션은 작업 공간을 아카이브하고 스냅샷을 통해 다시 지속합니다. -`snapshot`을 생략하면 런타임은 가능한 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 설정할 수 없으면 no-op 스냅샷으로 폴백합니다. 마운트된 경로와 임시 경로는 지속 가능한 작업공간 콘텐츠로 스냅샷에 복사되지 않습니다. +`snapshot`을 생략하면 런타임은 가능한 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 무작동 스냅샷으로 fallback합니다. 마운트된 경로와 임시 경로는 지속되는 작업 공간 콘텐츠로 스냅샷에 복사되지 않습니다. -### 샌드박스 생명주기 +### 샌드박스 수명 주기 -생명주기 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다. +수명 주기 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다.
@@ -396,7 +396,7 @@ sequenceDiagram
-샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 생명주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 작업공간 상태를 영속화하고, 샌드박스를 종료한 다음, 클라이언트가 러너 소유 리소스를 정리하게 합니다. +샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 수명 주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 runner가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 작업 공간 상태를 지속하고, 샌드박스를 종료하고, 클라이언트가 runner 소유 리소스를 정리하도록 합니다. ```python result = await Runner.run( @@ -408,7 +408,7 @@ result = await Runner.run( ) ``` -샌드박스를 미리 생성하거나, 여러 실행에서 하나의 살아 있는 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때 개발자 소유 생명주기를 사용하세요. `session=...`을 전달하면 러너가 해당 살아 있는 샌드박스를 사용하지만, 대신 닫아주지는 않습니다. +샌드박스를 미리 생성하거나, 여러 실행에서 하나의 라이브 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스를 대상으로 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때는 개발자 소유 수명 주기를 사용하세요. `session=...`을 전달하면 runner는 해당 라이브 샌드박스를 사용하지만 대신 닫지는 않습니다. ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -419,7 +419,7 @@ async with sandbox: await Runner.run(agent, "Write the final report.", run_config=run_config) ``` -컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 생명주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 생명주기 메서드를 직접 호출하세요. +일반적인 형태는 컨텍스트 매니저입니다. 진입 시 샌드박스를 시작하고, 종료 시 세션 정리 수명 주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명 주기 메서드를 직접 호출하세요: ```python sandbox = await client.create( @@ -440,64 +440,64 @@ finally: await sandbox.aclose() ``` -`stop()`은 스냅샷 기반 작업공간 콘텐츠만 영속화하며, 샌드박스를 해체하지 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다. +`stop()`은 스냅샷 기반 작업 공간 콘텐츠만 지속합니다. 샌드박스를 해체하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. 중지 전 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다. ## `SandboxRunConfig` 옵션 -[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디에서 오는지와 새 세션을 어떻게 초기화할지 결정하는 실행별 옵션을 보관합니다. +[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디에서 오는지, 그리고 새 세션을 어떻게 초기화할지를 결정하는 실행별 옵션을 보관합니다. ### 샌드박스 소스 -이 옵션은 러너가 샌드박스 세션을 재사용, 재개, 또는 생성해야 하는지 결정합니다. +이 옵션들은 runner가 샌드박스 세션을 재사용, 재개, 또는 생성해야 하는지를 결정합니다:
| 옵션 | 사용 시점 | 참고 | | --- | --- | --- | -| `client` | 러너가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 살아 있는 샌드박스 `session`을 제공하지 않는 한 필수입니다. | -| `session` | 이미 살아 있는 샌드박스 세션을 직접 생성했을 때 | 호출자가 생명주기를 소유하며, 러너는 해당 살아 있는 샌드박스 세션을 재사용합니다. | -| `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 살아 있는 샌드박스 세션 객체는 없을 때 | `client`가 필요합니다. 러너는 해당 명시적 상태에서 소유 세션으로 재개합니다. | +| `client` | runner가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 라이브 샌드박스 `session`을 제공하지 않는 한 필요합니다. | +| `session` | 이미 직접 라이브 샌드박스 세션을 생성했을 때 | 호출자가 수명 주기를 소유하며, runner는 해당 라이브 샌드박스 세션을 재사용합니다. | +| `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 라이브 샌드박스 세션 객체는 없을 때 | `client`가 필요합니다. runner는 해당 명시적 상태에서 소유 세션으로 재개합니다. |
-실제로 러너는 다음 순서로 샌드박스 세션을 해석합니다. +실제로 runner는 다음 순서로 샌드박스 세션을 확인합니다: -1. `run_config.sandbox.session`을 주입하면 해당 살아 있는 샌드박스 세션이 직접 재사용됩니다. +1. `run_config.sandbox.session`을 주입하면 해당 라이브 샌드박스 세션이 직접 재사용됩니다. 2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우, 저장된 샌드박스 세션 상태가 재개됩니다. -3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면, 러너는 해당 명시적 직렬화 샌드박스 세션 상태에서 재개합니다. -4. 그렇지 않으면 러너는 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 그렇지 않으면 `agent.default_manifest`를 사용합니다. +3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면 runner가 해당 명시적으로 직렬화된 샌드박스 세션 상태에서 재개합니다. +4. 그렇지 않으면 runner가 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 그렇지 않으면 `agent.default_manifest`를 사용합니다. ### 새 세션 입력 -이 옵션은 러너가 새 샌드박스 세션을 생성할 때만 중요합니다. +이 옵션들은 runner가 새 샌드박스 세션을 생성할 때만 의미가 있습니다:
| 옵션 | 사용 시점 | 참고 | | --- | --- | --- | -| `manifest` | 일회성 새 세션 작업공간 오버라이드를 원할 때 | 생략 시 `agent.default_manifest`로 폴백합니다. | -| `snapshot` | 새 샌드박스 세션을 스냅샷에서 시드해야 할 때 | 재개와 유사한 흐름이나 원격 스냅샷 클라이언트에 유용합니다. | +| `manifest` | 일회성 새 세션 작업 공간 오버라이드를 원할 때 | 생략하면 `agent.default_manifest`로 fallback합니다. | +| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시드되어야 할 때 | 재개와 유사한 흐름 또는 원격 스냅샷 클라이언트에 유용합니다. | | `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃, 유사한 클라이언트별 설정에 일반적입니다. |
### 구체화 제어 -`concurrency_limits`는 병렬로 실행될 수 있는 샌드박스 구체화 작업의 양을 제어합니다. 큰 매니페스트나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요. +`concurrency_limits`는 병렬로 실행될 수 있는 샌드박스 구체화 작업량을 제어합니다. 큰 매니페스트나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요. -`archive_limits`는 아카이브 추출에 대한 SDK 측 리소스 검사를 제어합니다. SDK 기본 임계값을 활성화하려면 `archive_limits=SandboxArchiveLimits()`를 설정하거나, 아카이브에 더 엄격한 리소스 제어가 필요할 때 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` 같은 명시적 값을 전달하세요. SDK 아카이브 리소스 제한 없이 기본 동작을 유지하려면 `archive_limits=None`으로 두고, 해당 제한만 비활성화하려면 개별 필드를 `None`으로 설정하세요. +`archive_limits`는 아카이브 추출에 대한 SDK 측 리소스 검사를 제어합니다. SDK 기본 임계값을 활성화하려면 `archive_limits=SandboxArchiveLimits()`를 설정하거나, 아카이브에 더 엄격한 리소스 제어가 필요할 때 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` 같은 명시적 값을 전달하세요. SDK 아카이브 리소스 제한이 없는 기본 동작을 유지하려면 `archive_limits=None`으로 두거나, 특정 제한만 비활성화하려면 개별 필드를 `None`으로 설정하세요. -유념할 만한 몇 가지 함의는 다음과 같습니다. +몇 가지 영향을 염두에 둘 필요가 있습니다: -- 새 세션: `manifest=`와 `snapshot=`은 러너가 새 샌드박스 세션을 생성할 때만 적용됩니다. -- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 재연결하는 반면, `snapshot=`은 저장된 작업공간 콘텐츠에서 새 샌드박스 세션을 시드합니다. -- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라지며, Docker와 많은 호스티드 클라이언트에는 이것이 필요합니다. +- 새 세션: `manifest=`와 `snapshot=`은 runner가 새 샌드박스 세션을 생성할 때만 적용됩니다. +- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 다시 연결하는 반면, `snapshot=`은 저장된 작업 공간 콘텐츠에서 새 샌드박스 세션을 시드합니다. +- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라집니다. Docker와 많은 호스티드 클라이언트에는 필요합니다. - 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 매니페스트 업데이트가 호환되는 비마운트 항목을 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다. -- 러너 API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다. +- Runner API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다. -## 전체 예시: 코딩 작업 +## 전체 예제: 코딩 작업 -이 코딩 스타일 예시는 좋은 기본 시작점입니다. +이 코딩 스타일 예제는 좋은 기본 시작점입니다: ```python import asyncio @@ -576,19 +576,19 @@ if __name__ == "__main__": ) ``` -[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예시는 작은 셸 기반 리포지토리를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다. 실제 작업 리포지토리는 물론 Python, JavaScript, 또는 그 밖의 무엇이든 될 수 있습니다. +[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 이 예제는 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있도록 작은 셸 기반 리포지토리를 사용합니다. 실제 작업 리포지토리는 물론 Python, JavaScript 또는 그 밖의 어떤 것이어도 됩니다. ## 일반적인 패턴 -위의 전체 예시에서 시작하세요. 많은 경우 동일한 `SandboxAgent`를 그대로 유지하면서 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 작업공간 소스만 변경할 수 있습니다. +위의 전체 예제에서 시작하세요. 많은 경우 동일한 `SandboxAgent`를 그대로 유지하면서 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 작업 공간 소스만 변경할 수 있습니다. ### 샌드박스 클라이언트 전환 -에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리 또는 이미지 동등성을 원할 때 Docker를 사용하고, 공급자 관리 실행을 원할 때 호스티드 공급자를 사용하세요. 예시와 공급자 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요. +에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리나 이미지 일관성이 필요하면 Docker를 사용하고, 제공자 관리 실행을 원하면 호스티드 제공자를 사용하세요. 예제와 제공자 옵션은 [샌드박스 클라이언트](clients.md)를 참고하세요. -### 작업공간 오버라이드 +### 작업 공간 오버라이드 -에이전트 정의는 그대로 두고 새 세션 매니페스트만 교체하세요. +에이전트 정의는 그대로 두고 새 세션 매니페스트만 교체하세요: ```python from agents.run import RunConfig @@ -608,11 +608,11 @@ run_config = RunConfig( ) ``` -에이전트를 다시 빌드하지 않고 동일한 에이전트 역할을 다른 리포지토리, 패킷, 또는 작업 번들에 대해 실행해야 할 때 사용하세요. 위의 검증된 코딩 예시는 일회성 오버라이드 대신 `default_manifest`로 동일한 패턴을 보여줍니다. +동일한 에이전트 역할을 여러 리포지토리, 패킷, 또는 작업 번들에 대해 실행해야 하지만 에이전트를 다시 빌드하고 싶지 않을 때 사용하세요. 위의 검증된 코딩 예제는 일회성 오버라이드 대신 `default_manifest`로 동일한 패턴을 보여줍니다. ### 샌드박스 세션 주입 -명시적 생명주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 살아 있는 샌드박스 세션을 주입하세요. +명시적 수명 주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 라이브 샌드박스 세션을 주입하세요: ```python from agents import Runner @@ -633,11 +633,11 @@ async with sandbox: ) ``` -실행 후 작업공간을 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 및 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참조하세요. +실행 후 작업 공간을 검사하거나 이미 시작된 샌드박스 세션을 대상으로 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요. ### 세션 상태에서 재개 -`RunState` 외부에서 이미 샌드박스 상태를 직렬화했다면, 러너가 해당 상태에서 재연결하게 하세요. +`RunState` 외부에서 샌드박스 상태를 이미 직렬화했다면 runner가 그 상태에서 다시 연결하도록 하세요: ```python from agents.run import RunConfig @@ -654,11 +654,11 @@ run_config = RunConfig( ) ``` -샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 여기에서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참조하세요. +샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 여기서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참고하세요. ### 스냅샷에서 시작 -저장된 파일과 산출물에서 새 샌드박스를 시드하세요. +저장된 파일과 아티팩트에서 새 샌드박스를 시드하세요: ```python from pathlib import Path @@ -675,11 +675,11 @@ run_config = RunConfig( ) ``` -새 실행이 `agent.default_manifest`만이 아니라 저장된 작업공간 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를, 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참조하세요. +새 실행이 `agent.default_manifest`만이 아니라 저장된 작업 공간 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를, 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참고하세요. ### Git에서 스킬 로드 -로컬 스킬 소스를 리포지토리 기반 소스로 교체하세요. +로컬 스킬 소스를 리포지토리 기반 소스로 교체하세요: ```python from agents.sandbox.capabilities import Capabilities, Skills @@ -690,11 +690,11 @@ capabilities = Capabilities.default() + [ ] ``` -스킬 번들이 자체 릴리스 주기를 가지거나 여러 샌드박스에서 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참조하세요. +스킬 번들에 자체 릴리스 주기가 있거나 여러 샌드박스에서 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참고하세요. ### 도구로 노출 -도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 상위 실행의 살아 있는 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 부모가 사용하는 정확한 작업공간을 검사할 수 있습니다. +도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 상위 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색기 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 상위 에이전트가 사용 중인 정확한 작업 공간을 검사할 수 있기 때문입니다. ```python from agents import Runner @@ -776,9 +776,9 @@ async with sandbox: ) ``` -여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 살아 있는 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기는 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로, 탐색기는 읽기 전용으로 유지되는 동안 부모는 최종 산출물을 쓸 수 있습니다. +여기서 상위 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 같은 라이브 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기가 빠르게 검사할 수 있지만, 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로, 상위 에이전트는 탐색기가 읽기 전용으로 남아 있는 동안 최종 아티팩트를 작성할 수 있습니다. -도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요. +도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요: ```python from docker import from_env as docker_from_env @@ -799,11 +799,11 @@ rollout_agent.as_tool( ) ``` -도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요. +도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요. ### 로컬 도구 및 MCP와 결합 -동일한 에이전트에서 일반 도구를 사용하면서 샌드박스 작업공간을 유지하세요. +동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 작업 공간을 유지하세요: ```python from agents.sandbox import SandboxAgent @@ -818,46 +818,46 @@ agent = SandboxAgent( ) ``` -작업공간 검사가 에이전트 작업의 일부일 뿐일 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참조하세요. +작업 공간 검사가 에이전트 작업의 일부에 불과할 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참고하세요. ## 메모리 -이후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 할 때 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 교훈을 샌드박스 작업공간 내부의 파일로 정제하고, 이후 실행이 해당 파일을 읽을 수 있게 합니다. +향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 한다면 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 메모리는 학습 내용을 샌드박스 작업 공간 내부의 파일로 증류하고, 이후 실행은 해당 파일을 읽을 수 있습니다. -설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참조하세요. +설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참고하세요. ## 구성 패턴 -단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인가입니다. +단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인지입니다. -샌드박스 에이전트는 여전히 SDK의 나머지 부분과 구성할 수 있습니다. +샌드박스 에이전트는 여전히 SDK의 나머지 부분과 함께 구성됩니다: -- [핸드오프](../handoffs.md): 문서가 많은 작업을 비샌드박스 접수 에이전트에서 샌드박스 리뷰어로 넘깁니다. -- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달해 각 도구가 자체 샌드박스 경계를 갖게 합니다. +- [핸드오프](../handoffs.md): 문서 중심 작업을 비샌드박스 접수 에이전트에서 샌드박스 검토자로 넘깁니다. +- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달하여 각 도구가 자체 샌드박스 경계를 갖도록 합니다. - [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다. - [에이전트 실행](../running_agents.md): 샌드박스 실행은 여전히 일반 `Runner` API를 사용합니다. -특히 흔한 두 가지 패턴은 다음과 같습니다. +특히 다음 두 가지 패턴이 일반적입니다: -- 작업공간 격리가 필요한 워크플로 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프 -- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용해 각 도구가 자체 격리 작업공간을 갖게 함 +- 워크플로 중 작업 공간 격리가 필요한 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프 +- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용하여 각 도구가 자체 격리 작업 공간을 갖도록 함 -### 턴과 샌드박스 실행 +### 턴 및 샌드박스 실행 -핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다. +핸드오프와 에이전트-도구 호출은 별도로 설명하는 것이 도움이 됩니다. -핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 리뷰어에게 핸드오프하면, 같은 실행에서 다음 모델 호출이 샌드박스 에이전트용으로 준비되고, 해당 샌드박스 에이전트가 다음 턴을 수행하는 에이전트가 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 소유하는 에이전트를 변경합니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참조하세요. +핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 검토자로 핸드오프하면, 같은 실행의 다음 모델 호출이 샌드박스 에이전트를 위해 준비되고, 해당 샌드박스 에이전트가 다음 턴을 수행하는 주체가 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 어느 에이전트가 소유하는지를 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참고하세요. -`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구를 호출하기로 결정하는 데 외부 턴 하나를 사용하고, 해당 도구 호출은 샌드박스 에이전트의 중첩 실행을 시작합니다. 중첩 실행은 자체 턴 루프, `max_turns`, 승인, 그리고 일반적으로 자체 샌드박스 `RunConfig`를 가집니다. 중첩 턴 하나로 끝날 수도 있고 여러 턴이 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 턴은 외부 실행의 턴 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요. +`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구 호출을 결정하기 위해 하나의 외부 턴을 사용하고, 해당 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행에는 자체 턴 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`가 있습니다. 하나의 중첩 턴으로 끝날 수도 있고 여러 턴이 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 턴은 외부 실행의 턴 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요. -승인 동작도 같은 분리를 따릅니다. +승인 동작도 같은 분리를 따릅니다: - 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인이 같은 최상위 실행에 유지됩니다. -- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 나타나지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다. +- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 표시되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다. ## 추가 자료 - [빠른 시작](quickstart.md): 샌드박스 에이전트 하나를 실행합니다. - [샌드박스 클라이언트](clients.md): 로컬, Docker, 호스티드, 마운트 옵션을 선택합니다. -- [에이전트 메모리](memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용합니다. +- [에이전트 메모리](memory.md): 이전 샌드박스 실행의 학습 내용을 보존하고 재사용합니다. - [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴. \ No newline at end of file diff --git a/docs/ko/sandbox/memory.md b/docs/ko/sandbox/memory.md index 584248a925..1f2fb44256 100644 --- a/docs/ko/sandbox/memory.md +++ b/docs/ko/sandbox/memory.md @@ -4,23 +4,23 @@ search: --- # 에이전트 메모리 -메모리를 사용하면 이후의 sandbox-agent 실행이 이전 실행에서 학습할 수 있습니다. 이는 메시지 기록을 저장하는 SDK의 대화형 [`Session`](../sessions/index.md) 메모리와는 별개입니다. 메모리는 이전 실행에서 얻은 교훈을 sandbox 워크스페이스의 파일로 정리합니다. +메모리는 향후 sandbox-agent 실행이 이전 실행에서 학습할 수 있게 합니다. 이는 메시지 기록을 저장하는 SDK의 대화형 [`Session`](../sessions/index.md) 메모리와는 별개입니다. 메모리는 이전 실행에서 얻은 교훈을 샌드박스 워크스페이스의 파일로 정제합니다. !!! warning "베타 기능" - Sandbox 에이전트는 베타입니다. 일반 제공 이전에 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다. + 샌드박스 에이전트는 베타 버전입니다. API, 기본값, 지원 기능의 세부 사항은 정식 출시 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다. -메모리는 이후 실행에서 세 가지 종류의 비용을 줄일 수 있습니다. +메모리는 향후 실행에서 세 가지 비용을 줄일 수 있습니다. -1. 에이전트 비용: 에이전트가 워크플로를 완료하는 데 오랜 시간이 걸렸다면, 다음 실행에서는 탐색이 덜 필요해야 합니다. 이렇게 하면 토큰 사용량과 완료 시간을 줄일 수 있습니다. -2. 사용자 비용: 사용자가 에이전트를 수정했거나 선호 사항을 표현했다면, 이후 실행은 그 피드백을 기억할 수 있습니다. 이렇게 하면 사람의 개입을 줄일 수 있습니다. -3. 컨텍스트 비용: 에이전트가 이전에 작업을 완료했고 사용자가 그 작업을 이어서 진행하려는 경우, 사용자는 이전 스레드를 찾거나 모든 컨텍스트를 다시 입력할 필요가 없어야 합니다. 이렇게 하면 작업 설명이 더 짧아집니다. +1. 에이전트 비용: 에이전트가 워크플로를 완료하는 데 오랜 시간이 걸렸다면, 다음 실행에서는 탐색이 덜 필요해야 합니다. 이를 통해 토큰 사용량과 완료까지 걸리는 시간을 줄일 수 있습니다. +2. 사용자 비용: 사용자가 에이전트를 수정했거나 선호 사항을 표현했다면, 향후 실행에서 해당 피드백을 기억할 수 있습니다. 이를 통해 사람의 개입을 줄일 수 있습니다. +3. 컨텍스트 비용: 에이전트가 이전에 작업을 완료했고 사용자가 그 작업을 이어서 진행하려는 경우, 사용자가 이전 스레드를 찾거나 모든 컨텍스트를 다시 입력할 필요가 없어야 합니다. 이를 통해 작업 설명을 더 짧게 만들 수 있습니다. -버그를 수정하고, 메모리를 생성하고, 스냅샷을 재개하고, 후속 검증 실행에서 해당 메모리를 사용하는 완전한 2회 실행 예제는 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를 참조하세요. 별도의 메모리 레이아웃을 사용하는 멀티턴, 멀티 에이전트 예제는 [examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)를 참조하세요. +버그를 수정하고, 메모리를 생성하고, 스냅샷을 재개한 뒤, 후속 검증 실행에서 해당 메모리를 사용하는 완전한 2회 실행 예제는 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를 참고하세요. 별도의 메모리 레이아웃을 사용하는 멀티턴, 멀티 에이전트 예제는 [examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)를 참고하세요. ## 메모리 활성화 -sandbox 에이전트의 capability로 `Memory()`를 추가합니다. +샌드박스 에이전트에 기능으로 `Memory()`를 추가합니다. ```python from pathlib import Path @@ -42,28 +42,28 @@ with tempfile.TemporaryDirectory(prefix="sandbox-memory-example-") as snapshot_d ) ``` -읽기가 활성화되면 `Memory()`에는 `Shell()`이 필요하며, 이를 통해 주입된 요약만으로 충분하지 않을 때 에이전트가 메모리 파일을 읽고 검색할 수 있습니다. 라이브 메모리 업데이트가 활성화된 경우(기본값)에는 `Filesystem()`도 필요하며, 이를 통해 에이전트가 오래된 메모리를 발견했거나 사용자가 메모리 업데이트를 요청했을 때 `memories/MEMORY.md`를 업데이트할 수 있습니다. +읽기가 활성화된 경우 `Memory()`에는 `Shell()`이 필요합니다. 이는 주입된 요약만으로 충분하지 않을 때 에이전트가 메모리 파일을 읽고 검색할 수 있게 합니다. 라이브 메모리 업데이트가 활성화된 경우(기본값), `Filesystem()`도 필요합니다. 이는 에이전트가 오래된 메모리를 발견하거나 사용자가 메모리 업데이트를 요청할 때 `memories/MEMORY.md`를 업데이트할 수 있게 합니다. -기본적으로 메모리 아티팩트는 sandbox 워크스페이스의 `memories/` 아래에 저장됩니다. 이후 실행에서 이를 재사용하려면 동일한 라이브 sandbox 세션을 유지하거나, 영속화된 세션 상태 또는 스냅샷에서 재개하여 구성된 전체 memories 디렉터리를 보존하고 재사용해야 합니다. 새 빈 sandbox는 빈 메모리로 시작합니다. +기본적으로 메모리 아티팩트는 샌드박스 워크스페이스의 `memories/` 아래에 저장됩니다. 나중 실행에서 이를 재사용하려면 동일한 라이브 샌드박스 세션을 유지하거나, 영구 저장된 세션 상태 또는 스냅샷에서 재개하여 구성된 memories 디렉터리 전체를 보존하고 재사용하세요. 새 빈 샌드박스는 빈 메모리로 시작합니다. -`Memory()`는 메모리 읽기와 메모리 생성을 모두 활성화합니다. 메모리를 읽되 새 메모리는 생성하지 않아야 하는 에이전트에는 `Memory(generate=None)`를 사용하세요. 예를 들어, 내부 에이전트, 서브에이전트, 검사기, 또는 실행이 큰 신호를 추가하지 않는 일회성 도구 에이전트가 이에 해당합니다. 실행이 나중을 위해 메모리를 생성해야 하지만, 사용자가 기존 메모리의 영향을 받기를 원하지 않는 경우에는 `Memory(read=None)`를 사용하세요. +`Memory()`는 메모리 읽기와 생성을 모두 활성화합니다. 메모리를 읽어야 하지만 새 메모리를 생성해서는 안 되는 에이전트에는 `Memory(generate=None)`을 사용하세요. 예를 들어 내부 에이전트, 서브에이전트, 검사기, 또는 실행이 많은 신호를 추가하지 않는 일회성 도구 에이전트가 이에 해당합니다. 실행이 나중을 위한 메모리는 생성해야 하지만, 기존 메모리의 영향을 받는 것을 사용자가 원하지 않는 경우에는 `Memory(read=None)`을 사용하세요. ## 메모리 읽기 -메모리 읽기는 점진적 공개(progressive disclosure)를 사용합니다. 실행 시작 시 SDK는 일반적으로 유용한 팁, 사용자 선호 사항, 사용 가능한 메모리를 담은 작은 요약인 (`memory_summary.md`)을 에이전트의 개발자 프롬프트에 주입합니다. 이를 통해 에이전트는 이전 작업이 관련 있을 수 있는지 판단할 만큼 충분한 컨텍스트를 얻습니다. +메모리 읽기는 점진적 공개 방식을 사용합니다. 실행 시작 시 SDK는 일반적으로 유용한 팁, 사용자 선호 사항, 사용 가능한 메모리에 대한 작은 요약(`memory_summary.md`)을 에이전트의 개발자 프롬프트에 주입합니다. 이를 통해 에이전트는 이전 작업이 관련될 수 있는지 판단하기에 충분한 컨텍스트를 얻습니다. -이전 작업이 관련 있어 보이면, 에이전트는 현재 작업의 키워드로 구성된 메모리 인덱스(`memories_dir` 아래의 `MEMORY.md`)를 검색합니다. 더 자세한 정보가 필요한 경우에만 구성된 `rollout_summaries/` 디렉터리 아래의 해당 이전 rollout 요약을 엽니다. +이전 작업이 관련 있어 보이면, 에이전트는 현재 작업의 키워드로 구성된 메모리 인덱스(`memories_dir` 아래의 `MEMORY.md`)를 검색합니다. 작업에 더 자세한 정보가 필요할 때만 구성된 `rollout_summaries/` 디렉터리 아래의 해당 이전 롤아웃 요약을 엽니다. -메모리는 오래될 수 있습니다. 에이전트는 메모리를 오직 참고용으로만 취급하고 현재 환경을 신뢰하도록 지시받습니다. 기본적으로 메모리 읽기에는 `live_update`가 활성화되어 있으므로, 에이전트가 오래된 메모리를 발견하면 같은 실행에서 구성된 `MEMORY.md`를 업데이트할 수 있습니다. 예를 들어 실행이 지연 시간에 민감한 경우처럼, 에이전트가 메모리를 읽되 실행 중 수정해서는 안 되는 경우에는 라이브 업데이트를 비활성화하세요. +메모리는 오래될 수 있습니다. 에이전트는 메모리를 지침으로만 취급하고 현재 환경을 신뢰하도록 지시받습니다. 기본적으로 메모리 읽기에는 `live_update`가 활성화되어 있으므로, 에이전트가 오래된 메모리를 발견하면 동일한 실행에서 구성된 `MEMORY.md`를 업데이트할 수 있습니다. 에이전트가 메모리를 읽어야 하지만 실행 중에 수정해서는 안 되는 경우, 예를 들어 실행이 지연 시간에 민감한 경우에는 라이브 업데이트를 비활성화하세요. ## 메모리 생성 -실행이 끝나면 sandbox 런타임은 해당 실행 세그먼트를 대화 파일에 추가합니다. 누적된 대화 파일은 sandbox 세션이 닫힐 때 처리됩니다. +실행이 끝나면 샌드박스 런타임은 해당 실행 세그먼트를 대화 파일에 추가합니다. 누적된 대화 파일은 샌드박스 세션이 닫힐 때 처리됩니다. 메모리 생성에는 두 단계가 있습니다. -1. 1단계: 대화 추출. 메모리 생성 모델이 하나의 누적된 대화 파일을 처리하고 대화 요약을 생성합니다. 시스템, 개발자, 추론 콘텐츠는 제외됩니다. 대화가 너무 길면 컨텍스트 윈도에 맞도록 잘리며, 시작과 끝은 보존됩니다. 또한 2단계에서 통합할 수 있도록 대화의 간결한 메모인 원문 메모리 추출도 생성합니다. -2. 2단계: 레이아웃 통합. 통합 에이전트가 하나의 메모리 레이아웃에 대한 원문 메모리를 읽고, 더 많은 근거가 필요할 때 대화 요약을 열어 패턴을 `MEMORY.md`와 `memory_summary.md`로 추출합니다. +1. 1단계: 대화 추출. 메모리 생성 모델이 누적된 대화 파일 하나를 처리하고 대화 요약을 생성합니다. 시스템, 개발자, 추론 내용은 생략됩니다. 대화가 너무 길면 컨텍스트 창에 맞도록 잘리며, 시작과 끝은 보존됩니다. 또한 원문 메모리 추출도 생성합니다. 이는 2단계에서 통합할 수 있는 대화의 간결한 노트입니다. +2. 2단계: 레이아웃 통합. 통합 에이전트가 하나의 메모리 레이아웃에 대한 원문 메모리를 읽고, 더 많은 근거가 필요할 때 대화 요약을 연 다음, 패턴을 `MEMORY.md`와 `memory_summary.md`로 추출합니다. 기본 워크스페이스 레이아웃은 다음과 같습니다. @@ -97,13 +97,13 @@ memory = Memory( ) ``` -`extra_prompt`를 사용해 GTM 에이전트의 고객 및 회사 세부 정보처럼, 사용 사례에서 어떤 신호가 가장 중요한지 메모리 생성기에 알려주세요. +`extra_prompt`를 사용하여 메모리 생성기에 사용 사례에서 가장 중요한 신호를 알려줄 수 있습니다. 예를 들어 GTM 에이전트의 경우 고객 및 회사 세부 정보가 해당됩니다. -최근 원문 메모리가 `max_raw_memories_for_consolidation`(기본값 256)을 초과하면, 2단계는 가장 최신 대화의 메모리만 유지하고 오래된 것은 제거합니다. 최신성은 대화가 마지막으로 업데이트된 시간을 기준으로 합니다. 이 망각 메커니즘은 메모리가 가장 새로운 환경을 반영하도록 돕습니다. +최근 원문 메모리가 `max_raw_memories_for_consolidation`(기본값 256)을 초과하면, 2단계는 가장 최신 대화의 메모리만 유지하고 더 오래된 메모리는 제거합니다. 최신성은 대화가 마지막으로 업데이트된 시간을 기준으로 합니다. 이 망각 메커니즘은 메모리가 최신 환경을 반영하는 데 도움이 됩니다. ## 멀티턴 대화 -멀티턴 sandbox 채팅의 경우, 동일한 라이브 sandbox 세션과 함께 일반 SDK `Session`을 사용하세요. +멀티턴 샌드박스 채팅에는 일반 SDK `Session`을 동일한 라이브 샌드박스 세션과 함께 사용하세요. ```python from agents import Runner, SQLiteSession @@ -132,20 +132,20 @@ async with sandbox: ) ``` -두 실행은 동일한 SDK 대화 세션(`session=conversation_session`)을 전달하므로 하나의 메모리 대화 파일에 추가되며, 따라서 같은 `session.session_id`를 공유합니다. 이는 라이브 워크스페이스를 식별하지만 메모리 대화 ID로는 사용되지 않는 sandbox(`sandbox`)와는 다릅니다. 1단계는 sandbox 세션이 닫힐 때 누적된 대화를 확인하므로, 분리된 두 턴이 아니라 전체 교환에서 메모리를 추출할 수 있습니다. +두 실행은 동일한 SDK 대화 세션(`session=conversation_session`)을 전달하므로 같은 `session.session_id`를 공유하고, 따라서 하나의 메모리 대화 파일에 추가됩니다. 이는 라이브 워크스페이스를 식별하며 메모리 대화 ID로 사용되지 않는 샌드박스(`sandbox`)와 다릅니다. 1단계는 샌드박스 세션이 닫힐 때 누적된 대화를 보므로, 서로 분리된 두 턴이 아니라 전체 교환에서 메모리를 추출할 수 있습니다. -여러 `Runner.run(...)` 호출이 하나의 메모리 대화가 되도록 하려면, 해당 호출들에 걸쳐 안정적인 식별자를 전달하세요. 메모리가 실행을 대화와 연결할 때는 다음 순서로 이를 확인합니다. +여러 `Runner.run(...)` 호출이 하나의 메모리 대화가 되도록 하려면 해당 호출들에 안정적인 식별자를 전달하세요. 메모리가 실행을 대화와 연결할 때는 다음 순서로 확인합니다. -1. `Runner.run(...)`에 전달한 경우의 `conversation_id` -2. `SQLiteSession`과 같은 SDK `Session`을 전달한 경우의 `session.session_id` -3. 위 둘 다 없는 경우의 `RunConfig.group_id` -4. 안정적인 식별자가 없는 경우의 실행별 생성 ID +1. `Runner.run(...)`에 전달한 경우 `conversation_id` +2. `SQLiteSession` 같은 SDK `Session`을 전달한 경우 `session.session_id` +3. 위 둘 중 어느 것도 없을 경우 `RunConfig.group_id` +4. 안정적인 식별자가 없을 경우 생성된 실행별 ID -## 여러 에이전트의 메모리 분리를 위한 다른 레이아웃 사용 +## 서로 다른 에이전트의 메모리를 격리하기 위한 서로 다른 레이아웃 사용 -메모리 분리는 에이전트 이름이 아니라 `MemoryLayoutConfig`를 기준으로 합니다. 동일한 레이아웃과 동일한 메모리 대화 ID를 가진 에이전트는 하나의 메모리 대화와 하나의 통합 메모리를 공유합니다. 레이아웃이 다른 에이전트는 같은 sandbox 워크스페이스를 공유하더라도 별도의 rollout 파일, 원문 메모리, `MEMORY.md`, `memory_summary.md`를 유지합니다. +메모리 격리는 에이전트 이름이 아니라 `MemoryLayoutConfig`를 기준으로 합니다. 동일한 레이아웃과 동일한 메모리 대화 ID를 가진 에이전트는 하나의 메모리 대화와 하나의 통합된 메모리를 공유합니다. 서로 다른 레이아웃을 가진 에이전트는 동일한 샌드박스 워크스페이스를 공유하더라도 별도의 롤아웃 파일, 원문 메모리, `MEMORY.md`, `memory_summary.md`를 유지합니다. -여러 에이전트가 하나의 sandbox를 공유하지만 메모리를 공유해서는 안 되는 경우에는 별도의 레이아웃을 사용하세요. +여러 에이전트가 하나의 샌드박스를 공유하지만 메모리는 공유해서는 안 되는 경우 별도의 레이아웃을 사용하세요. ```python from agents import SQLiteSession @@ -186,4 +186,4 @@ gtm_session = SQLiteSession("gtm-q2-pipeline-review") engineering_session = SQLiteSession("eng-invoice-test-fix") ``` -이렇게 하면 GTM 분석이 엔지니어링 버그 수정 메모리에 통합되는 것을 방지하고, 그 반대도 방지할 수 있습니다. \ No newline at end of file +이렇게 하면 GTM 분석이 엔지니어링 버그 수정 메모리로 통합되거나 그 반대가 되는 일을 방지할 수 있습니다. \ No newline at end of file diff --git a/docs/ko/sandbox_agents.md b/docs/ko/sandbox_agents.md index 79875c221f..d818a76216 100644 --- a/docs/ko/sandbox_agents.md +++ b/docs/ko/sandbox_agents.md @@ -6,16 +6,16 @@ search: !!! warning "베타 기능" - 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다. + 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 공개 전까지 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다. -최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. Agents SDK의 **샌드박스 에이전트**는 모델에 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 저장된 샌드박스 상태에서 작업 재개를 수행할 수 있는 지속적인 워크스페이스를 제공합니다. +최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. Agents SDK의 **샌드박스 에이전트**는 모델에 영구 작업 공간을 제공하여 대규모 문서 집합을 검색하고, 파일을 편집하고, 명령을 실행하고, 아티팩트를 생성하고, 저장된 샌드박스 상태에서 작업을 다시 이어갈 수 있게 합니다. -SDK는 파일 스테이징, 파일 시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 제공자별 글루 코드를 직접 연결하지 않아도 이러한 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지한 다음, 워크스페이스용 `Manifest`, 샌드박스 네이티브 도구용 기능, 작업이 실행될 위치를 위한 `SandboxRunConfig`를 추가하면 됩니다. +SDK는 파일 스테이징, 파일 시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 공급자별 연결 코드를 직접 엮지 않아도 이러한 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지한 다음, 작업 공간을 위한 `Manifest`, 샌드박스 네이티브 도구를 위한 기능, 작업이 실행될 위치를 위한 `SandboxRunConfig`를 추가하면 됩니다. ## 사전 요구 사항 - Python 3.10 이상 -- OpenAI Agents SDK에 대한 기본 이해 +- OpenAI Agents SDK에 대한 기본적인 이해 - 샌드박스 클라이언트. 로컬 개발의 경우 `UnixLocalSandboxClient`로 시작하세요. ## 설치 @@ -34,7 +34,7 @@ pip install "openai-agents[docker]" ## 로컬 샌드박스 에이전트 생성 -이 예제는 `repo/` 아래에 로컬 저장소를 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위한 Unix 로컬 샌드박스 세션을 만들도록 합니다. +이 예제는 `repo/` 아래에 로컬 리포지토리를 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위한 Unix-local 샌드박스 세션을 만들 수 있게 합니다. ```python import asyncio @@ -94,24 +94,24 @@ if __name__ == "__main__": asyncio.run(main()) ``` -[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 저장소를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다. +[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 리포지토리를 사용하므로 Unix-local 실행 전반에서 결정적으로 검증할 수 있습니다. ## 주요 선택 사항 -기본 실행이 작동한 뒤 대부분의 사람이 다음으로 고려하는 선택 사항은 다음과 같습니다. +기본 실행이 작동한 후 대부분의 사용자가 다음으로 고려하는 선택지는 다음과 같습니다. -- `default_manifest`: 새 샌드박스 세션을 위한 파일, 저장소, 디렉터리, 마운트 +- `default_manifest`: 새 샌드박스 세션을 위한 파일, 리포지토리, 디렉터리, 마운트 - `instructions`: 프롬프트 전반에 적용되어야 하는 짧은 워크플로 규칙 -- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 이스케이프 해치 +- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 탈출구 - `capabilities`: 파일 시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축과 같은 샌드박스 네이티브 도구 -- `run_as`: 모델이 사용하는 도구의 샌드박스 사용자 ID +- `run_as`: 모델 대상 도구를 위한 샌드박스 사용자 ID - `SandboxRunConfig.client`: 샌드박스 백엔드 -- `SandboxRunConfig.session`, `session_state` 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결하는 방식 +- `SandboxRunConfig.session`, `session_state` 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결되는 방식 ## 다음 단계 -- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 구성 패턴을 이해합니다. -- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 제공자, 마운트 전략을 선택합니다. -- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행에서 얻은 교훈을 보존하고 재사용합니다. +- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 구성 패턴 이해 +- [샌드박스 클라이언트](sandbox/clients.md): Unix-local, Docker, 호스티드 공급자, 마운트 전략 선택 +- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행에서 얻은 교훈 보존 및 재사용 -셸 접근이 가끔 사용하는 도구 중 하나에 불과하다면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요. \ No newline at end of file +셸 접근이 가끔 사용하는 도구 중 하나일 뿐이라면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택 또는 샌드박스 세션 재개 동작이 설계의 일부일 때 샌드박스 에이전트를 선택하세요. \ No newline at end of file diff --git a/docs/ko/sessions/advanced_sqlite_session.md b/docs/ko/sessions/advanced_sqlite_session.md index 2c74710993..3ebe601d76 100644 --- a/docs/ko/sessions/advanced_sqlite_session.md +++ b/docs/ko/sessions/advanced_sqlite_session.md @@ -4,14 +4,14 @@ search: --- # 고급 SQLite 세션 -`AdvancedSQLiteSession`은 기본 `SQLiteSession`의 향상된 버전으로, 대화 브랜칭, 상세 사용량 분석, 구조화된 대화 쿼리를 포함한 고급 대화 관리 기능을 제공합니다 +`AdvancedSQLiteSession`은 기본 `SQLiteSession`의 향상된 버전으로, 대화 분기, 상세 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다. ## 기능 -- **대화 브랜칭**: 모든 사용자 메시지에서 대체 대화 경로 생성 +- **대화 분기**: 모든 사용자 메시지에서 대체 대화 경로를 생성 - **사용량 추적**: 전체 JSON 세부 내역과 함께 턴별 상세 토큰 사용량 분석 -- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등 조회 -- **브랜치 관리**: 독립적인 브랜치 전환 및 관리 +- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등을 조회 +- **분기 관리**: 독립적인 분기 전환 및 관리 - **메시지 구조 메타데이터**: 메시지 유형, 도구 사용, 대화 흐름 추적 ## 빠른 시작 @@ -85,13 +85,13 @@ session = AdvancedSQLiteSession( ### 매개변수 - `session_id` (str): 대화 세션의 고유 식별자 -- `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 기본값은 인메모리 저장을 위한 `:memory:` +- `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 인메모리 저장소의 경우 기본값은 `:memory:` - `create_tables` (bool): 고급 테이블을 자동으로 생성할지 여부. 기본값은 `False` - `logger` (logging.Logger | None): 세션용 사용자 지정 로거. 기본값은 모듈 로거 ## 사용량 추적 -AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드가 호출되는지에 전적으로 의존합니다.** +AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세한 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드가 호출되는지에 전적으로 의존합니다.** ### 사용량 데이터 저장 @@ -135,11 +135,11 @@ for turn_data in turn_usage: turn_2_usage = await session.get_turn_usage(user_turn_number=2) ``` -## 대화 브랜칭 +## 대화 분기 -AdvancedSQLiteSession의 핵심 기능 중 하나는 모든 사용자 메시지에서 대화 브랜치를 생성할 수 있다는 점이며, 이를 통해 대체 대화 경로를 탐색할 수 있습니다. +AdvancedSQLiteSession의 핵심 기능 중 하나는 모든 사용자 메시지에서 대화 분기를 생성하여 대체 대화 경로를 탐색할 수 있는 기능입니다. -### 브랜치 생성 +### 분기 생성 ```python # Get available turns for branching @@ -165,7 +165,7 @@ branch_id = await session.create_branch_from_content( ) ``` -### 브랜치 관리 +### 분기 관리 ```python # List all branches @@ -182,7 +182,7 @@ await session.switch_to_branch(branch_id) await session.delete_branch(branch_id, force=True) # force=True allows deleting current branch ``` -### 브랜치 워크플로 예제 +### 분기 워크플로 예제 ```python # Original conversation @@ -245,17 +245,17 @@ for turn in matching_turns: ### 메시지 구조 -세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다: +세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다. -- 메시지 유형(user, assistant, tool_call 등) +- 메시지 유형(사용자, 어시스턴트, tool_call 등) - 도구 호출의 도구 이름 - 턴 번호 및 시퀀스 번호 -- 브랜치 연결 +- 분기 연결 - 타임스탬프 ## 데이터베이스 스키마 -AdvancedSQLiteSession은 기본 SQLite 스키마를 두 개의 추가 테이블로 확장합니다: +AdvancedSQLiteSession은 두 개의 추가 테이블로 기본 SQLite 스키마를 확장합니다. ### message_structure 테이블 @@ -298,7 +298,7 @@ CREATE TABLE turn_usage ( ## 전체 예제 -모든 기능을 종합적으로 시연하는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요 +모든 기능을 종합적으로 보여 주는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요. ## API 참조 diff --git a/docs/ko/sessions/encrypted_session.md b/docs/ko/sessions/encrypted_session.md index 24d3eeb473..0ddfb914eb 100644 --- a/docs/ko/sessions/encrypted_session.md +++ b/docs/ko/sessions/encrypted_session.md @@ -4,18 +4,18 @@ search: --- # 암호화된 세션 -`EncryptedSession`은 모든 세션 구현에 대해 투명한 암호화를 제공하며, 오래된 항목의 자동 만료로 대화 데이터를 안전하게 보호합니다. +`EncryptedSession`은 모든 세션 구현에 투명한 암호화를 제공하여, 오래된 항목의 자동 만료와 함께 대화 데이터를 보호합니다. ## 기능 -- **투명한 암호화**: Fernet 암호화로 모든 세션을 래핑합니다 -- **세션별 키**: 세션마다 고유한 암호화를 위해 HKDF 키 파생을 사용합니다 -- **자동 만료**: TTL이 만료되면 오래된 항목을 자동으로 건너뜁니다 -- **즉시 교체 가능**: 기존의 모든 세션 구현과 함께 작동합니다 +- **투명한 암호화**: 모든 세션을 Fernet 암호화로 래핑합니다 +- **세션별 키**: HKDF 키 파생을 사용하여 세션마다 고유한 암호화를 적용합니다 +- **자동 만료**: TTL이 만료되면 오래된 항목을 조용히 건너뜁니다 +- **드롭인 대체**: 기존의 모든 세션 구현과 함께 작동합니다 ## 설치 -암호화된 세션을 사용하려면 `encrypt` extra가 필요합니다: +암호화된 세션에는 `encrypt` extra가 필요합니다: ```bash pip install openai-agents[encrypt] @@ -57,7 +57,7 @@ if __name__ == "__main__": ### 암호화 키 -암호화 키는 Fernet 키 또는 임의의 문자열이 될 수 있습니다: +암호화 키는 Fernet 키이거나 임의의 문자열일 수 있습니다: ```python from agents.extensions.memory import EncryptedSession @@ -79,9 +79,9 @@ session = EncryptedSession( ) ``` -### TTL (유효 기간) +### TTL(time to live) -암호화된 항목이 유효하게 유지되는 시간을 설정합니다: +암호화된 항목이 유효한 기간을 설정합니다: ```python # Items expire after 1 hour @@ -101,7 +101,7 @@ session = EncryptedSession( ) ``` -## 다양한 세션 유형과의 사용 +## 다양한 세션 유형과 함께 사용 ### SQLite 세션과 함께 사용 @@ -140,16 +140,16 @@ session = EncryptedSession( !!! warning "고급 세션 기능" - `AdvancedSQLiteSession` 같은 고급 세션 구현과 `EncryptedSession`을 함께 사용할 때는 다음을 유의하세요: + `EncryptedSession`을 `AdvancedSQLiteSession` 같은 고급 세션 구현과 함께 사용할 때는 다음 사항에 유의하세요: - - 메시지 콘텐츠가 암호화되므로 `find_turns_by_content()` 같은 메서드는 효과적으로 작동하지 않습니다 - - 콘텐츠 기반 검색은 암호화된 데이터에서 수행되므로 효과가 제한됩니다 + - `find_turns_by_content()` 같은 메서드는 메시지 콘텐츠가 암호화되어 있으므로 효과적으로 작동하지 않습니다 + - 콘텐츠 기반 검색은 암호화된 데이터에 대해 동작하므로 효과가 제한됩니다 ## 키 파생 -EncryptedSession은 세션별 고유 암호화 키를 파생하기 위해 HKDF(HMAC 기반 키 파생 함수)를 사용합니다: +EncryptedSession은 HKDF(HMAC-based Key Derivation Function)를 사용하여 세션별로 고유한 암호화 키를 파생합니다: - **마스터 키**: 제공한 암호화 키 - **세션 솔트**: 세션 ID @@ -157,9 +157,9 @@ EncryptedSession은 세션별 고유 암호화 키를 파생하기 위해 HKDF(H - **출력**: 32바이트 Fernet 키 이를 통해 다음이 보장됩니다: -- 각 세션은 고유한 암호화 키를 가집니다 +- 각 세션에는 고유한 암호화 키가 있습니다 - 마스터 키 없이는 키를 파생할 수 없습니다 -- 세션 데이터는 서로 다른 세션 간에 복호화할 수 없습니다 +- 서로 다른 세션 간에는 세션 데이터를 복호화할 수 없습니다 ## 자동 만료 @@ -175,5 +175,5 @@ result = await Runner.run(agent, "Continue conversation", session=session) ## API 참조 -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 주요 클래스 +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 기본 클래스 - [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜 \ No newline at end of file diff --git a/docs/ko/sessions/index.md b/docs/ko/sessions/index.md index abadb1a240..ebda1f02b7 100644 --- a/docs/ko/sessions/index.md +++ b/docs/ko/sessions/index.md @@ -4,11 +4,11 @@ search: --- # 세션 -Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요를 없애줍니다. +Agents SDK는 여러 에이전트 실행 간 대화 기록을 자동으로 유지하는 기본 제공 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요를 없애줍니다. -세션은 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 특히 에이전트가 이전 상호작용을 기억하길 원하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 유용합니다. +세션은 특정 세션의 대화 기록을 저장하므로, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있습니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다. -SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id`, `auto_previous_response_id`와 함께 사용할 수 없습니다. 대신 OpenAI 서버 관리형 이어가기를 원한다면, 세션을 그 위에 겹쳐 쓰지 말고 이러한 메커니즘 중 하나를 선택하세요. +SDK가 클라이언트 측 메모리를 관리해 주기를 원할 때 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id` 와 함께 사용할 수 없습니다. OpenAI 서버 관리형 이어가기를 원한다면 세션을 그 위에 겹쳐 사용하지 말고 해당 메커니즘 중 하나를 선택하세요. ## 빠른 시작 @@ -51,7 +51,7 @@ print(result.final_output) # "Approximately 39 million" ## 동일한 세션으로 인터럽트된 실행 재개 -승인을 위해 실행이 일시 중지되면, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 동일한 백킹 스토어를 가리키는 다른 세션 인스턴스)로 재개하세요. +승인을 위해 실행이 일시 중지되는 경우, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 같은 기반 저장소를 가리키는 다른 세션 인스턴스)로 재개하세요. ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -65,29 +65,29 @@ if result.interruptions: ## 핵심 세션 동작 -세션 메모리가 활성화되면: +세션 메모리가 활성화되면 다음과 같이 동작합니다. -1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 항목 앞에 추가합니다. +1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하여 입력 항목 앞에 추가합니다. 2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다. 3. **컨텍스트 보존**: 동일한 세션으로 이어지는 각 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다. -이를 통해 `.to_input_list()`를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다. +이를 통해 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다. ## 기록과 새 입력 병합 제어 -세션을 전달하면, 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다. +세션을 전달하면 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다. -1. 세션 기록(`session.get_items(...)`에서 가져옴) +1. 세션 기록(`session.get_items(...)` 에서 조회) 2. 새 턴 입력 -모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 콜백은 두 개의 목록을 받습니다. +모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 을 사용하세요. 콜백은 두 개의 목록을 받습니다. -- `history`: 가져온 세션 기록(이미 입력 항목 형식으로 정규화됨) +- `history`: 조회된 세션 기록(이미 입력 항목 형식으로 정규화됨) - `new_input`: 현재 턴의 새 입력 항목 모델에 전송할 최종 입력 항목 목록을 반환하세요. -콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 저장합니다. 따라서 오래된 기록을 재정렬하거나 필터링해도 오래된 세션 항목이 새 입력으로 다시 저장되지는 않습니다. +콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 지속 저장합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 이전 세션 항목이 새 입력으로 다시 저장되지는 않습니다. ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,16 +109,16 @@ result = await Runner.run( ) ``` -세션이 항목을 저장하는 방식을 바꾸지 않으면서 기록을 사용자 지정 가지치기, 재정렬 또는 선택적으로 포함해야 할 때 사용하세요. 모델 호출 직전에 한 번 더 최종 처리가 필요하다면 [running agents guide](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]를 사용하세요. +세션이 항목을 저장하는 방식은 바꾸지 않으면서 기록에 대한 사용자 지정 가지치기, 재정렬 또는 선택적 포함이 필요할 때 사용하세요. 모델 호출 직전에 더 늦은 최종 처리 단계가 필요하다면 [에이전트 실행 가이드](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] 를 사용하세요. -## 가져오는 기록 제한 +## 조회 기록 제한 -각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings]를 사용하세요. +각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요. -- `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목 가져오기 -- `SessionSettings(limit=N)`: 가장 최근 `N`개 항목만 가져오기 +- `SessionSettings(limit=None)` (기본값): 사용 가능한 모든 세션 항목 조회 +- `SessionSettings(limit=N)`: 가장 최근 `N` 개 항목만 조회 -[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 이를 적용할 수 있습니다. +[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 를 통해 실행별로 이를 적용할 수 있습니다. ```python from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작을 바꾸지 않고 가져오기 크기를 제한하고 싶을 때 유용합니다. +세션 구현이 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings` 는 해당 실행에 대해 `None` 이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작은 변경하지 않으면서 조회 크기를 제한하고 싶을 때 유용합니다. ## 메모리 작업 ### 기본 작업 -세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다. +세션은 대화 기록 관리를 위한 여러 작업을 지원합니다. ```python from agents import SQLiteSession @@ -167,7 +167,7 @@ await session.clear_session() ### 수정을 위한 pop_item 사용 -`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하려는 경우 특히 유용합니다. +`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하고 싶을 때 특히 유용합니다. ```python from agents import Agent, Runner, SQLiteSession @@ -196,34 +196,34 @@ result = await Runner.run( print(f"Agent: {result.final_output}") ``` -## 내장 세션 구현 +## 기본 제공 세션 구현 -SDK는 다양한 사용 사례에 맞는 여러 세션 구현을 제공합니다. +SDK는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다. -### 내장 세션 구현 선택 +### 기본 제공 세션 구현 선택 -아래의 상세 예제를 읽기 전에 이 표를 사용해 출발점을 선택하세요. +아래의 상세 예제를 읽기 전에 시작점을 고르는 데 이 표를 사용하세요. -| 세션 유형 | 적합한 경우 | 참고 | +| 세션 유형 | 적합한 용도 | 참고 | | --- | --- | --- | -| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 내장형, 경량, 파일 기반 또는 인메모리 | -| `AsyncSQLiteSession` | `aiosqlite`를 사용하는 비동기 SQLite | 비동기 드라이버 지원이 있는 확장 백엔드 | -| `RedisSession` | 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 | -| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스와 작동 | -| `MongoDBSession` | 이미 MongoDB를 사용하거나 멀티프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 | +| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 기본 제공, 경량, 파일 기반 또는 인메모리 | +| `AsyncSQLiteSession` | `aiosqlite` 기반 비동기 SQLite | 비동기 드라이버를 지원하는 확장 백엔드 | +| `RedisSession` | 여러 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 | +| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy가 지원하는 데이터베이스와 함께 동작 | +| `MongoDBSession` | 이미 MongoDB를 사용하거나 다중 프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 | | `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 저장소와 TTL 및 일관성 제어 지원 | | `OpenAIConversationsSession` | OpenAI의 서버 관리형 스토리지 | OpenAI Conversations API 기반 기록 | | `OpenAIResponsesCompactionSession` | 자동 압축이 필요한 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 | -| `AdvancedSQLiteSession` | SQLite와 브랜칭/분석 | 더 무거운 기능 세트; 전용 페이지 참조 | -| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼; 먼저 기반 백엔드 선택 | +| `AdvancedSQLiteSession` | SQLite와 분기/분석 | 더 많은 기능 세트; 전용 페이지 참조 | +| `EncryptedSession` | 다른 세션 위에 암호화 + TTL 적용 | 래퍼; 먼저 하위 백엔드 선택 | -일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 각 하위 섹션에 인라인으로 링크되어 있습니다. +일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 해당 하위 섹션에 링크되어 있습니다. -ChatKit용 파이썬 서버를 구현하는 경우 ChatKit의 스레드 및 항목 영속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 대체하는 드롭인 대체품은 아닙니다. [`ChatKit 데이터 스토어 구현에 대한 chatkit-python 가이드`](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요. +ChatKit용 Python 서버를 구현하는 경우, ChatKit의 스레드 및 항목 지속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 그대로 대체할 수 있는 것은 아닙니다. [`chatkit-python` 의 ChatKit 데이터 스토어 구현 가이드](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요. ### OpenAI Conversations API 세션 -`OpenAIConversationsSession`을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요. +`OpenAIConversationsSession` 을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요. ```python from agents import Agent, Runner, OpenAIConversationsSession @@ -259,7 +259,7 @@ print(result.final_output) # "California" ### OpenAI Responses 압축 세션 -Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession`을 사용하세요. 이는 기반 세션을 감싸며 `should_trigger_compaction`에 따라 각 턴 후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession`을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다. +Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession` 을 사용하세요. 이 세션은 하위 세션을 감싸며, `should_trigger_compaction` 에 따라 각 턴 이후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession` 을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다. #### 일반적인 사용법(자동 압축) @@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -기본적으로, 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다. +기본적으로 압축은 후보 임계값에 도달하면 각 턴 이후 실행됩니다. -`compaction_mode="previous_response_id"`는 Responses API 응답 ID로 이미 턴을 체이닝하고 있을 때 가장 잘 작동합니다. `compaction_mode="input"`은 대신 현재 세션 항목에서 압축 요청을 다시 구성하므로, 응답 체인을 사용할 수 없거나 세션 내용이 진실의 원천이 되길 원할 때 유용합니다. 기본값 `"auto"`는 사용 가능한 가장 안전한 옵션을 선택합니다. +`compaction_mode="previous_response_id"` 는 이미 Responses API 응답 ID로 턴을 체이닝하고 있을 때 가장 잘 동작합니다. `compaction_mode="input"` 은 대신 현재 세션 항목으로부터 압축 요청을 다시 구성합니다. 이는 응답 체인을 사용할 수 없거나 세션 내용을 신뢰할 수 있는 기준으로 삼고 싶을 때 유용합니다. 기본값인 `"auto"` 는 사용 가능한 가장 안전한 옵션을 선택합니다. -에이전트가 `ModelSettings(store=False)`로 실행되면 Responses API는 나중 조회를 위해 마지막 응답을 보관하지 않습니다. 이러한 무상태 설정에서는 기본 `"auto"` 모드가 `previous_response_id`에 의존하는 대신 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요. +에이전트가 `ModelSettings(store=False)` 로 실행되는 경우, Responses API는 나중에 조회할 수 있도록 마지막 응답을 보관하지 않습니다. 이 무상태 구성에서는 기본 `"auto"` 모드가 `previous_response_id` 에 의존하지 않고 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요. -#### 자동 압축과 스트리밍 차단 가능성 +#### 스트리밍을 차단할 수 있는 자동 압축 -압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행을 완료로 간주하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초 동안 열려 있을 수 있음을 의미합니다. +압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행이 완료된 것으로 간주하기 전에 압축이 끝나기를 기다립니다. 스트리밍 모드에서는 압축 작업이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열린 상태로 남아 있을 수 있습니다. -저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()`을 호출하세요. 자체 기준에 따라 언제 압축을 강제할지 결정할 수 있습니다. +저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()` 을 호출하세요. 자체 기준에 따라 언제 압축을 강제로 실행할지 결정할 수 있습니다. ```python from agents import Agent, Runner, SQLiteSession @@ -311,7 +311,7 @@ await session.run_compaction({"force": True}) ### SQLite 세션 -SQLite를 사용하는 기본 경량 세션 구현: +SQLite를 사용하는 기본 경량 세션 구현입니다. ```python from agents import SQLiteSession @@ -332,7 +332,7 @@ result = await Runner.run( ### 비동기 SQLite 세션 -`aiosqlite` 기반 SQLite 영속성이 필요할 때 `AsyncSQLiteSession`을 사용하세요. +`aiosqlite` 기반 SQLite 지속성이 필요할 때 `AsyncSQLiteSession` 을 사용하세요. ```bash pip install aiosqlite @@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis 세션 -여러 워커나 서비스 간 공유 세션 메모리에는 `RedisSession`을 사용하세요. +여러 워커 또는 서비스 간 공유 세션 메모리에는 `RedisSession` 을 사용하세요. ```bash pip install openai-agents[redis] @@ -369,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session) ### SQLAlchemy 세션 -SQLAlchemy가 지원하는 모든 데이터베이스를 사용한 프로덕션 준비 Agents SDK 세션 영속성: +SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션 환경에 적합한 Agents SDK 세션 지속성입니다. ```python from agents.extensions.memory import SQLAlchemySession @@ -391,7 +391,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ### Dapr 세션 -이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 다양한 상태 저장소 백엔드 간 이동할 수 있는 세션 스토리지가 필요할 때 `DaprSession`을 사용하세요. +이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 여러 상태 저장소 백엔드 간에 이동할 수 있는 세션 스토리지를 원할 때 `DaprSession` 을 사용하세요. ```bash pip install openai-agents[dapr] @@ -414,16 +414,16 @@ async with DaprSession.from_address( 참고: -- `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리한다면 `dapr_client=...`로 `DaprSession(...)`을 직접 생성하세요. -- 백킹 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...`을 전달하세요. -- 더 강한 쓰기 후 읽기 보장이 필요할 때는 `consistency=DAPR_CONSISTENCY_STRONG`을 전달하세요. -- Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address`에서 사용하는 gRPC 포트와 함께 `--dapr-http-port 3500`으로 Dapr를 시작하세요. -- 로컬 컴포넌트와 문제 해결을 포함한 전체 설정 절차는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요. +- `from_address(...)` 는 Dapr 클라이언트를 생성하고 수명 주기를 관리합니다. 앱에서 이미 Dapr 클라이언트를 관리하고 있다면 `dapr_client=...` 로 `DaprSession(...)` 을 직접 생성하세요. +- 기반 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...` 을 전달하세요. +- 더 강한 쓰기 후 읽기 보장이 필요하면 `consistency=DAPR_CONSISTENCY_STRONG` 을 전달하세요. +- Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address` 에서 사용하는 gRPC 포트뿐 아니라 `--dapr-http-port 3500` 도 함께 지정해 Dapr를 시작하세요. +- 로컬 컴포넌트와 문제 해결을 포함한 전체 설정 안내는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요. ### MongoDB 세션 -이미 MongoDB를 사용하거나 수평 확장 가능한 멀티프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession`을 사용하세요. +이미 MongoDB를 사용하거나 수평 확장이 가능한 다중 프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession` 을 사용하세요. ```bash pip install openai-agents[mongodb] @@ -448,14 +448,14 @@ await session.close() 참고: -- `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()`에서 이를 닫습니다. 애플리케이션에서 이미 클라이언트를 관리한다면 `client=...`로 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 하지 않으며 라이프사이클은 호출자에게 있습니다. -- 다른 변경 없이 `from_uri(...)`에 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요. -- 두 컬렉션이 사용되며 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`)과 `messages_collection=`(기본값 `agent_messages`)를 통해 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 동시 작성자와 프로세스 간 순서를 보존하는 단조 증가 `seq` 카운터가 포함됩니다. -- 첫 실행 전에 연결성을 확인하려면 `await session.ping()`을 사용하세요. +- `from_uri(...)` 는 `AsyncMongoClient` 를 생성하고 수명 주기를 관리하며, `session.close()` 시 닫습니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...` 로 `MongoDBSession(...)` 을 직접 생성하세요. 이 경우 `session.close()` 는 아무 작업도 하지 않으며 수명 주기는 호출자에게 남아 있습니다. +- 다른 변경 없이 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 `from_uri(...)` 에 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요. +- 두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=` (기본값 `agent_sessions`) 및 `messages_collection=` (기본값 `agent_messages`) 로 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서는 단조 증가하는 `seq` 카운터를 포함하여 동시 작성자와 프로세스 간 순서를 보존합니다. +- 첫 실행 전에 연결을 확인하려면 `await session.ping()` 을 사용하세요. ### 고급 SQLite 세션 -대화 브랜칭, 사용량 분석, structured queries를 갖춘 향상된 SQLite 세션: +대화 분기, 사용량 분석, 구조화된 쿼리를 지원하는 향상된 SQLite 세션입니다. ```python from agents.extensions.memory import AdvancedSQLiteSession @@ -479,7 +479,7 @@ await session.create_branch_from_turn(2) # Branch from turn 2 ### 암호화된 세션 -모든 세션 구현을 위한 투명한 암호화 래퍼: +모든 세션 구현을 위한 투명한 암호화 래퍼입니다. ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -506,7 +506,7 @@ result = await Runner.run(agent, "Hello", session=session) ### 기타 세션 유형 -몇 가지 내장 옵션이 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요. +기본 제공 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요. ## 운영 패턴 @@ -518,18 +518,18 @@ result = await Runner.run(agent, "Hello", session=session) - 스레드 기반: `"thread_abc123"` - 컨텍스트 기반: `"support_ticket_456"` -### 메모리 영속성 +### 메모리 지속성 - 임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용 -- 영속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 +- 지속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용 - `aiosqlite` 기반 구현이 필요할 때는 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`) 사용 - 공유 저지연 세션 메모리에는 Redis 기반 세션(`RedisSession.from_url("session_id", url="redis://...")`) 사용 - SQLAlchemy가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용 -- 이미 MongoDB를 사용하거나 멀티프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용 -- 내장 텔레메트리, 트레이싱 및 데이터 격리를 갖춘 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용 -- OpenAI Conversations API에 기록을 저장하는 것을 선호한다면 OpenAI 호스팅 스토리지(`OpenAIConversationsSession()`) 사용 -- 모든 세션을 투명한 암호화 및 TTL 기반 만료로 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 -- 더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django)에 대한 사용자 지정 세션 백엔드 구현 고려 +- 이미 MongoDB를 사용하거나 다중 프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용 +- 기본 제공 텔레메트리, 트레이싱, 데이터 격리와 함께 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용 +- OpenAI Conversations API에 기록을 저장하고 싶다면 OpenAI가 호스팅하는 스토리지(`OpenAIConversationsSession()`) 사용 +- 투명한 암호화와 TTL 기반 만료로 모든 세션을 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용 +- 더 고급 사용 사례에는 다른 프로덕션 시스템(예: Django)을 위한 사용자 지정 세션 백엔드 구현 고려 ### 여러 세션 @@ -577,7 +577,7 @@ result2 = await Runner.run( ## 전체 예제 -다음은 세션 메모리가 동작하는 모습을 보여주는 전체 예제입니다. +세션 메모리가 동작하는 방식을 보여주는 전체 예제입니다. ```python import asyncio @@ -692,7 +692,7 @@ result = await Runner.run( |---------|-------------| | [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 위한 Django ORM 기반 세션 | -세션 구현을 구축했다면 여기에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요! +세션 구현을 만들었다면 이곳에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요! ## API 참조 @@ -707,5 +707,5 @@ result = await Runner.run( - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현 - [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 기반 세션 구현 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭과 분석을 갖춘 향상된 SQLite +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기와 분석을 지원하는 향상된 SQLite - [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼 \ No newline at end of file diff --git a/docs/ko/sessions/sqlalchemy_session.md b/docs/ko/sessions/sqlalchemy_session.md index 9c91cbf026..28e1098ac0 100644 --- a/docs/ko/sessions/sqlalchemy_session.md +++ b/docs/ko/sessions/sqlalchemy_session.md @@ -4,11 +4,11 @@ search: --- # SQLAlchemy 세션 -`SQLAlchemySession`은 SQLAlchemy를 사용하여 프로덕션 준비가 된 세션 구현을 제공하며, 세션 저장소에 SQLAlchemy가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 사용할 수 있게 해줍니다 +`SQLAlchemySession`은 SQLAlchemy를 사용해 프로덕션 환경에서 사용할 수 있는 세션 구현을 제공하며, 세션 저장소로 SQLAlchemy가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 사용할 수 있습니다. ## 설치 -SQLAlchemy 세션에는 `sqlalchemy` extra가 필요합니다: +SQLAlchemy 세션에는 `sqlalchemy` extra가 필요합니다. ```bash pip install openai-agents[sqlalchemy] @@ -18,7 +18,7 @@ pip install openai-agents[sqlalchemy] ### 데이터베이스 URL 사용 -시작하는 가장 간단한 방법입니다: +가장 간단하게 시작하는 방법입니다. ```python import asyncio @@ -76,5 +76,5 @@ if __name__ == "__main__": ## API 참조 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 메인 클래스 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 주요 클래스 - [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜 \ No newline at end of file diff --git a/docs/ko/streaming.md b/docs/ko/streaming.md index 5ed07259df..063d0e5391 100644 --- a/docs/ko/streaming.md +++ b/docs/ko/streaming.md @@ -4,17 +4,17 @@ 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] 객체의 비동기 스트림을 얻을 수 있습니다. -비동기 이터레이터가 끝날 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 종료될 때까지 완료된 것이 아니며, 세션 영속화, 승인 장부 처리, 히스토리 압축 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 끝날 수 있습니다. 루프가 종료되면 `result.is_complete`가 최종 실행 상태를 반영합니다. +비동기 이터레이터가 종료될 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 끝나기 전까지 완료되지 않으며, 세션 영속화, 승인 기록 관리, 히스토리 압축과 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 완료될 수 있습니다. 루프가 종료되면 `result.is_complete`는 최종 실행 상태를 반영합니다. -## 원시 응답 이벤트 +## 원문 응답 이벤트 -[`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` 등과 같은 타입과 데이터가 있습니다. 이러한 이벤트는 응답 메시지가 생성되는 즉시 사용자에게 스트리밍하려는 경우 유용합니다. -컴퓨터 도구 원시 이벤트는 저장된 결과와 동일한 프리뷰-vs-GA 구분을 유지합니다. 프리뷰 플로는 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하는 반면, `gpt-5.5`는 일괄 처리된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 더 높은 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면은 이를 위해 컴퓨터 전용 특별 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 노출되며, 스크린샷 결과는 `computer_call_output` 항목을 감싼 `tool_output`으로 반환됩니다. +컴퓨터 도구 원문 이벤트는 저장된 결과와 동일하게 preview-vs-GA 구분을 유지합니다. Preview 흐름은 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하는 반면, `gpt-5.5`는 배치된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 상위 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면은 이를 위해 컴퓨터 전용의 특별한 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 표면화되며, 스크린샷 결과는 `computer_call_output` 항목을 래핑한 `tool_output`으로 반환됩니다. 예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다. @@ -39,9 +39,9 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 스트리밍과 승인 +## 스트리밍 및 승인 -스트리밍은 도구 승인을 위해 일시 중지되는 실행과 호환됩니다. 도구에 승인이 필요한 경우 `result.stream_events()`가 종료되고 보류 중인 승인은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`로 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인하거나 거부한 다음 `Runner.run_streamed(...)`로 재개하세요. +스트리밍은 도구 승인을 위해 일시 중지되는 실행과 호환됩니다. 도구에 승인이 필요한 경우 `result.stream_events()`가 종료되고 대기 중인 승인은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`를 사용해 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인하거나 거부한 다음 `Runner.run_streamed(...)`로 재개하세요. ```python result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.") @@ -57,21 +57,21 @@ if result.interruptions: pass ``` -전체 일시 중지/재개 절차는 [휴먼인더루프 가이드](human_in_the_loop.md)를 참조하세요. +전체 일시 중지/재개 과정을 보려면 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요. ## 현재 턴 이후 스트리밍 취소 -스트리밍 실행을 중간에 중지해야 하는 경우 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로 이는 실행을 즉시 중지합니다. 중지하기 전에 현재 턴이 깔끔하게 완료되도록 하려면 대신 `result.cancel(mode="after_turn")`을 호출하세요. +스트리밍 실행을 중간에 중지해야 하는 경우 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로 이는 실행을 즉시 중지합니다. 중지하기 전에 현재 턴이 깔끔하게 끝나도록 하려면 대신 `result.cancel(mode="after_turn")`을 호출하세요. -스트리밍된 실행은 `result.stream_events()`가 끝날 때까지 완료되지 않습니다. 마지막으로 보이는 토큰 이후에도 SDK가 세션 항목을 영속화하거나, 승인 상태를 마무리하거나, 히스토리를 압축하고 있을 수 있습니다. +스트리밍된 실행은 `result.stream_events()`가 종료되기 전까지 완료되지 않습니다. 마지막으로 보이는 토큰 이후에도 SDK가 여전히 세션 항목을 영속화하거나, 승인 상태를 최종화하거나, 히스토리를 압축하고 있을 수 있습니다. -[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 계속 진행하고 있으며 `cancel(mode="after_turn")`이 도구 턴 이후 중지되는 경우, 즉시 새 사용자 턴을 추가하는 대신 해당 정규화된 입력으로 `result.last_agent`를 다시 실행하여 완료되지 않은 턴을 계속하세요. -- 스트리밍 실행이 도구 승인 때문에 중지된 경우, 이를 새 턴으로 취급하지 마세요. 스트림을 끝까지 소진하고 `result.interruptions`를 검사한 다음 `result.to_state()`에서 재개하세요. -- 다음 모델 호출 전에 가져온 세션 히스토리와 새 사용자 입력을 병합하는 방식을 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 그곳에서 새 턴 항목을 다시 작성하면, 다시 작성된 버전이 해당 턴에 대해 영속화됩니다. +[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 계속 진행하고 있고, `cancel(mode="after_turn")`가 도구 턴 이후에 중지되는 경우, 즉시 새 사용자 턴을 추가하는 대신 해당 정규화된 입력으로 `result.last_agent`를 다시 실행하여 완료되지 않은 턴을 계속 진행하세요. +- 스트리밍된 실행이 도구 승인 때문에 중지된 경우 이를 새 턴으로 취급하지 마세요. 스트림 소비를 완료하고, `result.interruptions`를 검사한 뒤, `result.to_state()`에서 재개하세요. +- 다음 모델 호출 전에 가져온 세션 히스토리와 새 사용자 입력이 병합되는 방식을 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 여기에서 새 턴 항목을 다시 작성하면, 다시 작성된 버전이 해당 턴에 대해 영속화됩니다. ## 실행 항목 이벤트 및 에이전트 이벤트 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰이 아니라 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황 업데이트를 푸시할 수 있습니다. 마찬가지로 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과) 업데이트를 제공합니다. +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰 대신 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황 업데이트를 푸시할 수 있습니다. 마찬가지로 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과) 업데이트를 제공합니다. ### 실행 항목 이벤트 이름 @@ -89,11 +89,11 @@ if result.interruptions: - `mcp_approval_response` - `mcp_list_tools` -`handoff_occured`는 하위 호환성을 위해 의도적으로 철자가 잘못되어 있습니다. +`handoff_occured`는 이전 버전과의 호환성을 위해 의도적으로 철자가 틀리게 작성되었습니다. -호스티드 툴 검색을 사용할 때는 모델이 도구 검색 요청을 발행하면 `tool_search_called`가 내보내지고, Responses API가 로드된 하위 집합을 반환하면 `tool_search_output_created`가 내보내집니다. +호스티드 툴 검색을 사용하면 모델이 도구 검색 요청을 발행할 때 `tool_search_called`가 발생하고, Responses API가 로드된 하위 집합을 반환할 때 `tool_search_output_created`가 발생합니다. -예를 들어, 다음은 원시 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. +예를 들어, 다음은 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다. ```python import asyncio diff --git a/docs/ko/tools.md b/docs/ko/tools.md index 41ff1af3fb..9366a2139a 100644 --- a/docs/ko/tools.md +++ b/docs/ko/tools.md @@ -4,37 +4,37 @@ search: --- # 도구 -도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용과 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다. +도구를 통해 에이전트는 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다. - 호스티드 OpenAI 도구: OpenAI 서버에서 모델과 함께 실행됩니다. -- 로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다. -- Function Calling: 모든 Python 함수를 도구로 래핑합니다. +- 로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다. +- 함수 호출: 모든 Python 함수를 도구로 래핑합니다. - Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다. -- 실험적: Codex 도구: 도구 호출에서 워크스페이스 범위의 Codex 작업을 실행합니다. +- 실험적 기능: Codex 도구: 도구 호출에서 워크스페이스 범위 Codex 작업을 실행합니다. ## 도구 유형 선택 -이 페이지를 카탈로그로 사용한 다음, 제어하는 런타임에 맞는 섹션으로 이동하세요. +이 페이지를 카탈로그로 활용한 다음, 제어하는 런타임에 맞는 섹션으로 이동하세요. -| 원하는 작업 | 시작 위치 | +| 원하는 작업... | 여기에서 시작 | | --- | --- | -| OpenAI가 관리하는 도구 사용(웹 검색, 파일 검색, code interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 도구](#hosted-tools) | -| 도구 검색으로 큰 도구 표면을 런타임까지 지연 | [호스티드 도구 검색](#hosted-tool-search) | +| OpenAI 관리형 도구 사용(웹 검색, 파일 검색, code interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 툴](#hosted-tools) | +| 도구 검색으로 대규모 도구 노출을 런타임까지 지연 | [호스티드 툴 검색](#hosted-tool-search) | | 자체 프로세스 또는 환경에서 도구 실행 | [로컬 런타임 도구](#local-runtime-tools) | | Python 함수를 도구로 래핑 | [함수 도구](#function-tools) | -| 한 에이전트가 핸드오프 없이 다른 에이전트를 호출하도록 허용 | [Agents as tools](#agents-as-tools) | -| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적: Codex 도구](#experimental-codex-tool) | +| 핸드오프 없이 한 에이전트가 다른 에이전트를 호출하게 하기 | [Agents as tools](#agents-as-tools) | +| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적 기능: Codex 도구](#experimental-codex-tool) | -## 호스티드 도구 +## 호스티드 툴 -OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]을 사용할 때 몇 가지 기본 제공 도구를 제공합니다. +OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]을 사용할 때 몇 가지 내장 도구를 제공합니다. -- [`WebSearchTool`][agents.tool.WebSearchTool]을 사용하면 에이전트가 웹을 검색할 수 있습니다. +- [`WebSearchTool`][agents.tool.WebSearchTool]은 에이전트가 웹을 검색할 수 있게 합니다. - [`FileSearchTool`][agents.tool.FileSearchTool]은 OpenAI 벡터 스토어에서 정보를 검색할 수 있게 합니다. - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]은 LLM이 샌드박스 환경에서 코드를 실행할 수 있게 합니다. - [`HostedMCPTool`][agents.tool.HostedMCPTool]은 원격 MCP 서버의 도구를 모델에 노출합니다. - [`ImageGenerationTool`][agents.tool.ImageGenerationTool]은 프롬프트에서 이미지를 생성합니다. -- [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 필요할 때 지연된 도구, 네임스페이스 또는 호스티드 MCP 서버를 로드할 수 있게 합니다. +- [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 지연 로딩 도구, 네임스페이스 또는 호스티드 MCP 서버를 필요할 때 로드할 수 있게 합니다. 고급 호스티드 검색 옵션: @@ -60,11 +60,11 @@ async def main(): print(result.final_output) ``` -### 호스티드 도구 검색 +### 호스티드 툴 검색 -도구 검색을 사용하면 OpenAI Responses 모델이 큰 도구 표면을 런타임까지 지연시켜, 모델이 현재 턴에 필요한 하위 집합만 로드할 수 있습니다. 이는 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 미리 노출하지 않으면서 도구 스키마 토큰을 줄이고 싶을 때 유용합니다. +도구 검색을 사용하면 OpenAI Responses 모델이 대규모 도구 노출을 런타임까지 지연할 수 있어, 모델은 현재 턴에 필요한 하위 집합만 로드합니다. 많은 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 있으며 모든 도구를 미리 노출하지 않고 도구 스키마 토큰을 줄이고 싶을 때 유용합니다. -후보 도구를 에이전트를 빌드할 때 이미 알고 있다면 호스티드 도구 검색부터 시작하세요. 애플리케이션이 무엇을 로드할지 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동 실행하지 않습니다. +후보 도구가 에이전트를 빌드할 때 이미 알려져 있다면 호스티드 툴 검색부터 시작하세요. 애플리케이션이 무엇을 로드할지 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동으로 실행하지 않습니다. ```python from typing import Annotated @@ -108,24 +108,24 @@ print(result.final_output) 알아둘 사항: -- 호스티드 도구 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다. -- 에이전트에서 지연 로딩 표면을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요. -- 검색 가능한 표면에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다. -- 지연 로딩 함수 도구는 반드시 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스만 사용하는 구성에서도 모델이 필요할 때 적절한 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다. -- `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름과 설명 아래에 그룹화합니다. 이는 보통 `crm`, `billing`, `shipping`처럼 관련 도구가 많을 때 가장 적합합니다. -- OpenAI의 공식 모범 사례 가이드는 [가능한 경우 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다. -- 가능하면 개별적으로 지연된 많은 함수보다 네임스페이스나 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 상위 수준 검색 표면과 더 나은 토큰 절감을 제공합니다. -- 네임스페이스는 즉시 사용 가능한 도구와 지연된 도구를 함께 포함할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능한 상태로 유지되며, 같은 네임스페이스의 지연된 도구는 도구 검색을 통해 로드됩니다. -- 경험상 각 네임스페이스는 비교적 작게 유지하되, 이상적으로는 함수 10개 미만으로 유지하세요. -- 이름이 지정된 `tool_choice`는 단독 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없습니다. `auto`, `required` 또는 실제 최상위 호출 가능 도구 이름을 선호하세요. -- `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 이를 실행하는 대신 예외를 발생시킵니다. -- 도구 검색 활동은 전용 항목 및 이벤트 유형과 함께 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에 나타납니다. -- 네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 완전한 실행 가능 예제는 `examples/tools/tool_search.py`를 참조하세요. +- 호스티드 툴 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다. +- 에이전트에 지연 로딩 대상을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요. +- 검색 가능한 대상에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다. +- 지연 로딩 함수 도구는 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스만 사용하는 설정도 모델이 필요할 때 적절한 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다. +- `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름 및 설명 아래에 그룹화합니다. `crm`, `billing`, `shipping`처럼 관련 도구가 많은 경우 일반적으로 가장 적합합니다. +- OpenAI의 공식 모범 사례 가이드는 [가능하면 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다. +- 가능하면 개별적으로 지연된 함수 다수보다 네임스페이스 또는 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 상위 수준 검색 대상과 더 나은 토큰 절감을 제공합니다. +- 네임스페이스는 즉시 사용 가능한 도구와 지연 도구를 혼합할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능한 상태로 유지되고, 같은 네임스페이스의 지연 도구는 도구 검색을 통해 로드됩니다. +- 경험칙으로 각 네임스페이스는 비교적 작게 유지하세요. 이상적으로는 함수 10개 미만이 좋습니다. +- 이름이 지정된 `tool_choice`는 네임스페이스 이름만 있는 대상이나 지연 전용 도구를 대상으로 지정할 수 없습니다. `auto`, `required` 또는 실제 최상위 호출 가능 도구 이름을 선호하세요. +- `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 이를 실행하지 않고 예외를 발생시킵니다. +- 도구 검색 활동은 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에 전용 항목 및 이벤트 유형으로 나타납니다. +- 네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 전체 실행 가능한 예제는 `examples/tools/tool_search.py`를 참조하세요. - 공식 플랫폼 가이드: [도구 검색](https://developers.openai.com/api/docs/guides/tools-tool-search) ### 호스티드 컨테이너 셸 + 스킬 -`ShellTool`은 OpenAI 호스티드 컨테이너 실행도 지원합니다. 모델이 로컬 런타임 대신 관리형 컨테이너에서 셸 명령을 실행하도록 하려면 이 모드를 사용하세요. +`ShellTool`은 OpenAI 호스팅 컨테이너 실행도 지원합니다. 모델이 로컬 런타임 대신 관리형 컨테이너에서 셸 명령을 실행하게 하려면 이 모드를 사용하세요. ```python from agents import Agent, Runner, ShellTool, ShellToolSkillReference @@ -163,47 +163,47 @@ print(result.final_output) 알아둘 사항: - 호스티드 셸은 Responses API 셸 도구를 통해 사용할 수 있습니다. -- `container_auto`는 요청에 대한 컨테이너를 프로비저닝하며, `container_reference`는 기존 컨테이너를 재사용합니다. -- `container_auto`는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다. -- `environment.skills`는 스킬 참조와 인라인 스킬 번들을 허용합니다. -- 호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval` 또는 `on_approval`을 설정하지 마세요. +- `container_auto`는 요청을 위한 컨테이너를 프로비저닝하고, `container_reference`는 기존 컨테이너를 재사용합니다. +- `container_auto`에는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다. +- `environment.skills`는 스킬 참조와 인라인 스킬 번들을 받습니다. +- 호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval`, `on_approval`을 설정하지 마세요. - `network_policy`는 `disabled` 및 `allowlist` 모드를 지원합니다. -- 허용 목록 모드에서 `network_policy.domain_secrets`는 이름으로 도메인 범위의 시크릿을 주입할 수 있습니다. -- 완전한 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요. +- allowlist 모드에서는 `network_policy.domain_secrets`가 이름으로 도메인 범위 시크릿을 주입할 수 있습니다. +- 전체 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요. - OpenAI 플랫폼 가이드: [Shell](https://platform.openai.com/docs/guides/tools-shell) 및 [Skills](https://platform.openai.com/docs/guides/tools-skills) ## 로컬 런타임 도구 -로컬 런타임 도구는 모델 응답 자체 외부에서 실행됩니다. 모델은 여전히 언제 호출할지 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다. +로컬 런타임 도구는 모델 응답 자체의 외부에서 실행됩니다. 모델은 여전히 언제 호출할지 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다. -`ComputerTool` 및 `ApplyPatchTool`에는 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 포괄합니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을 사용하고, 명령이 자체 프로세스에서 실행되기를 원하면 아래 로컬 런타임 구성을 사용하세요. +`ComputerTool` 및 `ApplyPatchTool`은 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드 모두에 걸쳐 있습니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을 사용하고, 명령이 자체 프로세스에서 실행되도록 하려면 아래의 로컬 런타임 구성을 사용하세요. 로컬 런타임 도구에는 구현을 제공해야 합니다. - [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 활성화하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현하세요. -- [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행 모두를 위한 최신 셸 도구입니다. +- [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행을 모두 지원하는 최신 셸 도구입니다. - [`LocalShellTool`][agents.tool.LocalShellTool]: 레거시 로컬 셸 통합입니다. -- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: 로컬에서 diff를 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요. +- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: diff를 로컬에 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요. - 로컬 셸 스킬은 `ShellTool(environment={"type": "local", "skills": [...]})`와 함께 사용할 수 있습니다. ### ComputerTool 및 Responses 컴퓨터 도구 `ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면, SDK가 해당 하네스를 OpenAI Responses API 컴퓨터 표면에 매핑합니다. -명시적 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA 기본 제공 도구 페이로드 `{"type": "computer"}`를 보냅니다. 더 오래된 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다. +명시적 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA(정식 출시) 내장 도구 페이로드 `{"type": "computer"}`를 전송합니다. 이전 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다. - 모델: `computer-use-preview` -> `gpt-5.5` -- 도구 선택기: `computer_use_preview` -> `computer` -- 컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 일괄 처리된 `actions[]` +- 도구 선택자: `computer_use_preview` -> `computer` +- 컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 배치된 `actions[]` - 잘림: 프리뷰 경로에서는 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 필요하지 않음 -SDK는 실제 Responses 요청의 유효 모델에서 해당 wire 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하고 있어 요청에서 `model`을 생략하는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다. +SDK는 실제 Responses 요청의 유효 모델을 기반으로 해당 전송 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하기 때문에 요청에서 `model`이 생략되는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다. -[`ComputerTool`][agents.tool.ComputerTool]이 있을 때는 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. `ComputerTool`이 없으면 이 문자열들은 여전히 일반 함수 이름처럼 동작합니다. +[`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 내장 선택자로 정규화됩니다. `ComputerTool`이 없으면 이러한 문자열은 여전히 일반 함수 이름처럼 동작합니다. -이 차이는 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리로 뒷받침될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기가 필요하지 않으므로, 해결되지 않은 팩토리도 괜찮습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 보낼 수 있도록 여전히 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 필요합니다. +이 차이는 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리로 지원될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기 정보가 필요하지 않으므로 해결되지 않은 팩토리도 괜찮습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 전송할 수 있도록 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 여전히 필요합니다. -런타임에는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 있는 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 일괄 처리된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요. +런타임에는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 포함된 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 배치된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요. ```python from agents import Agent, ApplyPatchTool, ShellTool @@ -249,14 +249,14 @@ agent = Agent( 모든 Python 함수를 도구로 사용할 수 있습니다. Agents SDK가 도구를 자동으로 설정합니다. -- 도구 이름은 Python 함수의 이름이 됩니다(또는 이름을 제공할 수 있습니다) +- 도구 이름은 Python 함수 이름이 됩니다(또는 이름을 제공할 수 있습니다) - 도구 설명은 함수의 docstring에서 가져옵니다(또는 설명을 제공할 수 있습니다) - 함수 입력의 스키마는 함수의 인수에서 자동으로 생성됩니다 -- 비활성화하지 않는 한 각 입력에 대한 설명은 함수의 docstring에서 가져옵니다 +- 각 입력의 설명은 비활성화하지 않는 한 함수의 docstring에서 가져옵니다 -함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring을 파싱하기 위해 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성을 위해 `pydantic`을 사용합니다. +함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성에는 `pydantic`을 사용합니다. -OpenAI Responses 모델을 사용할 때 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. 관련 함수 도구를 [`tool_namespace()`][agents.tool.tool_namespace]로 그룹화할 수도 있습니다. 전체 설정과 제약 사항은 [호스티드 도구 검색](#hosted-tool-search)을 참조하세요. +OpenAI Responses 모델을 사용하는 경우 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. [`tool_namespace()`][agents.tool.tool_namespace]로 관련 함수 도구를 그룹화할 수도 있습니다. 전체 설정과 제약은 [호스티드 툴 검색](#hosted-tool-search)을 참조하세요. ```python import json @@ -308,9 +308,9 @@ for tool in agent.tools: ``` -1. 함수 인수로 모든 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다. -2. Docstring이 있으면 설명과 인수 설명을 캡처하는 데 사용됩니다 -3. 함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 함). 도구 이름, 설명, 사용할 docstring 스타일 등과 같은 재정의도 설정할 수 있습니다. +1. 함수 인수에는 모든 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다. +2. docstring이 있으면 설명과 인수 설명을 캡처하는 데 사용됩니다. +3. 함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 합니다). 도구 이름, 설명, 사용할 docstring 스타일 등과 같은 재정의도 설정할 수 있습니다. 4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다. ??? note "출력을 보려면 펼치기" @@ -383,22 +383,22 @@ for tool in agent.tools: } ``` -### 함수 도구에서 이미지 또는 파일 반환 +### 함수 도구의 이미지 또는 파일 반환 텍스트 출력 반환 외에도 함수 도구의 출력으로 하나 이상의 이미지 또는 파일을 반환할 수 있습니다. 이를 위해 다음 중 하나를 반환할 수 있습니다. -- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) -- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) -- 텍스트: 문자열 또는 문자열화 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText] (또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) +- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage](또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]) +- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent](또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]) +- 텍스트: 문자열 또는 문자열로 변환 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText](또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]) ### 사용자 지정 함수 도구 -때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool]을 직접 만들 수 있습니다. 다음을 제공해야 합니다. +때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원하는 경우 [`FunctionTool`][agents.tool.FunctionTool]을 직접 생성할 수 있습니다. 다음을 제공해야 합니다. - `name` - `description` - `params_json_schema`: 인수에 대한 JSON 스키마 -- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 인수를 JSON 문자열로 받고 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 async 함수 +- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 JSON 문자열 형태의 인수를 받아 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 비동기 함수 ```python from typing import Any @@ -433,16 +433,16 @@ tool = FunctionTool( ### 자동 인수 및 docstring 파싱 -앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 이에 대한 몇 가지 참고 사항은 다음과 같습니다. +앞서 언급했듯이 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 관련 참고 사항은 다음과 같습니다. -1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 어노테이션을 사용하여 인수의 타입을 이해하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다. -2. `griffe`를 사용하여 docstring을 파싱합니다. 지원되는 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`][]에 있습니다. -### Pydantic Field로 인수 제한 및 설명 +### Pydantic Field를 사용한 인수 제약 및 설명 -Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용하여 도구 인수에 제약(예: 숫자의 최소/최대, 문자열의 길이 또는 패턴)과 설명을 추가할 수 있습니다. Pydantic에서처럼 두 형식이 모두 지원됩니다. 기본값 기반(`arg: int = Field(..., ge=1)`) 및 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`). 생성된 JSON 스키마와 유효성 검사에는 이러한 제약이 포함됩니다. +Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용하여 도구 인수에 제약(예: 숫자의 최솟값/최댓값, 문자열 길이 또는 패턴)과 설명을 추가할 수 있습니다. Pydantic과 마찬가지로 두 형식 모두 지원됩니다. 기본값 기반(`arg: int = Field(..., ge=1)`)과 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`)입니다. 생성된 JSON 스키마와 검증에는 이러한 제약이 포함됩니다. ```python from typing import Annotated @@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr ### 함수 도구 타임아웃 -`@function_tool(timeout=...)`으로 async 함수 도구에 호출별 타임아웃을 설정할 수 있습니다. +`@function_tool(timeout=...)`으로 비동기 함수 도구의 호출별 타임아웃을 설정할 수 있습니다. ```python import asyncio @@ -482,11 +482,11 @@ agent = Agent( ) ``` -타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델이 볼 수 있는 타임아웃 메시지(예: `Tool 'slow_lookup' timed out after 2 seconds.`)를 보냅니다. +타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델에서 볼 수 있는 타임아웃 메시지(예: `Tool 'slow_lookup' timed out after 2 seconds.`)를 보냅니다. 타임아웃 처리를 제어할 수 있습니다. -- `timeout_behavior="error_as_result"` (기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 반환합니다. +- `timeout_behavior="error_as_result"`(기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 모델에 반환합니다. - `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]를 발생시키고 실행을 실패시킵니다. - `timeout_error_function=...`: `error_as_result`를 사용할 때 타임아웃 메시지를 사용자 지정합니다. @@ -511,15 +511,15 @@ except ToolTimeoutError as e: !!! note - 타임아웃 구성은 async `@function_tool` 핸들러에만 지원됩니다. + 타임아웃 구성은 비동기 `@function_tool` 핸들러에만 지원됩니다. -### 함수 도구의 오류 처리 +### 함수 도구 오류 처리 -`@function_tool`을 통해 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 충돌하는 경우 LLM에 오류 응답을 제공하는 함수입니다. +`@function_tool`을 통해 함수 도구를 생성할 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 충돌하는 경우 LLM에 오류 응답을 제공하는 함수입니다. -- 기본적으로(즉, 아무것도 전달하지 않으면) LLM에 오류가 발생했음을 알리는 `default_tool_error_function`이 실행됩니다. -- 자체 오류 함수를 전달하면 대신 그것이 실행되고 응답이 LLM에 전송됩니다. -- 명시적으로 `None`을 전달하면 모든 도구 호출 오류가 다시 발생하여 직접 처리할 수 있습니다. 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`일 수 있고, 코드가 충돌한 경우 `UserError`일 수 있습니다. +- 기본적으로(즉, 아무것도 전달하지 않으면) LLM에 오류가 발생했음을 알리는 `default_tool_error_function`을 실행합니다. +- 자체 오류 함수를 전달하면 그 함수를 대신 실행하고 응답을 LLM에 보냅니다. +- 명시적으로 `None`을 전달하면 모든 도구 호출 오류가 다시 발생하므로 직접 처리할 수 있습니다. 이는 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`일 수도 있고, 코드가 충돌한 경우 `UserError`일 수도 있습니다. ```python from agents import function_tool, RunContextWrapper @@ -542,7 +542,7 @@ def get_user_profile(user_id: str) -> str: ``` -`FunctionTool` 객체를 수동으로 만드는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다. +`FunctionTool` 객체를 수동으로 생성하는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다. ## Agents as tools @@ -585,9 +585,9 @@ async def main(): print(result.final_output) ``` -### 도구 에이전트 사용자 지정 +### 도구-에이전트 사용자 지정 -`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환할 수 있게 해주는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 통한 structured input도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, fallback 동작 또는 여러 에이전트 호출 체이닝)의 경우 도구 구현에서 `Runner.run`을 직접 사용하세요. +`agent.as_tool` 함수는 에이전트를 쉽게 도구로 전환할 수 있게 해주는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 사용한 구조화된 입력도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, fallback 동작 또는 여러 에이전트 호출 체이닝)이 필요한 경우 도구 구현에서 `Runner.run`을 직접 사용하세요. ```python @function_tool @@ -606,7 +606,7 @@ async def run_my_agent() -> str: return str(result.final_output) ``` -### 도구 에이전트의 구조화된 입력 +### 도구-에이전트의 구조화된 입력 기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달하여 구조화된 스키마를 노출할 수 있습니다. @@ -614,7 +614,7 @@ async def run_my_agent() -> str: - `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON Schema를 포함합니다. - `input_builder=...`를 사용하면 구조화된 도구 인수가 중첩 에이전트 입력이 되는 방식을 완전히 사용자 지정할 수 있습니다. -- `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 안에 파싱된 구조화 페이로드를 포함합니다. +- `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 내부의 파싱된 구조화 페이로드를 포함합니다. ```python from pydantic import BaseModel, Field @@ -634,19 +634,19 @@ translator_tool = translator_agent.as_tool( ) ``` -완전한 실행 가능 예제는 `examples/agent_patterns/agents_as_tools_structured.py`를 참조하세요. +전체 실행 가능한 예제는 `examples/agent_patterns/agents_as_tools_structured.py`를 참조하세요. -### 도구 에이전트의 승인 게이트 +### 도구-에이전트의 승인 게이트 -`Agent.as_tool(..., needs_approval=...)`은 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요한 경우 실행이 일시 중지되고 보류 중인 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요. +`Agent.as_tool(..., needs_approval=...)`은 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요한 경우 실행이 일시 중지되고 대기 중인 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요. ### 사용자 지정 출력 추출 -특정 경우에는 중앙 에이전트에 반환하기 전에 도구 에이전트의 출력을 수정하고 싶을 수 있습니다. 이는 다음을 원할 때 유용할 수 있습니다. +특정 경우에는 중앙 에이전트에 반환하기 전에 도구-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우 유용할 수 있습니다. -- 하위 에이전트의 채팅 기록에서 특정 정보 조각(예: JSON 페이로드)을 추출 -- 에이전트의 최종 답변을 변환하거나 다시 포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환) -- 출력을 검증하거나 에이전트의 응답이 누락되었거나 잘못된 형식일 때 fallback 값 제공 +- 하위 에이전트의 채팅 기록에서 특정 정보(예: JSON 페이로드) 추출 +- 에이전트의 최종 답변 변환 또는 형식 재구성(예: Markdown을 일반 텍스트 또는 CSV로 변환) +- 에이전트 응답이 누락되었거나 형식이 잘못된 경우 출력 검증 또는 fallback 값 제공 `as_tool` 메서드에 `custom_output_extractor` 인수를 제공하여 이를 수행할 수 있습니다. @@ -667,14 +667,14 @@ json_tool = data_agent.as_tool( ) ``` -사용자 지정 추출기 안에서 중첩 [`RunResult`][agents.result.RunResult]는 -[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는 중첩 결과를 후처리하는 동안 -외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다. +사용자 지정 추출기 내부에서 중첩된 [`RunResult`][agents.result.RunResult]는 +[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는 +중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다. [결과 가이드](results.md#agent-as-tool-metadata)를 참조하세요. ### 중첩 에이전트 실행 스트리밍 -`as_tool`에 `on_stream` 콜백을 전달하면, 스트림이 완료된 뒤 최종 출력을 반환하면서도 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신할 수 있습니다. +`as_tool`에 `on_stream` 콜백을 전달하면 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신하면서, 스트림이 완료된 뒤 최종 출력도 반환할 수 있습니다. ```python from agents import AgentToolStreamEvent @@ -694,15 +694,15 @@ billing_agent_tool = billing_agent.as_tool( 예상 동작: -- 이벤트 유형은 `StreamEvent["type"]`를 반영합니다. `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event` -- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드로 실행되고 최종 출력을 반환하기 전에 스트림을 모두 소비합니다. -- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착하는 순서대로 전달됩니다. -- `tool_call`은 도구가 모델 도구 호출을 통해 호출될 때 존재합니다. 직접 호출에서는 `None`으로 남을 수 있습니다. -- 완전한 실행 가능 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요. +- 이벤트 유형은 `StreamEvent["type"]`을 반영합니다. `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event` +- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드에서 실행되며, 최종 출력을 반환하기 전에 스트림을 모두 소비합니다. +- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착한 순서대로 전달됩니다. +- 도구가 모델 도구 호출을 통해 호출되면 `tool_call`이 존재합니다. 직접 호출에서는 `None`일 수 있습니다. +- 전체 실행 가능한 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요. ### 조건부 도구 활성화 -`is_enabled` 매개변수를 사용하여 런타임에 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에 사용 가능한 도구를 동적으로 필터링할 수 있습니다. +`is_enabled` 매개변수를 사용하여 런타임에 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에 제공되는 도구를 동적으로 필터링할 수 있습니다. ```python import asyncio @@ -757,24 +757,24 @@ async def main(): asyncio.run(main()) ``` -`is_enabled` 매개변수는 다음을 허용합니다. +`is_enabled` 매개변수는 다음을 받습니다. -- **Boolean 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화) -- **호출 가능한 함수**: `(context, agent)`를 받아 boolean을 반환하는 함수 -- **Async 함수**: 복잡한 조건부 로직을 위한 async 함수 +- **불리언 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화) +- **호출 가능 함수**: `(context, agent)`를 받아 불리언을 반환하는 함수 +- **비동기 함수**: 복잡한 조건부 로직을 위한 비동기 함수 -비활성화된 도구는 런타임에 LLM으로부터 완전히 숨겨지므로, 다음에 유용합니다. +비활성화된 도구는 런타임에 LLM에게 완전히 숨겨지므로 다음에 유용합니다. - 사용자 권한에 기반한 기능 게이팅 -- 환경별 도구 사용 가능성(dev vs prod) -- 서로 다른 도구 구성의 A/B 테스트 +- 환경별 도구 가용성(개발 vs 프로덕션) +- 다양한 도구 구성의 A/B 테스트 - 런타임 상태에 기반한 동적 도구 필터링 -## 실험적: Codex 도구 +## 실험적 기능: Codex 도구 -`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중에 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다. +`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다. -메인 에이전트가 현재 실행을 벗어나지 않고 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 사용하세요. 기본적으로 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다. +메인 에이전트가 현재 실행을 벗어나지 않고 범위가 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 사용하세요. 기본적으로 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다. ```python from agents import Agent @@ -803,33 +803,33 @@ agent = Agent( ) ``` -다음 옵션 그룹부터 시작하세요. +다음 옵션 그룹부터 살펴보세요. -- 실행 표면: `sandbox_mode` 및 `working_directory`는 Codex가 작동할 수 있는 위치를 정의합니다. 둘을 함께 사용하고, 작업 디렉터리가 Git 저장소 안에 있지 않으면 `skip_git_repo_check=True`를 설정하세요. -- 스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, reasoning effort, approval policy, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요. +- 실행 범위: `sandbox_mode` 및 `working_directory`는 Codex가 작업할 수 있는 위치를 정의합니다. 둘을 함께 설정하고, 작업 디렉터리가 Git 저장소 안에 있지 않으면 `skip_git_repo_check=True`를 설정하세요. +- 스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, 추론 강도, 승인 정책, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요. - 턴 기본값: `default_turn_options=TurnOptions(...)`는 `idle_timeout_seconds` 및 선택적 취소 `signal` 같은 턴별 동작을 구성합니다. -- 도구 I/O: 도구 호출은 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 있는 `inputs` 항목을 최소 하나 포함해야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다. +- 도구 I/O: 도구 호출에는 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 포함된 `inputs` 항목이 적어도 하나 있어야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다. -스레드 재사용과 지속성은 별도의 제어입니다. +스레드 재사용과 지속성은 별도의 제어 항목입니다. -- `persist_session=True`는 같은 도구 인스턴스에 반복적으로 호출할 때 하나의 Codex 스레드를 재사용합니다. +- `persist_session=True`는 같은 도구 인스턴스에 대한 반복 호출에 하나의 Codex 스레드를 재사용합니다. - `use_run_context_thread_id=True`는 동일한 변경 가능한 컨텍스트 객체를 공유하는 실행 전반에서 실행 컨텍스트에 스레드 ID를 저장하고 재사용합니다. -- 스레드 ID 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 구성된 `thread_id` 옵션 순입니다. +- 스레드 ID 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 설정된 `thread_id` 옵션 순입니다. - 기본 실행 컨텍스트 키는 `name="codex"`의 경우 `codex_thread_id`이고, `name="codex_"`의 경우 `codex_thread_id_`입니다. `run_context_thread_id_key`로 재정의하세요. 런타임 구성: -- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나 `codex_options={"api_key": "..."}`를 전달하세요. +- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나, `codex_options={"api_key": "..."}`를 전달하세요. - 런타임: `codex_options.base_url`은 CLI 기본 URL을 재정의합니다. -- 바이너리 해석: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 해석한 뒤, 번들된 벤더 바이너리로 fallback합니다. -- 환경: `codex_options.env`는 서브프로세스 환경을 완전히 제어합니다. 이 값이 제공되면 서브프로세스는 `os.environ`을 상속하지 않습니다. -- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr reader 제한을 제어합니다. 유효 범위는 `65536`부터 `67108864`까지이며, 기본값은 `8388608`입니다. +- 바이너리 확인: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 확인한 뒤, 번들된 벤더 바이너리로 fallback합니다. +- 환경: `codex_options.env`는 하위 프로세스 환경을 완전히 제어합니다. 제공된 경우 하위 프로세스는 `os.environ`을 상속하지 않습니다. +- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536`부터 `67108864`까지이며, 기본값은 `8388608`입니다. - 스트리밍: `on_stream`은 스레드/턴 수명 주기 이벤트와 항목 이벤트(`reasoning`, `command_execution`, `mcp_tool_call`, `file_change`, `web_search`, `todo_list`, `error` 항목 업데이트)를 수신합니다. -- 출력: 결과에는 `response`, `usage`, `thread_id`가 포함되며, usage는 `RunContextWrapper.usage`에 추가됩니다. +- 출력: 결과에는 `response`, `usage`, `thread_id`가 포함됩니다. usage는 `RunContextWrapper.usage`에 추가됩니다. -참조: +참고 자료: -- [Codex 도구 API 참조](ref/extensions/experimental/codex/codex_tool.md) -- [ThreadOptions 참조](ref/extensions/experimental/codex/thread_options.md) -- [TurnOptions 참조](ref/extensions/experimental/codex/turn_options.md) -- 완전한 실행 가능 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참조하세요. \ No newline at end of file +- [Codex 도구 API 레퍼런스](ref/extensions/experimental/codex/codex_tool.md) +- [ThreadOptions 레퍼런스](ref/extensions/experimental/codex/thread_options.md) +- [TurnOptions 레퍼런스](ref/extensions/experimental/codex/turn_options.md) +- 전체 실행 가능한 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참조하세요. \ No newline at end of file diff --git a/docs/ko/tracing.md b/docs/ko/tracing.md index 98ecd64330..007815f37f 100644 --- a/docs/ko/tracing.md +++ b/docs/ko/tracing.md @@ -4,55 +4,59 @@ search: --- # 트레이싱 -Agents SDK에는 기본 제공 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다. 여기에는 LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 발생한 사용자 정의 이벤트까지 포함됩니다. [Traces dashboard](https://platform.openai.com/traces)를 사용하면 개발 중과 프로덕션 환경에서 워크플로를 디버그하고, 시각화하고, 모니터링할 수 있습니다. +Agents SDK에는 기본 제공 트레이싱이 포함되어 있어, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 발생한 사용자 지정 이벤트까지)에 대한 포괄적인 기록을 수집합니다. [트레이스 대시보드](https://platform.openai.com/traces)를 사용하면 개발 중 및 프로덕션 환경에서 워크플로를 디버그하고, 시각화하고, 모니터링할 수 있습니다. !!!note - 트레이싱은 기본적으로 활성화되어 있습니다. 다음의 일반적인 세 가지 방법으로 비활성화할 수 있습니다: + 트레이싱은 기본적으로 활성화되어 있습니다. 다음 세 가지 일반적인 방법으로 비활성화할 수 있습니다. - 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 을 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다 - 2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]를 사용해 전역적으로 트레이싱을 비활성화할 수 있습니다 - 3. 단일 실행에 대해서는 [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 트레이싱을 비활성화할 수 있습니다 + 1. env var `OPENAI_AGENTS_DISABLE_TRACING=1`을 설정하여 트레이싱을 전역적으로 비활성화할 수 있습니다 + 2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]를 사용하여 트레이싱을 전역적으로 비활성화할 수 있습니다 + 3. [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 단일 실행에 대해 트레이싱을 비활성화할 수 있습니다 -***OpenAI API를 사용하면서 Zero Data Retention (ZDR) 정책 하에서 운영하는 조직에서는 트레이싱을 사용할 수 없습니다.*** +***OpenAI의 API를 사용하며 Zero Data Retention (ZDR) 정책에 따라 운영되는 조직에서는 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 -- **트레이스**는 하나의 "워크플로"에 대한 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - - `workflow_name`: 논리적인 워크플로 또는 앱입니다. 예를 들어 "Code generation" 또는 "Customer service"입니다. +- **트레이스**는 "워크플로"의 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다. + - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예를 들어 "Code generation" 또는 "Customer service"입니다. - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다. - - `group_id`: 선택적 그룹 ID로, 동일한 대화에서 나온 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다. + - `group_id`: 동일한 대화의 여러 트레이스를 연결하기 위한 선택적 그룹 ID입니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다. - `disabled`: True이면 트레이스가 기록되지 않습니다. - - `metadata`: 트레이스에 대한 선택적 메타데이터입니다. -- **스팬**은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다: + - `metadata`: 트레이스의 선택적 메타데이터입니다. +- **스팬**은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다. - `started_at` 및 `ended_at` 타임스탬프 - - `trace_id`: 이 스팬이 속한 트레이스를 나타냅니다 - - `parent_id`: 이 스팬의 상위 스팬을 가리킵니다(있는 경우) - - `span_data`: 스팬에 대한 정보입니다. 예를 들어 `AgentSpanData`에는 Agent에 대한 정보가, `GenerationSpanData`에는 LLM 생성에 대한 정보가 포함됩니다. + - 자신이 속한 트레이스를 나타내는 `trace_id` + - 이 스팬의 부모 스팬(있는 경우)을 가리키는 `parent_id` + - 스팬에 대한 정보인 `span_data`. 예를 들어 `AgentSpanData`는 에이전트에 대한 정보를 포함하고, `GenerationSpanData`는 LLM 생성에 대한 정보를 포함하는 식입니다. ## 기본 트레이싱 -기본적으로 SDK는 다음을 트레이싱합니다: +기본적으로 SDK는 다음을 트레이싱합니다. -- 전체 `Runner.{run, run_sync, run_streamed}()`는 `trace()`로 감싸집니다 -- 에이전트가 실행될 때마다 `agent_span()`으로 감싸집니다 -- LLM 생성은 `generation_span()`으로 감싸집니다 -- 함수 도구 호출은 각각 `function_span()`으로 감싸집니다 -- 가드레일은 `guardrail_span()`으로 감싸집니다 -- 핸드오프는 `handoff_span()`으로 감싸집니다 -- 오디오 입력(음성-텍스트 변환)은 `transcription_span()`으로 감싸집니다 -- 오디오 출력(텍스트-음성 변환)은 `speech_span()`으로 감싸집니다 -- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식 관계로 중첩될 수 있습니다 +- 전체 `Runner.{run, run_sync, run_streamed}()`가 `trace()`로 래핑됩니다. +- 에이전트가 실행될 때마다 `agent_span()`으로 래핑됩니다 +- LLM 생성은 `generation_span()`으로 래핑됩니다 +- 함수 도구 호출은 각각 `function_span()`으로 래핑됩니다 +- 가드레일은 `guardrail_span()`으로 래핑됩니다 +- 핸드오프는 `handoff_span()`으로 래핑됩니다 +- 오디오 입력(음성-텍스트 변환)은 `transcription_span()`으로 래핑됩니다 +- 오디오 출력(텍스트-음성 변환)은 `speech_span()`으로 래핑됩니다 +- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식 관계로 배치될 수 있습니다 -기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하는 경우 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]를 사용해 이름 및 기타 속성을 구성할 수도 있습니다. +기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하는 경우 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]로 이름과 기타 속성을 구성할 수도 있습니다. -또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정하여 다른 대상에 트레이스를 전송할 수 있습니다(대체 대상 또는 보조 대상으로). +또한 트레이스를 다른 대상으로 보내도록 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정할 수 있습니다(대체 대상 또는 보조 대상으로). ## 장기 실행 워커와 즉시 내보내기 -기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내며, 메모리 내 큐가 크기 임계값에 도달하면 더 빨리 내보냅니다. 또한 프로세스가 종료될 때 최종 플러시를 수행합니다. Celery, RQ, Dramatiq 또는 FastAPI 백그라운드 작업과 같은 장기 실행 워커에서는 일반적으로 추가 코드 없이도 트레이스가 자동으로 내보내지지만, 각 작업이 끝난 직후 Traces dashboard에 바로 표시되지는 않을 수 있습니다. +기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내거나, 메모리 내 큐가 크기 트리거에 도달하면 더 빨리 내보내며, +프로세스가 종료될 때 최종 flush도 수행합니다. Celery, +RQ, Dramatiq 또는 FastAPI 백그라운드 작업과 같은 장기 실행 워커에서는 일반적으로 추가 코드 없이 트레이스가 자동으로 내보내지지만, +각 작업이 완료된 직후 Traces 대시보드에 표시되지 않을 수 있습니다. -작업 단위가 끝날 때 즉시 전달을 보장해야 한다면, 트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출하세요. +작업 단위가 끝날 때 즉시 전달을 보장해야 하는 경우, +트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출합니다. ```python from agents import Runner, flush_traces, trace @@ -89,11 +93,13 @@ async def run(prompt: str, background_tasks: BackgroundTasks): return {"status": "queued"} ``` -[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이 내보내질 때까지 블로킹되므로, 부분적으로만 구성된 트레이스를 플러시하지 않도록 `trace()`가 닫힌 후 호출해야 합니다. 기본 내보내기 지연이 허용 가능하다면 이 호출은 생략할 수 있습니다. +[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이 +내보내질 때까지 차단하므로, 부분적으로 구성된 트레이스를 flush하지 않도록 `trace()`가 닫힌 후 호출합니다. 기본 내보내기 지연 시간이 허용 가능한 경우 +이 호출을 생략할 수 있습니다. ## 상위 수준 트레이스 -경우에 따라 여러 `run()` 호출을 하나의 단일 트레이스에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다. +때로는 여러 `run()` 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 전체 코드를 `trace()`로 래핑하면 이를 수행할 수 있습니다. ```python from agents import Agent, Runner, trace @@ -108,20 +114,20 @@ 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)를 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. @@ -129,27 +135,28 @@ async def main(): 일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. -`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]를 구성하여 이 오디오 데이터 캡처를 비활성화할 수 있습니다. -기본적으로 `trace_include_sensitive_data`는 `True`입니다. 앱을 실행하기 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`으로 내보내 코드 변경 없이 기본값을 설정할 수 있습니다. +기본적으로 `trace_include_sensitive_data`는 `True`입니다. 앱을 실행하기 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`로 내보내면 코드 없이 기본값을 설정할 수 있습니다. -## 사용자 정의 트레이싱 프로세서 +## 사용자 지정 트레이싱 프로세서 -트레이싱의 상위 수준 아키텍처는 다음과 같습니다: +트레이싱의 상위 수준 아키텍처는 다음과 같습니다. -- 초기화 시 트레이스 생성을 담당하는 전역 [`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]를 사용하면 기본 프로세서를 사용자의 트레이스 프로세서로 **대체**할 수 있습니다. 이 경우 `TracingProcessor`를 포함하지 않으면 트레이스는 OpenAI 백엔드로 전송되지 않습니다. +1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 트레이스와 스팬이 준비되는 대로 수신할 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것에 더해 자체 처리를 수행할 수 있습니다. +2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 자체 트레이스 프로세서로 **교체**할 수 있습니다. 즉, 이를 수행하는 `TracingProcessor`를 포함하지 않는 한 트레이스는 OpenAI 백엔드로 전송되지 않습니다. -## 비 OpenAI 모델과의 트레이싱 -트레이싱을 비활성화하지 않고도 OpenAI Traces dashboard에서 무료 트레이싱을 활성화하기 위해 비 OpenAI 모델에 OpenAI API 키를 사용할 수 있습니다. 어댑터 선택 및 설정 시 유의사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요. +## 비 OpenAI 모델을 사용한 트레이싱 + +비 OpenAI 모델에서 OpenAI API 키를 사용하면 트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. 어댑터 선택 및 설정 시 주의 사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참조하세요. ```python import os @@ -170,7 +177,7 @@ agent = Agent( ) ``` -단일 실행에 대해서만 다른 트레이싱 키가 필요하다면, 전역 exporter를 변경하는 대신 `RunConfig`를 통해 전달하세요. +단일 실행에 대해서만 다른 트레이싱 키가 필요한 경우, 전역 익스포터를 변경하는 대신 `RunConfig`를 통해 전달합니다. ```python from agents import Runner, RunConfig @@ -183,7 +190,8 @@ await Runner.run( ``` ## 추가 참고 사항 -- Openai Traces dashboard에서 무료 트레이스를 확인하세요 +- Openai Traces 대시보드에서 무료 트레이스를 확인합니다. + ## 에코시스템 통합 @@ -194,8 +202,8 @@ await Runner.run( - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) -- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) +- [MLflow (자체 호스팅/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow (Databricks 호스팅)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) - [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk) diff --git a/docs/ko/usage.md b/docs/ko/usage.md index 9eb5d87e98..1041dd427e 100644 --- a/docs/ko/usage.md +++ b/docs/ko/usage.md @@ -2,9 +2,9 @@ search: exclude: true --- -# 사용 +# 사용량 -Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하여 비용 모니터링, 제한 적용, 분석 기록에 활용할 수 있습니다. +Agents SDK는 모든 실행에 대한 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 접근할 수 있으며, 비용 모니터링, 한도 적용, 분석 기록에 사용할 수 있습니다. ## 추적 항목 @@ -19,7 +19,7 @@ Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합 ## 실행에서 사용량 접근 -`Runner.run(...)` 이후 `result.context_wrapper.usage`를 통해 사용량에 접근할 수 있습니다. +`Runner.run(...)` 이후에는 `result.context_wrapper.usage`를 통해 사용량에 접근합니다. ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -31,20 +31,20 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다. +사용량은 실행 중의 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다. ### 서드파티 어댑터에서 사용량 활성화 -사용량 보고는 서드파티 어댑터와 제공자 백엔드에 따라 달라집니다. 어댑터 기반 모델을 사용하고 정확한 `result.context_wrapper.usage` 값이 필요하다면 다음을 확인하세요: +사용량 보고는 서드파티 어댑터와 제공자 백엔드에 따라 다릅니다. 어댑터 기반 모델에 의존하고 정확한 `result.context_wrapper.usage` 값이 필요한 경우: -- `AnyLLMModel`에서는 업스트림 제공자가 사용량을 반환하면 자동으로 전파됩니다. 스트리밍 Chat Completions 백엔드의 경우, 사용량 청크가 전송되기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다 -- `LitellmModel`에서는 일부 제공자 백엔드가 기본적으로 사용량을 보고하지 않으므로, `ModelSettings(include_usage=True)`가 자주 필요합니다 +- `AnyLLMModel`에서는 업스트림 제공자가 사용량을 반환하면 사용량이 자동으로 전달됩니다. 스트리밍 Chat Completions 백엔드의 경우 사용량 청크가 방출되기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. +- `LitellmModel`에서는 일부 제공자 백엔드가 기본적으로 사용량을 보고하지 않으므로, `ModelSettings(include_usage=True)`가 필요한 경우가 많습니다. -모델 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션에서 어댑터별 참고 사항을 확인하고, 배포 예정인 정확한 제공자 백엔드를 검증하세요. +Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션에서 어댑터별 참고 사항을 검토하고, 배포하려는 정확한 제공자 백엔드를 검증하세요. ## 요청별 사용량 추적 -SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하므로, 상세한 비용 계산과 컨텍스트 윈도 소비량 모니터링에 유용합니다. +SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하므로, 자세한 비용 계산과 컨텍스트 창 소비 모니터링에 유용합니다. ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -55,7 +55,7 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): ## 세션에서 사용량 접근 -`Session`(예: `SQLiteSession`)을 사용할 때 `Runner.run(...)`의 각 호출은 해당 실행에 대한 사용량을 반환합니다. 세션은 컨텍스트를 위해 대화 이력을 유지하지만, 각 실행의 사용량은 서로 독립적입니다. +`Session`(예: `SQLiteSession`)을 사용하는 경우 `Runner.run(...)`을 호출할 때마다 해당 특정 실행의 사용량이 반환됩니다. 세션은 컨텍스트를 위해 대화 기록을 유지하지만, 각 실행의 사용량은 독립적입니다. ```python session = SQLiteSession("my_conversation") @@ -67,11 +67,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): @@ -80,11 +80,11 @@ class MyHooks(RunHooks): print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens") ``` -## API 레퍼런스 +## API 참조 -자세한 API 문서는 다음을 참고하세요: +자세한 API 문서는 다음을 참조하세요. - [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조 - [`RequestUsage`][agents.usage.RequestUsage] - 요청별 사용량 세부 정보 - [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근 -- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 라이프사이클에 훅 연결 \ No newline at end of file +- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 수명 주기에 훅 연결 \ No newline at end of file diff --git a/docs/ko/visualization.md b/docs/ko/visualization.md index 1cebf06076..bfd9760c35 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,12 +16,12 @@ pip install "openai-agents[viz]" ## 그래프 생성 -`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 방향 그래프를 만듭니다: +`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 유향 그래프를 만듭니다. -- **에이전트**는 노란색 상자로 표시됩니다 -- **MCP 서버**는 회색 상자로 표시됩니다 -- **도구**는 초록색 타원으로 표시됩니다 -- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향성 간선으로 표시됩니다 +- **에이전트**는 노란색 박스로 표시됩니다. +- **MCP 서버**는 회색 박스로 표시됩니다. +- **도구**는 초록색 타원으로 표시됩니다. +- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향성 엣지로 표시됩니다. ### 사용 예시 @@ -67,40 +67,43 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![에이전트 그래프](../assets/images/graph.png) + +이렇게 하면 **트리아지 에이전트**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프가 생성됩니다. -이렇게 하면 **triage agent**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프가 생성됩니다. ## 시각화 이해 -생성된 그래프에는 다음이 포함됩니다: +생성된 그래프에는 다음이 포함됩니다. -- 진입 지점을 나타내는 **시작 노드** (`__start__`) -- 노란색 채움의 **직사각형**으로 표시된 에이전트 -- 초록색 채움의 **타원**으로 표시된 도구 -- 회색 채움의 **직사각형**으로 표시된 MCP 서버 -- 상호작용을 나타내는 방향성 간선: - - 에이전트 간 핸드오프를 위한 **실선 화살표** - - 도구 호출을 위한 **점선 화살표** - - MCP 서버 호출을 위한 **파선 화살표** -- 실행이 종료되는 지점을 나타내는 **종료 노드** (`__end__`) +- 진입점을 나타내는 **시작 노드**(`__start__`) +- 노란색으로 채워진 **직사각형**으로 표시되는 에이전트 +- 초록색으로 채워진 **타원**으로 표시되는 도구 +- 회색으로 채워진 **직사각형**으로 표시되는 MCP 서버 +- 상호작용을 나타내는 방향성 엣지: + - 에이전트 간 핸드오프를 나타내는 **실선 화살표** + - 도구 호출을 나타내는 **점선 화살표** + - MCP 서버 호출을 나타내는 **파선 화살표** +- 실행이 종료되는 위치를 나타내는 **종료 노드**(`__end__`) -**참고:** MCP 서버는 `agents` 패키지의 최신 버전에서 렌더링됩니다(**v0.2.8**에서 확인됨). 시각화에서 MCP 상자가 보이지 않으면 최신 릴리스로 업그레이드하세요. +**참고:** MCP 서버는 최신 버전의 +`agents` 패키지에서 렌더링됩니다(**v0.2.8**에서 확인됨). 시각화에서 MCP 박스가 +보이지 않으면 최신 릴리스로 업그레이드하세요. ## 그래프 사용자 지정 ### 그래프 표시 -기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에서 표시하려면 다음과 같이 작성하세요: +기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에 표시하려면 다음과 같이 작성합니다. ```python draw_graph(triage_agent).view() ``` ### 그래프 저장 -기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일명을 지정하세요: +기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일 이름을 지정합니다. ```python draw_graph(triage_agent, filename="agent_graph") ``` -이렇게 하면 작업 디렉터리에 `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 dbcae9cbf8..52f878f11a 100644 --- a/docs/ko/voice/pipeline.md +++ b/docs/ko/voice/pipeline.md @@ -2,9 +2,9 @@ search: exclude: true --- -# 파이프라인과 워크플로 +# 파이프라인 및 워크플로 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 워크플로를 음성 앱으로 쉽게 전환할 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 시점 감지, 적절한 시점의 워크플로 호출, 그리고 워크플로 출력의 오디오 변환까지 처리합니다. +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 기반 워크플로를 음성 앱으로 쉽게 전환할 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 시점 감지, 적절한 시점의 워크플로 호출, 워크플로 출력의 오디오 변환을 처리합니다. ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## 파이프라인 구성 -파이프라인을 생성할 때 몇 가지를 설정할 수 있습니다: +파이프라인을 만들 때 몇 가지를 설정할 수 있습니다. -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]: 새 오디오가 전사될 때마다 실행되는 코드입니다 +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]: 새 오디오가 전사될 때마다 실행되는 코드 2. 사용되는 [`speech-to-text`][agents.voice.model.STTModel] 및 [`text-to-speech`][agents.voice.model.TTSModel] 모델 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 다음과 같은 항목을 구성할 수 있습니다: +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 다음과 같은 항목을 구성할 수 있습니다. - 모델 이름을 모델에 매핑할 수 있는 모델 제공자 - - 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, trace ID 등 트레이싱 관련 설정 - - 프롬프트, 언어, 사용되는 데이터 유형 등 TTS 및 STT 모델의 설정 + - 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 트레이스 ID 등을 포함한 트레이싱 + - 프롬프트, 언어, 사용되는 데이터 타입 등 TTS 및 STT 모델 설정 ## 파이프라인 실행 -[`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드를 통해 파이프라인을 실행할 수 있으며, 두 가지 형태의 오디오 입력을 전달할 수 있습니다: +[`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드로 파이프라인을 실행할 수 있으며, 오디오 입력은 두 가지 형태로 전달할 수 있습니다. -1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사본이 있을 때 사용하며, 그에 대한 결과만 생성하려는 경우에 적합합니다. 이는 화자가 말하기를 마쳤는지 감지할 필요가 없는 경우에 유용합니다. 예를 들어, 미리 녹음된 오디오가 있거나 사용자가 말을 마쳤는지 명확한 push-to-talk 앱에서 사용할 수 있습니다. -2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 말하기를 마쳤는지 감지해야 할 수 있을 때 사용합니다. 감지되는 대로 오디오 청크를 전달할 수 있으며, 음성 파이프라인이 "activity detection"이라는 과정을 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다. +1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사가 있고 그에 대한 결과만 생성하려는 경우에 사용됩니다. 화자가 말하기를 마쳤는지 감지할 필요가 없는 경우에 유용합니다. 예를 들어, 사전 녹음된 오디오가 있거나 사용자가 말하기를 마친 시점이 명확한 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]: 턴 시작 또는 종료와 같은 라이프사이클 이벤트를 알려줍니다 -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/ko/voice/quickstart.md b/docs/ko/voice/quickstart.md index a1244ab025..034c21e4ee 100644 --- a/docs/ko/voice/quickstart.md +++ b/docs/ko/voice/quickstart.md @@ -4,9 +4,9 @@ search: --- # 빠른 시작 -## 사전 요구 사항 +## 사전 준비 사항 -Agents SDK에 대한 기본 [빠른 시작 지침](../quickstart.md)을 따르고 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택적 음성 종속성을 설치하세요. +Agents SDK의 기본 [빠른 시작 지침](../quickstart.md)을 따르고 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택 사항인 음성 의존성을 설치하세요. ```bash pip install 'openai-agents[voice]' @@ -14,11 +14,11 @@ pip install 'openai-agents[voice]' ## 개념 -알아야 할 주요 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다. +알아두어야 할 주요 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다. -1. 음성을 텍스트로 변환하기 위해 speech-to-text 모델을 실행합니다. -2. 결과를 생성하기 위해 일반적으로 에이전트형 워크플로인 코드를 실행합니다. -3. 결과 텍스트를 다시 음성으로 변환하기 위해 text-to-speech 모델을 실행합니다. +1. 음성-텍스트 변환 모델을 실행하여 오디오를 텍스트로 변환합니다. +2. 일반적으로 에이전트형 워크플로인 코드를 실행하여 결과를 생성합니다. +3. 텍스트-음성 변환 모델을 실행하여 결과 텍스트를 다시 오디오로 변환합니다. ```mermaid graph LR @@ -48,7 +48,7 @@ graph LR ## 에이전트 -먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 몇 개의 에이전트, 핸드오프, 도구를 사용하겠습니다. +먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 에이전트 몇 개, 핸드오프 하나, 도구 하나를 사용합니다. ```python import asyncio @@ -195,4 +195,4 @@ if __name__ == "__main__": asyncio.run(main()) ``` -이 예제를 실행하면 에이전트가 사용자에게 말을 합니다! 직접 에이전트에게 말해 볼 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인하세요. \ No newline at end of file +이 예제를 실행하면 에이전트가 사용자에게 말을 걸 것입니다! 에이전트와 직접 대화할 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인하세요. \ No newline at end of file diff --git a/docs/ko/voice/tracing.md b/docs/ko/voice/tracing.md index d341f34e25..adef95624d 100644 --- a/docs/ko/voice/tracing.md +++ b/docs/ko/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # 트레이싱 -[에이전트가 트레이싱되는](../tracing.md) 방식과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다. +[에이전트가 트레이싱되는 방식](../tracing.md)과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다. -기본적인 트레이싱 정보는 위의 트레이싱 문서를 참고하시면 되며, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다. +기본적인 트레이싱 정보는 위의 트레이싱 문서를 참고할 수 있으며, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다. -트레이싱 관련 핵심 필드는 다음과 같습니다: +트레이싱 관련 주요 필드는 다음과 같습니다. -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱을 비활성화할지 여부를 제어합니다. 기본값은 트레이싱 활성화입니다. -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사본과 같은 잠재적으로 민감한 데이터를 트레이스에 포함할지 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며, Workflow 내부에서 발생하는 모든 것에는 적용되지 않습니다. +- [`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`로, 여러 트레이스를 연결할 수 있습니다. +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있게 해 주는 트레이스의 `group_id`입니다. - [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.trace_metadata]: 트레이스에 포함할 추가 메타데이터입니다. \ No newline at end of file diff --git a/docs/scripts/translate_docs.py b/docs/scripts/translate_docs.py index b5b686fc55..18a97a8dd1 100644 --- a/docs/scripts/translate_docs.py +++ b/docs/scripts/translate_docs.py @@ -340,8 +340,8 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None: model=OPENAI_MODEL, instructions=instructions, input=chunk, - reasoning={"effort": "none"}, - text={"verbosity": "low"}, + reasoning={"effort": "high"}, + text={"verbosity": "medium"}, ) translated_content.append(response.output_text) elif OPENAI_MODEL.startswith("o"): diff --git a/docs/zh/agents.md b/docs/zh/agents.md index 64e9b5fc80..7210cde7a4 100644 --- a/docs/zh/agents.md +++ b/docs/zh/agents.md @@ -4,49 +4,49 @@ search: --- # 智能体 -智能体是应用中的核心构建块。智能体是一个大语言模型（LLM），配置了 instructions、工具，以及可选的运行时行为，例如任务转移、安全防护措施和 structured outputs。 +智能体是应用中的核心构建块。智能体是一个大型语言模型（LLM），配置了instructions、tools，以及可选的运行时行为，例如任务转移、安全防护措施和structured outputs。 -当你想定义或自定义单个普通 `Agent` 时，请使用本页。如果你正在决定多个智能体应如何协作，请阅读[智能体编排](multi_agent.md)。如果智能体应在包含清单定义文件和沙箱原生能力的隔离工作区内运行，请阅读[沙箱智能体概念](sandbox/guide.md)。 +当你想定义或自定义单个普通`Agent`时，请使用本页。如果你正在决定多个智能体应如何协作，请阅读[智能体编排](multi_agent.md)。如果智能体应在包含由清单定义的文件和沙盒原生能力的隔离工作区内运行，请阅读[沙盒智能体概念](sandbox/guide.md)。 -SDK 对 OpenAI 模型默认使用 Responses API，但这里的区别在于编排：`Agent` 加 `Runner` 让 SDK 为你管理轮次、工具、安全防护措施、任务转移和会话。如果你想自己掌控这个循环，请直接使用 Responses API。 +对于OpenAI模型，SDK默认使用Responses API，但这里的区别在于编排：`Agent`加`Runner`让SDK为你管理轮次、工具、安全防护措施、任务转移和会话。如果你想自行掌控该循环，请直接使用Responses API。 -## 下一篇指南的选择 +## 下一篇指南 -使用本页作为智能体定义的中心。跳转到与你接下来需要做出的决定相匹配的相邻指南。 +将本页作为智能体定义的中心。跳转到与你接下来需要做出的决策相匹配的相邻指南。 | 如果你想要... | 接下来阅读 | | --- | --- | -| 选择模型或服务商设置 | [模型](models/index.md) | +| 选择模型或提供商设置 | [模型](models/index.md) | | 为智能体添加能力 | [工具](tools.md) | -| 针对真实代码仓库、文档包或隔离工作区运行智能体 | [沙箱智能体快速入门](sandbox_agents.md) | -| 在管理器风格的编排与任务转移之间做决定 | [智能体编排](multi_agent.md) | +| 让智能体针对真实代码仓库、文档包或隔离工作区运行 | [沙盒智能体快速入门](sandbox_agents.md) | +| 在管理器式编排与任务转移之间做决策 | [智能体编排](multi_agent.md) | | 配置任务转移行为 | [任务转移](handoffs.md) | | 运行轮次、流式传输事件或管理对话状态 | [运行智能体](running_agents.md) | | 检查最终输出、运行项或可恢复状态 | [结果](results.md) | -| 共享本地依赖和运行时状态 | [上下文管理](context.md) | +| 共享本地依赖项和运行时状态 | [上下文管理](context.md) | ## 基本配置 -智能体最常见的属性包括： +智能体最常见的属性如下： -| 属性 | 必需 | 描述 | +| 属性 | 必填 | 描述 | | --- | --- | --- | | `name` | 是 | 人类可读的智能体名称。 | -| `instructions` | 是 | 系统提示词或动态 instructions 回调。请参阅[动态 instructions](#dynamic-instructions)。 | -| `prompt` | 否 | OpenAI Responses API prompt 配置。接受静态 prompt 对象或函数。请参阅[提示词模板](#prompt-templates)。 | -| `handoff_description` | 否 | 当此智能体作为任务转移目标提供时展示的简短描述。 | -| `handoffs` | 否 | 将对话委托给专家智能体。请参阅[任务转移](handoffs.md)。 | -| `model` | 否 | 使用哪个 LLM。请参阅[模型](models/index.md)。 | -| `model_settings` | 否 | 模型调优参数，例如 `temperature`、`top_p` 和 `tool_choice`。 | -| `tools` | 否 | 智能体可以调用的工具。请参阅[工具](tools.md)。 | -| `mcp_servers` | 否 | 面向智能体、由 MCP 支持的工具。请参阅 [MCP 指南](mcp.md)。 | -| `mcp_config` | 否 | 微调 MCP 工具的准备方式，例如严格 schema 转换和 MCP 失败格式化。请参阅 [MCP 指南](mcp.md#agent-level-mcp-configuration)。 | -| `input_guardrails` | 否 | 在此智能体链的第一个用户输入上运行的安全防护措施。请参阅[安全防护措施](guardrails.md)。 | -| `output_guardrails` | 否 | 在此智能体最终输出上运行的安全防护措施。请参阅[安全防护措施](guardrails.md)。 | -| `output_type` | 否 | 使用结构化输出类型而非纯文本。请参阅[输出类型](#output-types)。 | -| `hooks` | 否 | 作用于智能体范围的生命周期回调。请参阅[生命周期事件（hooks）](#lifecycle-events-hooks)。 | -| `tool_use_behavior` | 否 | 控制工具结果是回传给模型还是结束运行。请参阅[工具使用行为](#tool-use-behavior)。 | -| `reset_tool_choice` | 否 | 在工具调用后重置 `tool_choice`（默认：`True`），以避免工具使用循环。请参阅[强制使用工具](#forcing-tool-use)。 | +| `instructions` | 否 | 系统提示词或动态instructions回调。强烈建议设置。参见[动态instructions](#dynamic-instructions)。 | +| `prompt` | 否 | OpenAI Responses API prompt配置。接受静态prompt对象或函数。参见[Prompt模板](#prompt-templates)。 | +| `handoff_description` | 否 | 当此智能体作为任务转移目标提供时公开的简短描述。 | +| `handoffs` | 否 | 将对话委派给专业智能体。参见[任务转移](handoffs.md)。 | +| `model` | 否 | 使用哪个LLM。参见[模型](models/index.md)。 | +| `model_settings` | 否 | 模型调优参数，例如`temperature`、`top_p`和`tool_choice`。 | +| `tools` | 否 | 智能体可调用的工具。参见[工具](tools.md)。 | +| `mcp_servers` | 否 | 由MCP支持的智能体工具。参见[MCP指南](mcp.md)。 | +| `mcp_config` | 否 | 精细调整MCP工具的准备方式，例如严格的schema转换和MCP失败格式化。参见[MCP指南](mcp.md#agent-level-mcp-configuration)。 | +| `input_guardrails` | 否 | 在此智能体链的首个用户输入上运行的安全防护措施。参见[安全防护措施](guardrails.md)。 | +| `output_guardrails` | 否 | 在此智能体的最终输出上运行的安全防护措施。参见[安全防护措施](guardrails.md)。 | +| `output_type` | 否 | 使用结构化输出类型，而不是纯文本。参见[输出类型](#output-types)。 | +| `hooks` | 否 | 智能体作用域的生命周期回调。参见[生命周期事件（hooks）](#lifecycle-events-hooks)。 | +| `tool_use_behavior` | 否 | 控制工具结果是回传给模型还是结束运行。参见[工具使用行为](#tool-use-behavior)。 | +| `reset_tool_choice` | 否 | 在工具调用后重置`tool_choice`（默认值：`True`），以避免工具使用循环。参见[工具使用的强制](#forcing-tool-use)。 | ```python from agents import Agent, ModelSettings, function_tool @@ -64,23 +64,23 @@ agent = Agent( ) ``` -本节中的所有内容都适用于 `Agent`。`SandboxAgent` 基于相同理念构建，并额外添加了 `default_manifest`、`base_instructions`、`capabilities` 和 `run_as`，用于工作区范围的运行。请参阅[沙箱智能体概念](sandbox/guide.md)。 +本节中的所有内容都适用于`Agent`。`SandboxAgent`基于相同理念构建，并进一步添加了`default_manifest`、`base_instructions`、`capabilities`和`run_as`，用于工作区范围内的运行。参见[沙盒智能体概念](sandbox/guide.md)。 -## 提示词模板 +## Prompt模板 -你可以通过设置 `prompt` 来引用在 OpenAI 平台中创建的提示词模板。这适用于使用 Responses API 的 OpenAI 模型。 +你可以通过设置`prompt`来引用在OpenAI平台中创建的prompt模板。此功能适用于使用Responses API的OpenAI模型。 要使用它，请： -1. 前往 https://platform.openai.com/playground/prompts -2. 创建新的 prompt 变量 `poem_style`。 -3. 创建一个包含以下内容的系统提示词： +1. 前往https://platform.openai.com/playground/prompts +2. 创建一个新的prompt变量`poem_style`。 +3. 创建包含以下内容的系统提示词： ``` Write a poem in {{poem_style}} ``` -4. 使用 `--prompt-id` 标志运行示例。 +4. 使用`--prompt-id`标志运行示例。 ```python from agents import Agent @@ -95,7 +95,7 @@ agent = Agent( ) ``` -你也可以在运行时动态生成提示词： +你也可以在运行时动态生成prompt： ```python from dataclasses import dataclass @@ -127,9 +127,9 @@ result = await Runner.run( ## 上下文 -智能体在其 `context` 类型上是泛型的。上下文是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会被传递给每个智能体、工具、任务转移等，并作为智能体运行所需依赖和状态的集合。你可以提供任何 Python 对象作为上下文。 +智能体在其`context`类型上是泛型的。Context是一种依赖注入工具：它是你创建并传递给`Runner.run()`的对象，会被传递给每个智能体、工具、任务转移等，并充当智能体运行所需依赖项和状态的容器。你可以将任何Python对象作为context提供。 -阅读[上下文指南](context.md)，了解完整的 `RunContextWrapper` 接口、共享用量跟踪、嵌套 `tool_input` 以及序列化注意事项。 +阅读[上下文指南](context.md)，了解完整的`RunContextWrapper`接口、共享用量跟踪、嵌套的`tool_input`以及序列化注意事项。 ```python @dataclass @@ -148,7 +148,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 @@ -169,20 +169,20 @@ agent = Agent( !!! note - 当你传入 `output_type` 时，这会告诉模型使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而不是常规纯文本响应。 + 当你传入`output_type`时，这会告知模型使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而不是常规的纯文本响应。 ## 多智能体系统设计模式 -设计多智能体系统有许多方式，但我们通常看到两种广泛适用的模式： +设计多智能体系统有很多方式，但我们通常看到两种广泛适用的模式： -1. 管理器（agents as tools）：中央管理器/编排器将专用子智能体作为工具调用，并保留对对话的控制权。 -2. 任务转移：对等智能体将控制权转交给接管对话的专用智能体。这是去中心化的。 +1. 管理器（agents as tools）：中央管理器/编排器将专业子智能体作为工具调用，并保留对对话的控制权。 +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)。 ### 管理器（agents as tools） -`customer_facing_agent` 处理所有用户交互，并调用作为工具暴露的专用子智能体。请在[工具](tools.md#agents-as-tools)文档中阅读更多内容。 +`customer_facing_agent`处理所有用户交互，并调用以工具形式公开的专业子智能体。请在[工具](tools.md#agents-as-tools)文档中阅读更多内容。 ```python from agents import Agent @@ -211,7 +211,7 @@ customer_facing_agent = Agent( ### 任务转移 -任务转移是智能体可以委托给的子智能体。当发生任务转移时，被委托的智能体会接收对话历史并接管对话。此模式支持模块化的专用智能体，使其在单一任务上表现出色。请在[任务转移](handoffs.md)文档中阅读更多内容。 +任务转移对象是智能体可以委派给的子智能体。当发生任务转移时，被委派的智能体会接收对话历史并接管对话。此模式支持模块化的专业智能体，使其能够在单一任务上表现出色。请在[任务转移](handoffs.md)文档中阅读更多内容。 ```python from agents import Agent @@ -230,9 +230,9 @@ triage_agent = Agent( ) ``` -## 动态 instructions +## 动态instructions -在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过函数提供动态 instructions。该函数将接收智能体和上下文，并且必须返回 prompt。普通函数和 `async` 函数都受支持。 +在大多数情况下，你可以在创建智能体时提供instructions。不过，你也可以通过函数提供动态instructions。该函数将接收智能体和context，并且必须返回prompt。常规函数和`async`函数均可接受。 ```python def dynamic_instructions( @@ -249,27 +249,27 @@ agent = Agent[UserContext]( ## 生命周期事件（hooks） -有时，你希望观察智能体的生命周期。例如，你可能希望在某些事件发生时记录事件、预取数据或记录用量。 +有时，你希望观察智能体的生命周期。例如，你可能希望在某些事件发生时记录日志、预取数据或记录用量。 -有两个 hook 作用域： +有两个hook作用域： -- [`RunHooks`][agents.lifecycle.RunHooks] 观察整个 `Runner.run(...)` 调用，包括到其他智能体的任务转移。 -- [`AgentHooks`][agents.lifecycle.AgentHooks] 通过 `agent.hooks` 附加到特定智能体实例。 +- [`RunHooks`][agents.lifecycle.RunHooks]观察整个`Runner.run(...)`调用，包括到其他智能体的任务转移。 +- [`AgentHooks`][agents.lifecycle.AgentHooks]通过`agent.hooks`附加到特定智能体实例。 -回调上下文也会根据事件变化： +回调上下文也会根据事件而变化： -- 智能体开始/结束 hooks 接收 [`AgentHookContext`][agents.run_context.AgentHookContext]，它包装你的原始上下文并携带共享的运行用量状态。 -- LLM、工具和任务转移 hooks 接收 [`RunContextWrapper`][agents.run_context.RunContextWrapper]。 +- 智能体开始/结束hook接收[`AgentHookContext`][agents.run_context.AgentHookContext]，它包装你的原始context并携带共享的运行用量状态。 +- LLM、工具和任务转移hook接收[`RunContextWrapper`][agents.run_context.RunContextWrapper]。 -典型 hook 时机： +典型hook时机： -- `on_agent_start` / `on_agent_end`：当特定智能体开始或完成生成最终输出时。 +- `on_agent_start` / `on_agent_end`：当某个特定智能体开始或完成生成最终输出时。 - `on_llm_start` / `on_llm_end`：紧邻每次模型调用前后。 - `on_tool_start` / `on_tool_end`：围绕每次本地工具调用。 - 对于工具调用，hook `context` 通常是 `ToolContext`，因此你可以检查工具调用元数据，例如 `tool_call_id`。 -- `on_handoff`：当控制权从一个智能体转移到另一个智能体时。 + 对于工具调用，hook的`context`通常是`ToolContext`，因此你可以检查诸如`tool_call_id`之类的工具调用元数据。 +- `on_handoff`：当控制权从一个智能体移动到另一个智能体时。 -当你希望为整个工作流设置一个观察者时使用 `RunHooks`；当某个智能体需要自定义副作用时使用 `AgentHooks`。 +当你希望为整个工作流设置单一观察者时，使用`RunHooks`；当某个智能体需要自定义副作用时，使用`AgentHooks`。 ```python from agents import Agent, RunHooks, Runner @@ -291,15 +291,15 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks()) print(result.final_output) ``` -完整的回调接口请参阅[生命周期 API 参考](ref/lifecycle.md)。 +完整的回调接口请参见[生命周期API参考](ref/lifecycle.md)。 ## 安全防护措施 -安全防护措施允许你在智能体运行的同时并行对用户输入进行检查/验证，并在智能体输出生成后对其进行检查/验证。例如，你可以筛查用户输入和智能体输出的相关性。请在[安全防护措施](guardrails.md)文档中阅读更多内容。 +安全防护措施允许你在智能体运行的同时对用户输入执行检查/验证，并在智能体输出生成后对其执行检查/验证。例如，你可以筛查用户输入和智能体输出的相关性。请在[安全防护措施](guardrails.md)文档中阅读更多内容。 ## 智能体的克隆/复制 -通过在智能体上使用 `clone()` 方法，你可以复制一个 Agent，并可选择更改任何你想要的属性。 +通过在智能体上使用`clone()`方法，你可以复制一个Agent，并可选择更改任何你需要的属性。 ```python pirate_agent = Agent( @@ -314,16 +314,16 @@ 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使用该特定工具。 -当你使用 OpenAI Responses 工具搜索时，命名工具选择受到更多限制：你不能用 `tool_choice` 指向裸命名空间名称或仅延迟的工具，并且 `tool_choice="tool_search"` 不会指向 [`ToolSearchTool`][agents.tool.ToolSearchTool]。在这些情况下，优先使用 `auto` 或 `required`。有关 Responses 特有的约束，请参阅[托管工具搜索](tools.md#hosted-tool-search)。 +使用OpenAI Responses工具搜索时，命名工具选择会受到更多限制：你不能通过`tool_choice`定位裸命名空间名称或仅延迟工具，并且`tool_choice="tool_search"`不会定位[`ToolSearchTool`][agents.tool.ToolSearchTool]。在这些情况下，优先使用`auto`或`required`。参见[托管工具搜索](tools.md#hosted-tool-search)，了解Responses特定的约束。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -343,10 +343,10 @@ agent = Agent( ## 工具使用行为 -`Agent` 配置中的 `tool_use_behavior` 参数控制如何处理工具输出： +`Agent`配置中的`tool_use_behavior`参数控制工具输出的处理方式： -- `"run_llm_again"`：默认值。运行工具，并由 LLM 处理结果以生成最终响应。 -- `"stop_on_first_tool"`：将第一次工具调用的输出用作最终响应，而不再进行 LLM 处理。 +- `"run_llm_again"`：默认值。运行工具，并由LLM处理结果以生成最终响应。 +- `"stop_on_first_tool"`：第一个工具调用的输出会被用作最终响应，不再经过LLM进一步处理。 ```python from agents import Agent, Runner, function_tool, ModelSettings @@ -388,7 +388,7 @@ agent = Agent( ) ``` -- `ToolsToFinalOutputFunction`：自定义函数，用于处理工具结果并决定是停止还是继续使用 LLM。 +- `ToolsToFinalOutputFunction`：一个自定义函数，用于处理工具结果并决定是停止还是继续使用LLM。 ```python from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper @@ -426,4 +426,4 @@ agent = Agent( !!! note - 为防止无限循环，框架会在工具调用后自动将 `tool_choice` 重置为 "auto"。此行为可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 配置。无限循环的原因是工具结果会发送给 LLM，而 LLM 随后又会因为 `tool_choice` 生成另一个工具调用，如此反复。 \ No newline at end of file + 为防止无限循环，框架会在工具调用后自动将`tool_choice`重置为"auto"。此行为可通过[`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]配置。产生无限循环的原因是工具结果会发送给LLM，而LLM随后又因为`tool_choice`生成另一次工具调用，如此无穷无尽。 \ No newline at end of file diff --git a/docs/zh/config.md b/docs/zh/config.md index 3af0c330eb..d81588fc6c 100644 --- a/docs/zh/config.md +++ b/docs/zh/config.md @@ -4,21 +4,21 @@ search: --- # 配置 -本页面介绍通常在应用启动时一次性设置的 SDK 全局默认项，例如默认 OpenAI key 或 client、默认 OpenAI API 形态、追踪导出默认项以及日志行为。 +本页介绍通常在应用启动期间只需设置一次的 SDK 全局默认值，例如默认 OpenAI 密钥或客户端、默认 OpenAI API 形态、追踪导出默认值以及日志记录行为。 -这些默认项同样适用于基于沙箱的工作流，但沙箱工作区、沙箱客户端和会话复用需要单独配置。 +这些默认值仍适用于基于沙盒的工作流，但沙盒工作区、沙盒客户端和会话复用需要单独配置。 -如果你需要改为配置特定智能体或运行，请先查看： +如果你需要改为配置特定智能体或运行，请从以下内容开始： -- 普通 `Agent` 的 instructions、tools、输出类型、任务转移和安全防护措施，请参阅[智能体](agents.md)。 -- `RunConfig`、会话和对话状态选项，请参阅[运行智能体](running_agents.md)。 -- `SandboxRunConfig`、清单、能力和沙箱客户端专属工作区设置，请参阅[沙箱智能体](sandbox/guide.md)。 -- 模型选择和提供方配置，请参阅[模型](models/index.md)。 -- 每次运行的追踪元数据和自定义追踪进程，请参阅[追踪](tracing.md)。 +- [智能体](agents.md)：了解普通 `Agent` 上的 instructions、tools、输出类型、任务转移和安全防护措施。 +- [运行智能体](running_agents.md)：了解 `RunConfig`、会话和对话状态选项。 +- [沙盒智能体](sandbox/guide.md)：了解 `SandboxRunConfig`、清单、能力以及特定于沙盒客户端的工作区设置。 +- [模型](models/index.md)：了解模型选择和提供方配置。 +- [追踪](tracing.md)：了解每次运行的追踪元数据和自定义追踪处理器。 -## API keys 与 clients +## API 密钥和客户端 -默认情况下，SDK 使用 `OPENAI_API_KEY` 环境变量来处理 LLM 请求和追踪。该 key 会在 SDK 首次创建 OpenAI client 时解析（惰性初始化），因此请在首次模型调用前设置该环境变量。如果你的应用启动前无法设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数设置 key。 +默认情况下，SDK 使用 `OPENAI_API_KEY` 环境变量处理 LLM 请求和追踪。该密钥会在 SDK 首次创建 OpenAI 客户端时解析（惰性初始化），因此请在首次模型调用之前设置环境变量。如果你无法在应用启动前设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数来设置密钥。 ```python from agents import set_default_openai_key @@ -26,7 +26,7 @@ from agents import set_default_openai_key set_default_openai_key("sk-...") ``` -或者，你也可以配置要使用的 OpenAI client。默认情况下，SDK 会创建一个 `AsyncOpenAI` 实例，使用来自环境变量的 API key 或上面设置的默认 key。你可以通过 [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 @@ -36,14 +36,14 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client) ``` -如果你更偏好基于环境变量的 endpoint 配置，默认 OpenAI provider 也会读取 `OPENAI_BASE_URL`。启用 Responses websocket 传输时，它还会读取 `OPENAI_WEBSOCKET_BASE_URL` 用于 websocket `/responses` endpoint。 +如果你更偏好基于环境变量的端点配置，默认 OpenAI 提供方也会读取 `OPENAI_BASE_URL`。当你启用 Responses websocket 传输时，它还会读取 `OPENAI_WEBSOCKET_BASE_URL` 作为 websocket `/responses` 端点。 ```bash export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1" export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1" ``` -最后，你还可以自定义所使用的 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 @@ -53,7 +53,7 @@ set_default_openai_api("chat_completions") ## 追踪 -追踪默认启用。默认情况下，它使用与你在上文模型请求中相同的 OpenAI API key（即环境变量中的 key，或你设置的默认 key）。你可以使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数专门设置追踪使用的 API key。 +追踪默认启用。默认情况下，它使用与你在上一节中的模型请求相同的 OpenAI API 密钥（即环境变量中的密钥或你设置的默认密钥）。你可以使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数专门设置用于追踪的 API 密钥。 ```python from agents import set_tracing_export_api_key @@ -61,7 +61,7 @@ from agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...") ``` -如果你的模型流量使用一个 key 或 client，但追踪应使用另一个 OpenAI key，请在设置默认 key 或 client 时传入 `use_for_tracing=False`，然后单独配置追踪。如果你未使用自定义 client，也可对 [`set_default_openai_key()`][agents.set_default_openai_key] 使用同样模式。 +如果你的模型流量使用一个密钥或客户端，但追踪应使用另一个 OpenAI 密钥，请在设置默认密钥或客户端时传入 `use_for_tracing=False`，然后单独配置追踪。如果你没有使用自定义客户端，同样的模式也适用于 [`set_default_openai_key()`][agents.set_default_openai_key]。 ```python from openai import AsyncOpenAI @@ -76,14 +76,14 @@ set_default_openai_client(custom_client, use_for_tracing=False) set_tracing_export_api_key("sk-tracing") ``` -如果使用默认导出器时，你需要将 traces 归属到特定 organization 或 project，请在应用启动前设置这些环境变量： +如果你在使用默认导出器时需要将追踪归因到特定组织或项目，请在应用启动前设置这些环境变量： ```bash export OPENAI_ORG_ID="org_..." export OPENAI_PROJECT_ID="proj_..." ``` -你也可以按每次运行设置追踪 API key，而无需更改全局导出器。 +你也可以在每次运行时设置追踪 API 密钥，而无需更改全局导出器。 ```python from agents import Runner, RunConfig @@ -95,7 +95,7 @@ await Runner.run( ) ``` -你还可以使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数完全禁用追踪。 +你也可以使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数完全禁用追踪。 ```python from agents import set_tracing_disabled @@ -103,7 +103,7 @@ from agents import set_tracing_disabled set_tracing_disabled(True) ``` -如果你希望保持追踪启用，但从追踪负载中排除可能敏感的输入/输出，请将 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 设为 `False`： +如果你希望保持追踪启用，但从追踪负载中排除可能敏感的输入/输出，请将 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 设置为 `False`： ```python from agents import Runner, RunConfig @@ -115,19 +115,19 @@ await Runner.run( ) ``` -你也可以不写代码，在应用启动前设置此环境变量来修改默认行为： +你也可以通过在应用启动前设置此环境变量，在不编写代码的情况下更改默认值： ```bash export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0 ``` -完整的追踪控制请参阅[追踪指南](tracing.md)。 +有关完整的追踪控制，请参阅[追踪指南](tracing.md)。 ## 调试日志 -SDK 定义了两个 Python logger（`openai.agents` 和 `openai.agents.tracing`），默认不附加 handlers。日志遵循你应用的 Python 日志配置。 +SDK 定义了两个 Python 日志记录器（`openai.agents` 和 `openai.agents.tracing`），并且默认不附加处理器。日志遵循你的应用的 Python 日志配置。 -如需启用详细日志，请使用 [`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 @@ -135,7 +135,7 @@ from agents import enable_verbose_stdout_logging enable_verbose_stdout_logging() ``` -或者，你也可以通过添加 handlers、filters、formatters 等来自定义日志。更多信息请参阅[Python logging 指南](https://docs.python.org/3/howto/logging.html)。 +或者，你可以通过添加处理器、过滤器、格式化器等来自定义日志。你可以在 [Python 日志指南](https://docs.python.org/3/howto/logging.html)中了解更多信息。 ```python import logging @@ -158,14 +158,14 @@ logger.addHandler(logging.StreamHandler()) 某些日志可能包含敏感数据（例如用户数据）。 -默认情况下，SDK **不会**记录 LLM 输入/输出或 tools 输入/输出。这些保护由以下项控制： +默认情况下，SDK **不会**记录 LLM 输入/输出或工具输入/输出。这些保护由以下内容控制： ```bash OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1 ``` -如果你需要为调试临时包含这些数据，请在应用启动前将任一变量设为 `0`（或 `false`）： +如果你需要临时包含这些数据以进行调试，请在应用启动前将任一变量设置为 `0`（或 `false`）： ```bash export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0 diff --git a/docs/zh/context.md b/docs/zh/context.md index abe3918f9d..61f20aaa84 100644 --- a/docs/zh/context.md +++ b/docs/zh/context.md @@ -4,49 +4,49 @@ search: --- # 上下文管理 -Context 是一个含义广泛的术语。你可能关心的上下文主要有两类： +上下文是一个含义丰富的术语。你可能关心的上下文主要有两类： -1. 你的代码在本地可用的上下文：这是在工具函数运行时、在 `on_handoff` 等回调中、在生命周期钩子中等场景下可能需要的数据和依赖。 -2. LLM 可用的上下文：这是 LLM 在生成回复时能看到的数据。 +1. 代码本地可用的上下文：这是工具函数运行时、`on_handoff` 等回调中、生命周期钩子中等可能需要的数据和依赖项。 +2. LLM 可用的上下文：这是 LLM 在生成响应时看到的数据。 ## 本地上下文 -这通过 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 类及其中的 [`context`][agents.run_context.RunContextWrapper.context] 属性来表示。其工作方式如下： +这通过 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 类及其中的 [`context`][agents.run_context.RunContextWrapper.context] 属性来表示。它的工作方式如下： -1. 你可以创建任何想要的 Python 对象。常见模式是使用 dataclass 或 Pydantic 对象。 -2. 你将该对象传给各类 run 方法（例如 `Runner.run(..., context=whatever)`）。 -3. 你的所有工具调用、生命周期钩子等都会收到一个包装器对象 `RunContextWrapper[T]`，其中 `T` 表示你的上下文对象类型，你可以通过 `wrapper.context` 访问它。 +1. 你创建任意所需的 Python 对象。常见模式是使用 dataclass 或 Pydantic 对象。 +2. 你将该对象传递给各种 run 方法（例如 `Runner.run(..., context=whatever)`）。 +3. 你的所有工具调用、生命周期钩子等都会收到一个包装对象 `RunContextWrapper[T]`，其中 `T` 表示你的上下文对象类型，你可以通过 `wrapper.context` 访问它。 -对于某些运行时特定回调，SDK 可能会传入 `RunContextWrapper[T]` 的更专用子类。例如，工具调用生命周期钩子通常会收到 `ToolContext`，它还会暴露工具调用元数据，如 `tool_call_id`、`tool_name` 和 `tool_arguments`。 +对于一些运行时特定的回调，SDK 可能会传递 `RunContextWrapper[T]` 的更专用子类。例如，工具调用生命周期钩子通常会接收 `ToolContext`，它还会公开工具调用元数据，例如 `tool_call_id`、`tool_name` 和 `tool_arguments`。 -**最重要**的一点是：在某次给定的智能体运行中，每个智能体、工具函数、生命周期等都必须使用相同的上下文_类型_。 +需要注意的**最重要**事项：对于给定的智能体运行，其每个智能体、工具函数、生命周期等都必须使用相同的上下文_类型_。 -你可以将上下文用于如下场景： +你可以将上下文用于以下用途： -- 运行的上下文数据（例如用户名/uid 或其他用户信息） -- 依赖项（例如 logger 对象、数据获取器等） -- 辅助函数 +- 运行所需的上下文数据（例如用户名/uid 或关于用户的其他信息） +- 依赖项（例如日志记录器对象、数据获取器等） +- 辅助函数 !!! danger "注意" - 上下文对象**不会**发送给 LLM。它纯粹是一个本地对象，你可以从中读取、向其中写入并调用其方法。 + 上下文对象**不会**发送给 LLM。它纯粹是一个本地对象，你可以从中读取、向其写入，并调用其方法。 -在一次运行中，派生包装器共享相同的底层应用上下文、审批状态和用量追踪。嵌套的 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行可能会附加不同的 `tool_input`，但默认情况下不会获得应用状态的隔离副本。 +在单次运行中，派生包装器共享相同的底层应用上下文、审批状态和用量跟踪。嵌套的 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行可能会附加不同的 `tool_input`，但默认情况下不会获得应用状态的隔离副本。 -### `RunContextWrapper` 提供的内容 +### `RunContextWrapper` 公开的内容 -[`RunContextWrapper`][agents.run_context.RunContextWrapper] 是你应用自定义上下文对象的包装器。实际中你最常使用的是： +[`RunContextWrapper`][agents.run_context.RunContextWrapper] 是围绕你应用定义的上下文对象的包装器。实践中你最常使用的是： -- [`wrapper.context`][agents.run_context.RunContextWrapper.context]：用于你自己的可变应用状态和依赖。 -- [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]：用于当前运行中的聚合请求与 token 用量。 -- [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]：用于当前运行在 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内执行时的结构化输入。 -- [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]：当你需要以编程方式更新审批状态时使用。 +- [`wrapper.context`][agents.run_context.RunContextWrapper.context]：用于你自己的可变应用状态和依赖项。 +- [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]：用于当前运行中聚合的请求和 token 用量。 +- [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]：用于当前运行在 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内执行时的结构化输入。 +- [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]：当你需要以编程方式更新审批状态时使用。 -只有 `wrapper.context` 是你应用自定义的对象。其他字段都是由 SDK 管理的运行时元数据。 +只有 `wrapper.context` 是你应用定义的对象。其他字段都是由 SDK 管理的运行时元数据。 -如果你之后为了 human-in-the-loop 或持久化任务工作流序列化 [`RunState`][agents.run_state.RunState]，这些运行时元数据会随状态一同保存。如果你打算持久化或传输序列化状态，请避免在 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] 中放置敏感信息。 +如果你之后为了人工介入或持久化作业工作流而序列化 [`RunState`][agents.run_state.RunState]，这些运行时元数据会随状态一起保存。如果你打算持久化或传输序列化状态，请避免在 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] 中放入密钥。 -会话状态是另一个独立问题。请根据你希望如何延续轮次，使用 `result.to_input_list()`、`session`、`conversation_id` 或 `previous_response_id`。相关决策请参见 [results](results.md)、[running agents](running_agents.md) 和 [sessions](sessions/index.md)。 +会话状态是另一个单独的问题。根据你希望如何延续多轮对话，可以使用 `result.to_input_list()`、`session`、`conversation_id` 或 `previous_response_id`。有关该决策，请参见[结果](results.md)、[运行智能体](running_agents.md)和[会话](sessions/index.md)。 ```python import asyncio @@ -85,17 +85,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -1. 这是上下文对象。这里我们使用了 dataclass，但你可以使用任何类型。 -2. 这是一个工具。你可以看到它接收 `RunContextWrapper[UserInfo]`。工具实现会从上下文中读取数据。 -3. 我们将智能体标注为泛型 `UserInfo`，这样类型检查器就能捕获错误（例如，如果我们尝试传入接收不同上下文类型的工具）。 -4. 上下文会传给 `run` 函数。 -5. 智能体会正确调用工具并获取年龄。 +1. 这是上下文对象。这里我们使用了 dataclass，但你可以使用任意类型。 +2. 这是一个工具。你可以看到它接收 `RunContextWrapper[UserInfo]`。工具实现会从上下文中读取信息。 +3. 我们用泛型 `UserInfo` 标记该智能体，这样类型检查器就能捕获错误（例如，如果我们尝试传入一个接收不同上下文类型的工具）。 +4. 上下文会传递给 `run` 函数。 +5. 智能体会正确调用该工具并获得年龄。 --- -### 高级内容：`ToolContext` +### 高级：`ToolContext` -在某些情况下，你可能希望访问正在执行的工具的额外元数据——例如其名称、调用 ID 或原始参数字符串。 +在某些情况下，你可能希望访问有关正在执行的工具的额外元数据，例如其名称、调用 ID 或原始参数字符串。 为此，你可以使用 [`ToolContext`][agents.tool_context.ToolContext] 类，它扩展了 `RunContextWrapper`。 ```python @@ -125,24 +125,24 @@ agent = Agent( ``` `ToolContext` 提供与 `RunContextWrapper` 相同的 `.context` 属性， -并额外提供当前工具调用特有的字段： +此外还提供当前工具调用特有的额外字段： -- `tool_name` – 正在调用的工具名称 +- `tool_name` – 被调用工具的名称 - `tool_call_id` – 此工具调用的唯一标识符 -- `tool_arguments` – 传给工具的原始参数字符串 -- `tool_namespace` – 工具调用对应的 Responses 命名空间（当工具通过 `tool_namespace()` 或其他带命名空间的表面加载时） -- `qualified_tool_name` – 在可用时，带命名空间限定的工具名称 +- `tool_arguments` – 传递给工具的原始参数字符串 +- `tool_namespace` – 工具调用的 Responses 命名空间，当工具通过 `tool_namespace()` 或其他带命名空间的表面加载时可用 +- `qualified_tool_name` – 当有可用命名空间时，带命名空间限定的工具名称 -当你在执行期间需要工具级元数据时，使用 `ToolContext`。 -对于智能体与工具之间的一般上下文共享，`RunContextWrapper` 仍然足够。由于 `ToolContext` 扩展自 `RunContextWrapper`，当嵌套的 `Agent.as_tool()` 运行提供了结构化输入时，它也可以暴露 `.tool_input`。 +当你在执行期间需要工具级元数据时，请使用 `ToolContext`。 +对于智能体与工具之间的一般上下文共享，`RunContextWrapper` 仍然足够。由于 `ToolContext` 扩展了 `RunContextWrapper`，当嵌套的 `Agent.as_tool()` 运行提供了结构化输入时，它也可以公开 `.tool_input`。 --- ## 智能体/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. 使用检索或网络检索。这些是特殊工具，能够从文件或数据库中获取相关数据（检索），或从网络获取相关数据（网络检索）。这对于将响应“锚定”在相关上下文数据中很有用。 \ No newline at end of file diff --git a/docs/zh/examples.md b/docs/zh/examples.md index d2aee9af6d..e5e2ccc806 100644 --- a/docs/zh/examples.md +++ b/docs/zh/examples.md @@ -4,85 +4,85 @@ search: --- # 示例 -请在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的示例部分查看 SDK 的多种 sample code。示例按多个目录组织，展示了不同的模式和能力。 +请查看[代码库](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):** - 此目录中的示例展示了常见的智能体设计模式，例如 + 此目录中的示例展示常见的智能体设计模式，例如 - 确定性工作流 - Agents as tools - - 带流式事件的 Agents as tools（`examples/agent_patterns/agents_as_tools_streaming.py`） - - 带结构化输入参数的 Agents as tools（`examples/agent_patterns/agents_as_tools_structured.py`） + - 包含流式传输事件的Agents as tools（`examples/agent_patterns/agents_as_tools_streaming.py`） + - 使用结构化输入参数的Agents as tools（`examples/agent_patterns/agents_as_tools_structured.py`） - 并行智能体执行 - - 条件化工具使用 - - 通过不同行为强制工具使用（`examples/agent_patterns/forcing_tool_use.py`） + - 条件式工具使用 + - 以不同行为强制使用工具（`examples/agent_patterns/forcing_tool_use.py`） - 输入/输出安全防护措施 - - LLM 作为裁判 + - LLM作为评审者 - 路由 - - 流式安全防护措施 - - 带工具审批与状态序列化的人在回路（`examples/agent_patterns/human_in_the_loop.py`） - - 带流式传输的人在回路（`examples/agent_patterns/human_in_the_loop_stream.py`） + - 流式传输安全防护措施 + - 具备工具审批和状态序列化的人在回路（`examples/agent_patterns/human_in_the_loop.py`） + - 具备流式传输的人在回路（`examples/agent_patterns/human_in_the_loop_stream.py`） - 审批流程的自定义拒绝消息（`examples/agent_patterns/human_in_the_loop_custom_rejection.py`） - **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):** - 这些示例展示了 SDK 的基础能力，例如 + 这些示例展示 SDK 的基础能力，例如 - - Hello World 示例（默认模型、GPT-5、开放权重模型） + - Hello world示例（默认模型、GPT-5、开放权重模型） - 智能体生命周期管理 - - Run hooks 和 agent hooks 生命周期示例（`examples/basic/lifecycle_example.py`） + - 运行钩子和智能体钩子的生命周期示例（`examples/basic/lifecycle_example.py`） - 动态系统提示词 - - 基础工具使用（`examples/basic/tools.py`） + - 基本工具使用（`examples/basic/tools.py`） - 工具输入/输出安全防护措施（`examples/basic/tool_guardrails.py`） - 图像工具输出（`examples/basic/image_tool_output.py`） - - 流式输出（文本、条目、函数调用参数） - - 跨轮次共享会话助手的 Responses websocket 传输（`examples/basic/stream_ws.py`） + - 流式传输输出（文本、项、函数调用参数） + - Responses WebSocket 传输，以及跨轮次共享的会话辅助工具（`examples/basic/stream_ws.py`） - 提示词模板 - - 文件处理（本地与远程、图像与 PDF） - - 用量追踪 - - 由 Runner 管理的重试设置（`examples/basic/retry.py`） - - 通过第三方适配器由 Runner 管理重试（`examples/basic/retry_litellm.py`） + - 文件处理（本地和远程、图像和 PDF） + - 用量跟踪 + - Runner 管理的重试设置（`examples/basic/retry.py`） + - 通过第三方适配器由 Runner 管理的重试（`examples/basic/retry_litellm.py`） - 非严格输出类型 - - previous response 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):** - 智能体任务转移的实用示例，包含消息过滤，包括： + 智能体任务转移的实践示例，包含消息过滤，包括： - - 消息过滤示例（`examples/handoffs/message_filter.py`） - - 带流式传输的消息过滤（`examples/handoffs/message_filter_streaming.py`） + - 消息过滤器示例（`examples/handoffs/message_filter.py`） + - 带流式传输的消息过滤器（`examples/handoffs/message_filter_streaming.py`） - **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):** - 展示如何将托管 MCP（Model context protocol）与 OpenAI Responses API 一起使用的示例，包括： + 展示如何将托管 MCP（Model Context Protocol）与 OpenAI Responses API 配合使用的示例，包括： - 无需审批的简单托管 MCP（`examples/hosted_mcp/simple.py`） - MCP 连接器，例如 Google Calendar（`examples/hosted_mcp/connectors.py`） - - 基于中断审批的人在回路（`examples/hosted_mcp/human_in_the_loop.py`） - - MCP 工具调用的审批回调（`examples/hosted_mcp/on_approval.py`） + - 具备基于中断的审批的人在回路（`examples/hosted_mcp/human_in_the_loop.py`） + - MCP 工具调用的审批通过回调（`examples/hosted_mcp/on_approval.py`） - **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):** - 了解如何使用 MCP（Model context protocol）构建智能体，包括： + 了解如何使用 MCP（Model Context Protocol）构建智能体，包括： - 文件系统示例 - Git 示例 - - MCP prompt 服务示例 - - SSE（服务器发送事件）示例 + - MCP 提示词服务示例 + - SSE（Server-Sent Events）示例 - SSE 远程服务连接（`examples/mcp/sse_remote_example`） - Streamable HTTP 示例 - Streamable HTTP 远程连接（`examples/mcp/streamable_http_remote_example`） - 用于 Streamable HTTP 的自定义 HTTP 客户端工厂（`examples/mcp/streamablehttp_custom_client_example`） - - 使用 `MCPUtil.get_all_function_tools` 预获取所有 MCP 工具（`examples/mcp/get_all_mcp_tools_example`） - - 搭配 FastAPI 的 MCPServerManager（`examples/mcp/manager_example`） + - 使用 `MCPUtil.get_all_function_tools` 预取所有 MCP 工具（`examples/mcp/get_all_mcp_tools_example`） + - MCPServerManager 与 FastAPI（`examples/mcp/manager_example`） - MCP 工具过滤（`examples/mcp/tool_filter_example`） - **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):** - 面向智能体的不同内存实现示例，包括： + 智能体不同记忆实现的示例，包括： - SQLite 会话存储 - 高级 SQLite 会话存储 @@ -93,46 +93,46 @@ search: - OpenAI Conversations 会话存储 - Responses 压缩会话存储 - 使用 `ModelSettings(store=False)` 的无状态 Responses 压缩（`examples/memory/compaction_session_stateless_example.py`） - - 文件后端会话存储（`examples/memory/file_session.py`） - - 带人在回路的文件后端会话（`examples/memory/file_hitl_example.py`） - - 带人在回路的 SQLite 内存会话（`examples/memory/memory_session_hitl_example.py`） - - 带人在回路的 OpenAI Conversations 会话（`examples/memory/openai_session_hitl_example.py`） + - 基于文件的会话存储（`examples/memory/file_session.py`） + - 具备人在回路的基于文件的会话（`examples/memory/file_hitl_example.py`） + - 具备人在回路的 SQLite 内存会话（`examples/memory/memory_session_hitl_example.py`） + - 具备人在回路的 OpenAI Conversations 会话（`examples/memory/openai_session_hitl_example.py`） - 跨会话的 HITL 审批/拒绝场景（`examples/memory/hitl_session_scenario.py`） - **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):** - 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和第三方适配器。 + 探索如何将非 OpenAI 模型与 SDK 配合使用，包括自定义提供商和第三方适配器。 - **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):** 展示如何使用 SDK 构建实时体验的示例，包括： - - 使用结构化文本和图像消息的 Web 应用模式 - - 命令行音频循环与播放处理 + - 包含结构化文本和图像消息的 Web 应用模式 + - 命令行音频循环和播放处理 - 基于 WebSocket 的 Twilio Media Streams 集成 - - 使用 Realtime Calls API attach 流程的 Twilio SIP 集成 + - 使用 Realtime Calls API 附加流程的 Twilio SIP 集成 - **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):** 展示如何处理推理内容的示例，包括： - - 使用 Runner API 的推理内容，含流式和非流式（`examples/reasoning_content/runner_example.py`） - - 通过 OpenRouter 使用 OSS 模型的推理内容（`examples/reasoning_content/gpt_oss_stream.py`） + - 通过 Runner API 处理推理内容，支持流式传输和非流式传输（`examples/reasoning_content/runner_example.py`） + - 通过 OpenRouter 使用 OSS 模型处理推理内容（`examples/reasoning_content/gpt_oss_stream.py`） - 基础推理内容示例（`examples/reasoning_content/main.py`） - **[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托管的工具和实验性 Codex 工具能力，例如： + 了解如何实现由OpenAI托管的工具以及实验性 Codex 工具，例如： - - 网络检索以及带过滤器的网络检索 + - 网络检索，以及带过滤器的网络检索 - 文件检索 - - Code Interpreter - - 带文件编辑与审批的 apply patch 工具（`examples/tools/apply_patch.py`） - - 带审批回调的 shell 工具执行（`examples/tools/shell.py`） - - 带基于中断审批的人在回路 shell 工具（`examples/tools/shell_human_in_the_loop.py`） + - Code interpreter + - Apply patch 工具，包含文件编辑和审批（`examples/tools/apply_patch.py`） + - 带审批回调的 Shell 工具执行（`examples/tools/shell.py`） + - 具备人在回路基于中断审批的 Shell 工具（`examples/tools/shell_human_in_the_loop.py`） - 带内联技能的托管容器 shell（`examples/tools/container_shell_inline_skill.py`） - 带技能引用的托管容器 shell（`examples/tools/container_shell_skill_reference.py`） - 带本地技能的本地 shell（`examples/tools/local_shell_skill.py`） - - 带命名空间和延迟工具的工具搜索（`examples/tools/tool_search.py`） + - 具有命名空间和延迟工具的工具搜索（`examples/tools/tool_search.py`） - 计算机操作 - 图像生成 - 实验性 Codex 工具工作流（`examples/tools/codex.py`） diff --git a/docs/zh/guardrails.md b/docs/zh/guardrails.md index 63aa2acb63..a8a7d92a5b 100644 --- a/docs/zh/guardrails.md +++ b/docs/zh/guardrails.md @@ -4,74 +4,74 @@ search: --- # 安全防护措施 -安全防护措施让你能够对用户输入和智能体输出进行检查与校验。比如，假设你有一个智能体，使用一个非常智能（因此也较慢/昂贵）的模型来帮助处理客户请求。你肯定不希望恶意用户让这个模型帮他们做数学作业。因此，你可以先用一个快速/便宜的模型运行安全防护措施。如果安全防护措施检测到恶意使用，它可以立即抛出错误并阻止昂贵模型运行，从而节省时间和成本（**在使用阻塞式安全防护措施时；对于并行安全防护措施，昂贵模型可能在安全防护措施完成前就已经开始运行。详情见下方“执行模式”**）。 +安全防护措施使你能够对用户输入和智能体输出进行检查与验证。例如，假设你有一个智能体使用一个非常智能（因此速度慢/成本高）的模型来帮助处理客户请求。你不会希望恶意用户要求模型帮他们做数学作业。因此，你可以用一个快速/低成本的模型运行安全防护措施。如果安全防护措施检测到恶意使用，它可以立即引发错误并阻止高成本模型运行，从而为你节省时间和费用（**当使用阻塞式安全防护措施时；对于并行安全防护措施，高成本模型可能在安全防护措施完成之前就已经开始运行。详情请参见下方“执行模式”**）。 安全防护措施有两种： -1. 输入安全防护措施：作用于初始用户输入 -2. 输出安全防护措施：作用于最终智能体输出 +1. 输入安全防护措施在初始用户输入上运行 +2. 输出安全防护措施在最终智能体输出上运行 ## 工作流边界 -安全防护措施会附加在智能体和工具上，但它们在工作流中的运行时机并不相同： +安全防护措施会附加到智能体和工具上，但它们并不会都在工作流中的相同节点运行： -- **输入安全防护措施**仅对链路中的第一个智能体运行。 -- **输出安全防护措施**仅对产出最终输出的智能体运行。 -- **工具安全防护措施**会在每次自定义 function-tool 调用时运行，执行前运行输入安全防护措施，执行后运行输出安全防护措施。 +- **输入安全防护措施**仅对链中的第一个智能体运行。 +- **输出安全防护措施**仅对生成最终输出的智能体运行。 +- **工具安全防护措施**会在每次自定义工具调用调用时运行，其中输入安全防护措施在执行前运行，输出安全防护措施在执行后运行。 -如果你的工作流包含管理者、任务转移或被委派的专家，并且需要围绕每次自定义 function-tool 调用做检查，请使用工具安全防护措施，而不要只依赖智能体级别的输入/输出安全防护措施。 +如果你需要在包含管理器、任务转移或委派专家的工作流中围绕每次自定义工具调用进行检查，请使用工具安全防护措施，而不是只依赖智能体级别的输入/输出安全防护措施。 ## 输入安全防护措施 输入安全防护措施分 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`？这是因为安全防护措施通常与具体的 Agent 相关——不同智能体通常会使用不同的安全防护措施，把代码就近放置有助于提升可读性。 + 输入安全防护措施旨在针对用户输入运行，因此只有当某个智能体是*第一个*智能体时，该智能体的安全防护措施才会运行。你可能会疑惑，为什么 `guardrails` 属性是在智能体上，而不是传给 `Runner.run`？这是因为安全防护措施往往与实际的 Agent 相关——你会为不同的智能体运行不同的安全防护措施，因此将代码放在一起有助于提升可读性。 ### 执行模式 输入安全防护措施支持两种执行模式： -- **并行执行**（默认，`run_in_parallel=True`）：安全防护措施与智能体执行并发运行。由于两者同时开始，这能提供最佳延迟表现。不过，如果安全防护措施失败，智能体在被取消前可能已经消耗了 token 并执行了工具调用。 +- **并行执行**（默认，`run_in_parallel=True`）：安全防护措施与智能体的执行并发运行。由于二者同时启动，这可以提供最佳延迟表现。不过，如果安全防护措施失败，智能体在被取消之前可能已经消耗了 token 并执行了工具。 -- **阻塞执行**（`run_in_parallel=False`）：安全防护措施会在智能体启动*之前*运行并完成。如果触发了安全防护触发器，智能体将不会执行，从而避免 token 消耗和工具执行。这非常适合成本优化，以及你希望避免工具调用潜在副作用的场景。 +- **阻塞式执行**（`run_in_parallel=False`）：安全防护措施会在智能体启动*之前*运行并完成。如果安全防护措施的触发线被触发，智能体将永远不会执行，从而避免 token 消耗和工具执行。这非常适合成本优化，以及当你希望避免工具调用可能产生的副作用时。 ## 输出安全防护措施 输出安全防护措施分 3 步运行： -1. 首先，安全防护措施接收智能体生成的输出。 -2. 接着，运行安全防护函数，产出一个 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后被封装为 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] -3. 最后，我们检查 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] 是否为 true。若为 true，会抛出 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 异常，以便你恰当地响应用户或处理异常。 +1. 首先，安全防护措施会接收智能体生成的输出。 +2. 接着，安全防护措施函数运行并生成一个 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]，随后它会被包装在 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] 中 +3. 最后，我们检查 [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] 是否为 true。如果为 true，则会引发 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 异常，因此你可以适当地回应用户或处理该异常。 !!! Note - 输出安全防护措施旨在作用于最终智能体输出，因此只有当该智能体是*最后一个*智能体时，它的安全防护措施才会运行。与输入安全防护措施类似，这样设计是因为安全防护措施通常与具体 Agent 相关——不同智能体通常会使用不同的安全防护措施，把代码就近放置有助于提升可读性。 + 输出安全防护措施旨在针对最终智能体输出运行，因此只有当某个智能体是*最后一个*智能体时，该智能体的安全防护措施才会运行。与输入安全防护措施类似，我们这样做是因为安全防护措施往往与实际的 Agent 相关——你会为不同的智能体运行不同的安全防护措施，因此将代码放在一起有助于提升可读性。 - 输出安全防护措施总是在智能体完成后运行，因此不支持 `run_in_parallel` 参数。 + 输出安全防护措施始终在智能体完成后运行，因此它们不支持 `run_in_parallel` 参数。 ## 工具安全防护措施 -工具安全防护措施会包裹**工具调用**，让你能够在执行前后校验或拦截工具调用。它们配置在工具本身上，并在每次调用该工具时运行。 +工具安全防护措施会包装**工具调用**，并让你在执行前后验证或阻止工具调用。它们配置在工具本身上，并在每次调用该工具时运行。 -- 输入工具安全防护措施在工具执行前运行，可跳过调用、用一条消息替换输出，或抛出触发器。 -- 输出工具安全防护措施在工具执行后运行，可替换输出或抛出触发器。 -- 工具安全防护措施仅适用于通过 [`function_tool`][agents.tool.function_tool] 创建的 function tools。任务转移通过 SDK 的 handoff 管线运行，而不是普通 function-tool 管线，因此工具安全防护措施不适用于任务转移调用本身。托管工具（`WebSearchTool`、`FileSearchTool`、`HostedMCPTool`、`CodeInterpreterTool`、`ImageGenerationTool`）和内置执行工具（`ComputerTool`、`ShellTool`、`ApplyPatchTool`、`LocalShellTool`）也不使用这条安全防护措施管线，且 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 目前也不直接暴露工具安全防护措施选项。 +- 输入工具安全防护措施在工具执行前运行，可以跳过调用、用一条消息替换输出，或引发触发线。 +- 输出工具安全防护措施在工具执行后运行，可以替换输出或引发触发线。 +- 工具安全防护措施仅适用于使用 [`function_tool`][agents.tool.function_tool] 创建的工具调用。任务转移会通过 SDK 的任务转移流水线运行，而不是普通的工具调用流水线，因此工具安全防护措施不适用于任务转移调用本身。托管工具（`WebSearchTool`、`FileSearchTool`、`HostedMCPTool`、`CodeInterpreterTool`、`ImageGenerationTool`）和内置执行工具（`ComputerTool`、`ShellTool`、`ApplyPatchTool`、`LocalShellTool`）也不使用此安全防护措施流水线，并且 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 目前也不会直接公开工具安全防护措施选项。 -详情见下方代码片段。 +详情请参见下方代码片段。 -## 触发器 +## 触发线 -如果输入或输出未通过安全防护措施，安全防护措施可通过触发器发出信号。一旦检测到某个安全防护措施触发了触发器，我们会立即抛出 `{Input,Output}GuardrailTripwireTriggered` 异常并终止智能体执行。 +如果输入或输出未通过安全防护措施，Guardrail 可以通过触发线来发出信号。一旦我们发现某个安全防护措施触发了触发线，就会立即引发 `{Input,Output}GuardrailTripwireTriggered` 异常，并停止 Agent 执行。 ## 安全防护措施实现 -你需要提供一个函数来接收输入，并返回一个 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]。在这个示例中，我们会通过在底层运行一个智能体来实现。 +你需要提供一个接收输入并返回 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] 的函数。在此示例中，我们将通过在底层运行一个 Agent 来实现这一点。 ```python from pydantic import BaseModel @@ -124,10 +124,10 @@ async def main(): print("Math homework guardrail tripped") ``` -1. 我们会在安全防护函数中使用这个智能体。 -2. 这是安全防护函数，它接收智能体的输入/上下文，并返回结果。 -3. 我们可以在安全防护结果中包含额外信息。 -4. 这是真正定义工作流的智能体。 +1. 我们将在安全防护措施函数中使用此智能体。 +2. 这是接收智能体输入/上下文并返回结果的安全防护措施函数。 +3. 我们可以在安全防护措施结果中包含额外信息。 +4. 这是定义工作流的实际智能体。 输出安全防护措施类似。 @@ -184,10 +184,10 @@ async def main(): 1. 这是实际智能体的输出类型。 2. 这是安全防护措施的输出类型。 -3. 这是安全防护函数，它接收智能体的输出，并返回结果。 -4. 这是真正定义工作流的智能体。 +3. 这是接收智能体输出并返回结果的安全防护措施函数。 +4. 这是定义工作流的实际智能体。 -最后，这里是工具安全防护措施的示例。 +最后，下面是一些工具安全防护措施的代码示例。 ```python import json diff --git a/docs/zh/handoffs.md b/docs/zh/handoffs.md index 8d0d627ba0..4eef128027 100644 --- a/docs/zh/handoffs.md +++ b/docs/zh/handoffs.md @@ -4,21 +4,21 @@ search: --- # 任务转移 -任务转移允许一个智能体将任务委派给另一个智能体。这在不同智能体专注于不同领域的场景中特别有用。例如，一个客户支持应用可能会有多个智能体，分别专门处理订单状态、退款、常见问题等任务。 +任务转移允许一个智能体将任务委派给另一个智能体。这在不同智能体专长于不同领域的场景中特别有用。例如，客服应用可能有多个智能体，分别专门处理订单状态、退款、FAQ 等任务。 -任务转移会作为工具呈现给 LLM。因此，如果有一个转移目标是名为 `Refund Agent` 的智能体，那么该工具名称会是 `transfer_to_refund_agent`。 +任务转移会作为工具呈现给 LLM。因此，如果存在一个转移到名为 `Refund Agent` 的智能体的任务转移，该工具会被称为 `transfer_to_refund_agent`。 -## 创建任务转移 +## 任务转移的创建 所有智能体都有一个 [`handoffs`][agents.agent.Agent.handoffs] 参数，它既可以直接接收一个 `Agent`，也可以接收一个用于自定义任务转移的 `Handoff` 对象。 -如果你传入普通的 `Agent` 实例，它们的 [`handoff_description`][agents.agent.Agent.handoff_description]（设置时）会附加到默认工具描述中。你可以用它提示模型何时应选择该任务转移，而无需编写完整的 `handoff()` 对象。 +如果传入普通的 `Agent` 实例，它们的 [`handoff_description`][agents.agent.Agent.handoff_description]（如果已设置）会追加到默认工具描述中。可以使用它来提示模型应在何时选择该任务转移，而无需编写完整的 `handoff()` 对象。 -你可以使用 Agents SDK 提供的 [`handoff()`][agents.handoffs.handoff] 函数创建任务转移。该函数允许你指定要转移到的智能体，以及可选的覆盖项和输入过滤器。 +你可以使用 Agents SDK 提供的 [`handoff()`][agents.handoffs.handoff] 函数创建任务转移。此函数允许你指定要转移到的智能体，并提供可选的覆盖项和输入过滤器。 ### 基本用法 -下面是创建一个简单任务转移的方法： +下面是创建简单任务转移的方法： ```python from agents import Agent, handoff @@ -32,20 +32,20 @@ triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refun 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`：任务转移工具调用参数的 schema。设置后，解析后的负载会传递给 `on_handoff`。 -- `input_filter`：允许你过滤下一个智能体接收到的输入。详见下文。 -- `is_enabled`：任务转移是否启用。可以是布尔值，也可以是返回布尔值的函数，从而允许你在运行时动态启用或禁用任务转移。 -- `nest_handoff_history`：对 RunConfig 级别 `nest_handoff_history` 设置的可选单次调用覆盖项。如果为 `None`，则改用当前运行配置中定义的值。 +- `agent`: 这是任务将被转移到的智能体。 +- `tool_name_override`: 默认使用 `Handoff.default_tool_name()` 函数，其结果为 `transfer_to_`。你可以覆盖此项。 +- `tool_description_override`: 覆盖来自 `Handoff.default_tool_description()` 的默认工具描述 +- `on_handoff`: 在任务转移被调用时执行的回调函数。当你知道任务转移正在被调用时，需要立即启动某些数据获取等操作，这会很有用。此函数接收智能体上下文，并且也可以选择接收由 LLM 生成的输入。输入数据由 `input_type` 参数控制。 +- `input_type`: 任务转移工具调用参数的模式。设置后，解析后的载荷会传递给 `on_handoff`。 +- `input_filter`: 可用于过滤下一个智能体接收的输入。更多信息见下文。 +- `is_enabled`: 任务转移是否启用。它可以是布尔值，或返回布尔值的函数，从而允许你在运行时动态启用或禁用该任务转移。 +- `nest_handoff_history`: 用于覆盖 RunConfig 级别 `nest_handoff_history` 设置的可选单次调用配置。如果为 `None`，则改用当前生效运行配置中定义的值。 -[`handoff()`][agents.handoffs.handoff] 辅助函数始终将控制权转移到你传入的特定 `agent`。如果你有多个可能的目标，请为每个目标注册一个任务转移，并让模型在它们之间选择。仅当你自己的任务转移代码必须在调用时决定返回哪个智能体时，才使用自定义 [`Handoff`][agents.handoffs.Handoff]。 +[`handoff()`][agents.handoffs.handoff] 辅助函数始终将控制权转移给你传入的特定 `agent`。如果有多个可能的目标，请为每个目标注册一个任务转移，并让模型在其中选择。只有当你自己的任务转移代码必须在调用时决定返回哪个智能体时，才使用自定义 [`Handoff`][agents.handoffs.Handoff]。 ```python from agents import Agent, handoff, RunContextWrapper @@ -65,7 +65,7 @@ handoff_obj = handoff( ## 任务转移输入 -在某些情况下，你会希望 LLM 在调用任务转移时提供一些数据。例如，设想有一个到“升级处理智能体”的任务转移。你可能希望提供原因，以便记录日志。 +在某些情况下，你希望 LLM 在调用任务转移时提供一些数据。例如，设想一个转移到“升级智能体”的任务转移。你可能希望提供一个原因，以便记录它。 ```python from pydantic import BaseModel @@ -87,44 +87,44 @@ handoff_obj = handoff( ) ``` -`input_type` 描述的是任务转移工具调用本身的参数。SDK 会将该 schema 作为任务转移工具的 `parameters` 暴露给模型，在本地校验返回的 JSON，并将解析后的值传递给 `on_handoff`。 +`input_type` 描述任务转移工具调用本身的参数。SDK 会将该模式作为任务转移工具的 `parameters` 暴露给模型，在本地验证返回的 JSON，并将解析后的值传递给 `on_handoff`。 -它不会替代下一个智能体的主输入，也不会选择不同的目标。[`handoff()`][agents.handoffs.handoff] 辅助函数仍会转移到你封装的特定智能体，接收方智能体仍会看到对话历史，除非你通过 [`input_filter`][agents.handoffs.Handoff.input_filter] 或嵌套任务转移历史设置进行更改。 +它不会替换下一个智能体的主输入，也不会选择不同的目标。[`handoff()`][agents.handoffs.handoff] 辅助函数仍会转移到你包装的特定智能体，并且接收方智能体仍会看到对话历史，除非你使用 [`input_filter`][agents.handoffs.Handoff.input_filter] 或嵌套任务转移历史设置来更改它。 -`input_type` 也独立于 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]。`input_type` 适用于模型在任务转移时决定的元数据，而不是你本地已存在的应用状态或依赖项。 +`input_type` 也不同于 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]。请将 `input_type` 用于模型在任务转移时决定的元数据，而不是用于你在本地已有的应用状态或依赖项。 -### 何时使用 `input_type` +### `input_type` 的使用场景 -当任务转移需要一小段由模型生成的元数据（如 `reason`、`language`、`priority` 或 `summary`）时，使用 `input_type`。例如，分流智能体可以将任务转移给退款智能体并附带 `{ "reason": "duplicate_charge", "priority": "high" }`，而 `on_handoff` 可以在退款智能体接管前记录或持久化该元数据。 +当任务转移需要一小段由模型生成的元数据（例如 `reason`、`language`、`priority` 或 `summary`）时，使用 `input_type`。例如，分流智能体可以使用 `{ "reason": "duplicate_charge", "priority": "high" }` 转移给退款智能体，而 `on_handoff` 可以在退款智能体接管之前记录或持久化该元数据。 -当目标不同，请选择其他机制： +当目标不同时，请选择其他机制： -- 将现有应用状态和依赖项放入 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]。参见[上下文指南](context.md)。 -- 如果你想更改接收方智能体能看到的历史，使用 [`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 或 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]。 -- 如果存在多个可能的专家目标，为每个目标注册一个任务转移。`input_type` 可以为已选任务转移添加元数据，但不会在目标之间分发。 -- 如果你想为嵌套专家提供 structured outputs 输入而不转移对话，优先使用 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]。参见 [tools](tools.md#structured-input-for-tool-agents)。 +- 将已有的应用状态和依赖项放入 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]。请参阅[上下文指南](context.md)。 +- 如果你想更改接收方智能体看到的历史，请使用 [`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 或 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]。 +- 如果存在多个可能的专业智能体，请为每个目标注册一个任务转移。`input_type` 可以向所选任务转移添加元数据，但不会在各目标之间进行分派。 +- 如果你希望为嵌套的专业智能体提供结构化输入，而不转移对话，请优先使用 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]。请参阅[工具](tools.md#structured-input-for-tool-agents)。 ## 输入过滤器 -当发生任务转移时，就好像新智能体接管了对话，并能看到此前完整的对话历史。如果你想改变这一点，可以设置 [`input_filter`][agents.handoffs.Handoff.input_filter]。输入过滤器是一个函数，它通过 [`HandoffInputData`][agents.handoffs.HandoffInputData] 接收现有输入，并且必须返回一个新的 `HandoffInputData`。 +当发生任务转移时，就像新的智能体接管对话一样，它可以看到此前完整的对话历史。如果你想更改这一点，可以设置 [`input_filter`][agents.handoffs.Handoff.input_filter]。输入过滤器是一个通过 [`HandoffInputData`][agents.handoffs.HandoffInputData] 接收现有输入的函数，并且必须返回新的 `HandoffInputData`。 -[`HandoffInputData`][agents.handoffs.HandoffInputData] 包含： +[`HandoffInputData`][agents.handoffs.HandoffInputData] 包括： -- `input_history`：`Runner.run(...)` 开始前的输入历史。 -- `pre_handoff_items`：调用任务转移的智能体轮次之前生成的条目。 -- `new_items`：当前轮次中生成的条目，包括任务转移调用和任务转移输出条目。 -- `input_items`：可选项；可转发给下一个智能体以替代 `new_items`，从而在保留用于会话历史的 `new_items` 不变的同时过滤模型输入。 -- `run_context`：调用任务转移时处于激活状态的 [`RunContextWrapper`][agents.run_context.RunContextWrapper]。 +- `input_history`: `Runner.run(...)` 启动之前的输入历史。 +- `pre_handoff_items`: 在调用任务转移的智能体轮次之前生成的项。 +- `new_items`: 当前轮次期间生成的项，包括任务转移调用和任务转移输出项。 +- `input_items`: 可选项，用于转发给下一个智能体以替代 `new_items`，使你能够过滤模型输入，同时保持 `new_items` 在会话历史中不变。 +- `run_context`: 任务转移被调用时处于活动状态的 [`RunContextWrapper`][agents.run_context.RunContextWrapper]。 -嵌套任务转移作为可选启用的 beta 功能提供，默认关闭，直到我们将其稳定化。启用 [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 后，runner 会将先前的对话记录折叠为一条 assistant 摘要消息，并将其包装在 `` 块中；当同一次运行中发生多次任务转移时，该块会持续追加新轮次。你可以通过 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 提供自己的映射函数来替换自动生成的消息，而无需编写完整的 `input_filter`。仅当任务转移和运行都未提供显式 `input_filter` 时，此可选启用才会生效，因此已自定义负载的现有代码（包括本仓库中的代码示例）无需变更即可保持当前行为。你可以在 [`handoff(...)`][agents.handoffs.handoff] 中传入 `nest_handoff_history=True` 或 `False` 来覆盖单次任务转移的嵌套行为，这会设置 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]。如果你只需要修改生成摘要的包装文本，请在运行智能体前调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及可选的 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 +嵌套任务转移以可选择启用的 beta 形式提供，在我们稳定该功能期间默认禁用。当你启用 [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 时，运行器会将先前的对话记录折叠为一条助手摘要消息，并将其包装在 `` 块中；当同一次运行中发生多次任务转移时，该块会持续追加新的轮次。你可以通过 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 提供自己的映射函数来替换生成的消息，而无需编写完整的 `input_filter`。只有在任务转移和运行都没有提供显式 `input_filter` 时，此可选启用机制才会生效，因此已经自定义载荷的现有代码（包括本仓库中的代码示例）会保持当前行为，无需更改。你可以通过向 [`handoff(...)`][agents.handoffs.handoff] 传入 `nest_handoff_history=True` 或 `False` 来覆盖单个任务转移的嵌套行为，这会设置 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]。如果你只需要更改生成摘要的包装文本，请在运行智能体之前调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（也可选择调用 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。 -如果任务转移和当前激活的 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] 都定义了过滤器，则该特定任务转移的每任务转移 [`input_filter`][agents.handoffs.Handoff.input_filter] 优先。 +如果任务转移和当前生效的 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] 都定义了过滤器，则针对该特定任务转移，任务转移级别的 [`input_filter`][agents.handoffs.Handoff.input_filter] 优先。 !!! note - 任务转移会保持在单次运行内。输入安全防护措施仍仅适用于链路中的第一个智能体，输出安全防护措施仅适用于产生最终输出的智能体。当你需要在工作流中每次自定义工具调用周围进行检查时，请使用工具安全防护措施。 + 任务转移会停留在单次运行内。输入安全防护措施仍然只应用于链路中的第一个智能体，输出安全防护措施也只应用于生成最终输出的智能体。当你需要围绕工作流中的每个自定义函数工具调用进行检查时，请使用工具安全防护措施。 -有一些常见模式（例如从历史中移除所有工具调用）已在 [`agents.extensions.handoff_filters`][] 中为你实现。 +有一些常见模式（例如从历史中移除所有工具调用），已在 [`agents.extensions.handoff_filters`][] 中为你实现 ```python from agents import Agent, handoff @@ -138,11 +138,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`][]，将推荐内容自动添加到你的提示词中。 +为了确保 LLMs 能够正确理解任务转移，我们建议在你的智能体中包含有关任务转移的信息。我们在 [`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/human_in_the_loop.md b/docs/zh/human_in_the_loop.md index f7b9e30da0..ff5c8163e3 100644 --- a/docs/zh/human_in_the_loop.md +++ b/docs/zh/human_in_the_loop.md @@ -2,19 +2,19 @@ search: exclude: true --- -# 人在回路中 +# 人在回路 -使用人在回路（HITL）流程，在人员批准或拒绝敏感工具调用之前暂停智能体执行。工具会声明何时需要审批，运行结果会将待审批项作为中断暴露出来，而 `RunState` 允许你在决策完成后序列化并恢复运行。 +使用人在回路（HITL）流程暂停智能体执行，直到有人批准或拒绝敏感工具调用。工具会声明何时需要审批，运行结果会以中断形式呈现待处理审批，而 `RunState` 让你能够在做出决策后序列化并恢复运行。 -该审批界面是运行级别的，不仅限于当前顶层智能体。无论工具属于当前智能体、属于通过任务转移到达的智能体，还是属于嵌套的 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 执行，都采用同一种模式。在嵌套 `Agent.as_tool()` 的情况下，中断仍会出现在外层运行上，因此你应在外层 `RunState` 上进行批准或拒绝，并恢复原始顶层运行。 +该审批机制作用于整个运行，而不仅限于当前的顶层智能体。当工具属于当前智能体、属于通过任务转移到达的智能体，或属于嵌套的 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 执行时，都适用同一模式。在嵌套 `Agent.as_tool()` 的情况下，中断仍会呈现在外层运行上，因此你需要在外层 `RunState` 上批准或拒绝它，并恢复原始的顶层运行。 -使用 `Agent.as_tool()` 时，审批可能发生在两个不同层级：智能体工具本身可通过 `Agent.as_tool(..., needs_approval=...)` 要求审批；嵌套智能体内部的工具在嵌套运行开始后也可能触发各自审批。这两类都通过同一个外层运行中断流程处理。 +使用 `Agent.as_tool()` 时，审批可能发生在两个不同层级：智能体工具本身可以通过 `Agent.as_tool(..., needs_approval=...)` 要求审批，而嵌套智能体内的工具也可以在嵌套运行开始后再发起自己的审批请求。两者都通过相同的外层运行中断流程处理。 -本页重点介绍通过 `interruptions` 的手动审批流程。如果你的应用可以在代码中做决策，某些工具类型也支持编程式审批回调，使运行无需暂停即可继续。 +本页重点介绍通过 `interruptions` 进行的手动审批流程。如果你的应用可以在代码中做出决策，某些工具类型还支持程序化审批回调，使运行无需暂停即可继续。 ## 需要审批的工具标记 -将 `needs_approval` 设为 `True` 可始终要求审批，或提供一个异步函数按调用逐次决定。该可调用对象会接收运行上下文、解析后的工具参数以及工具调用 ID。 +将 `needs_approval` 设置为 `True` 可始终要求审批，或提供一个按调用进行决策的异步函数。该可调用对象会接收运行上下文、已解析的工具参数以及工具调用 ID。 ```python from agents import Agent, Runner, function_tool @@ -41,28 +41,28 @@ agent = Agent( ) ``` -`needs_approval` 可用于 [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool] 和 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]。本地 MCP 服务也支持通过 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse] 和 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 上的 `require_approval` 进行审批。托管 MCP 服务可通过 [`HostedMCPTool`][agents.tool.HostedMCPTool] 配置 `tool_config={"require_approval": "always"}` 支持审批，并可选提供 `on_approval_request` 回调。Shell 和 apply_patch 工具接受 `on_approval` 回调，用于在不暴露中断的情况下自动批准或自动拒绝。 +`needs_approval` 可用于 [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool] 和 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]。本地 MCP 服务也支持通过 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse] 和 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 上的 `require_approval` 进行审批。托管 MCP 服务支持通过 [`HostedMCPTool`][agents.tool.HostedMCPTool] 以及 `tool_config={"require_approval": "always"}` 和可选的 `on_approval_request` 回调进行审批。如果你想在不呈现中断的情况下自动批准或自动拒绝，Shell 和 apply_patch 工具接受 `on_approval` 回调。 ## 审批流程机制 -1. 当模型发出工具调用时，运行器会评估其审批规则（`needs_approval`、`require_approval` 或托管 MCP 的等效配置）。 -2. 如果该工具调用的审批决定已存储在 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 中，运行器将不再提示而直接继续。按调用的审批仅作用于特定调用 ID；传入 `always_approve=True` 或 `always_reject=True` 可将同一决定持久化到本次运行后续对该工具的调用。 -3. 否则，执行会暂停，且 `RunResult.interruptions`（或 `RunResultStreaming.interruptions`）会包含 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 条目，其中含有 `agent.name`、`tool_name`、`arguments` 等细节。这也包括在任务转移之后或嵌套 `Agent.as_tool()` 执行内部触发的审批。 -4. 通过 `result.to_state()` 将结果转为 `RunState`，调用 `state.approve(...)` 或 `state.reject(...)`，然后用 `Runner.run(agent, state)` 或 `Runner.run_streamed(agent, state)` 恢复，其中 `agent` 是该运行的原始顶层智能体。 -5. 恢复后的运行会从中断处继续；若需要新的审批，将再次进入该流程。 +1. 当模型发出工具调用时，运行器会评估其审批规则（`needs_approval`、`require_approval` 或托管 MCP 的等效机制）。 +2. 如果该工具调用的审批决策已存储在 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 中，运行器会继续执行而不提示。按调用的审批作用域限定在特定调用 ID；传入 `always_approve=True` 或 `always_reject=True` 可在运行的剩余过程中，为该工具后续调用持久保留同一决策。 +3. 否则，执行会暂停，并且 `RunResult.interruptions`（或 `RunResultStreaming.interruptions`）会包含 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 条目，其中包含 `agent.name`、`tool_name` 和 `arguments` 等详细信息。这包括在任务转移之后或嵌套 `Agent.as_tool()` 执行内部发起的审批。 +4. 使用 `result.to_state()` 将结果转换为 `RunState`，调用 `state.approve(...)` 或 `state.reject(...)`，然后使用 `Runner.run(agent, state)` 或 `Runner.run_streamed(agent, state)` 恢复，其中 `agent` 是该运行的原始顶层智能体。 +5. 恢复后的运行会从暂停处继续，并且如果需要新的审批，将再次进入此流程。 -通过 `always_approve=True` 或 `always_reject=True` 创建的粘性决策会保存在运行状态中，因此在你稍后恢复同一已暂停运行时，它们会在 `state.to_string()` / `RunState.from_string(...)` 与 `state.to_json()` / `RunState.from_json(...)` 之间保留。 +使用 `always_approve=True` 或 `always_reject=True` 创建的持续性决策会存储在运行状态中，因此当你稍后恢复同一个已暂停运行时，它们会在 `state.to_string()` / `RunState.from_string(...)` 和 `state.to_json()` / `RunState.from_json(...)` 之间保留。 -你不需要在同一轮中解决所有待审批项。`interruptions` 可以同时包含常规函数工具、托管 MCP 审批以及嵌套 `Agent.as_tool()` 审批。如果你仅批准或拒绝其中部分项目后重新运行，已解决调用可以继续，而未解决项仍会保留在 `interruptions` 中并再次暂停运行。 +你不需要在同一次处理中解决所有待处理审批。`interruptions` 可以包含常规工具调用、托管 MCP 审批和嵌套 `Agent.as_tool()` 审批的混合。如果你在只批准或拒绝部分项目后重新运行，已解决的调用可以继续，而未解决的调用会保留在 `interruptions` 中并再次暂停运行。 ## 自定义拒绝消息 -默认情况下，被拒绝的工具调用会将 SDK 的标准拒绝文本返回到运行中。你可以在两层进行自定义： +默认情况下，被拒绝的工具调用会将 SDK 的标准拒绝文本返回到运行中。你可以在两个层级自定义该消息： -- 全运行回退：设置 [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]，控制整个运行中审批拒绝时对模型可见的默认消息。 -- 按调用覆盖：调用 `state.reject(...)` 时传入 `rejection_message=...`，让某个特定被拒绝工具调用显示不同消息。 +- 运行范围后备：设置 [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]，以控制整个运行中审批拒绝时默认的模型可见消息。 +- 按调用覆盖：当你希望某个特定的被拒绝工具调用呈现不同消息时，将 `rejection_message=...` 传给 `state.reject(...)`。 -若两者同时提供，则按调用 `rejection_message` 优先于全运行格式化器。 +如果两者都提供，则按调用的 `rejection_message` 优先于运行范围格式化器。 ```python from agents import RunConfig, ToolErrorFormatterArgs @@ -83,27 +83,27 @@ state.reject( ) ``` -参见 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py) 获取同时展示这两层的完整示例。 +请参阅 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py)，其中的完整示例展示了如何同时使用这两个层级。 ## 自动审批决策 -手动 `interruptions` 是最通用模式，但并非唯一方式： +手动 `interruptions` 是最通用的模式，但并不是唯一模式： -- 本地 [`ShellTool`][agents.tool.ShellTool] 和 [`ApplyPatchTool`][agents.tool.ApplyPatchTool] 可用 `on_approval` 在代码中立即批准或拒绝。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] 可使用 `tool_config={"require_approval": "always"}` 配合 `on_approval_request` 实现同类编程式决策。 -- 普通 [`function_tool`][agents.tool.function_tool] 工具与 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 使用本页介绍的手动中断流程。 +- 本地 [`ShellTool`][agents.tool.ShellTool] 和 [`ApplyPatchTool`][agents.tool.ApplyPatchTool] 可以使用 `on_approval` 在代码中立即批准或拒绝。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] 可以将 `tool_config={"require_approval": "always"}` 与 `on_approval_request` 一起使用，以进行同类程序化决策。 +- 普通 [`function_tool`][agents.tool.function_tool] 工具和 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 使用本页的手动中断流程。 -当这些回调返回决策时，运行会继续，无需暂停等待人工响应。对于 Realtime 和语音会话 API，请参阅 [Realtime 指南](realtime/guide.md) 中的审批流程。 +当这些回调返回决策时，运行会继续，而无需暂停等待人工响应。对于 Realtime 和语音会话 API，请参阅 [Realtime 指南](realtime/guide.md)中的审批流程。 -## 流式传输与会话 +## 流式传输和会话 -同样的中断流程也适用于流式传输运行。流式运行暂停后，继续消费 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events] 直到迭代器结束，检查 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]，解决后如需继续流式输出，可用 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] 恢复。此模式的流式版本请参见[流式传输](streaming.md)。 +同一中断流程也适用于流式传输运行。流式传输运行暂停后，继续消费 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events]，直到迭代器结束，然后检查 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]、解决它们，并在你希望恢复后的输出继续流式传输时使用 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] 恢复。有关此模式的流式传输版本，请参阅[流式传输](streaming.md)。 -如果你也在使用会话，从 `RunState` 恢复时请继续传入同一个会话实例，或传入另一个指向同一后端存储的会话对象。恢复后的轮次会追加到同一已存储会话历史中。会话生命周期细节见[会话](sessions/index.md)。 +如果你还在使用会话，则在从 `RunState` 恢复时继续传入同一个会话实例，或传入另一个指向相同后端存储的会话对象。恢复后的轮次随后会追加到同一个已存储的对话历史中。有关会话生命周期详情，请参阅[会话](sessions/index.md)。 -## 示例：暂停、批准、恢复 +## 暂停、批准与恢复示例 -下面的片段与 JavaScript HITL 指南一致：当工具需要审批时暂停，将状态持久化到磁盘，重新加载后在收集决策后恢复。 +下面的代码片段与 JavaScript HITL 指南一致：它会在工具需要审批时暂停，将状态持久化到磁盘，重新加载状态，并在收集到决策后恢复。 ```python import asyncio @@ -167,35 +167,43 @@ if __name__ == "__main__": asyncio.run(main()) ``` -在此示例中，`prompt_approval` 是同步的，因为它使用 `input()` 并通过 `run_in_executor(...)` 执行。如果你的审批来源本身已是异步（例如 HTTP 请求或异步数据库查询），可改用 `async def` 函数并直接 `await`。 +在此示例中，`prompt_approval` 是同步的，因为它使用 `input()`，并通过 `run_in_executor(...)` 执行。如果你的审批来源已经是异步的（例如 HTTP 请求或异步数据库查询），则可以改用 `async def` 函数并直接 `await` 它。 -若要在等待审批时流式输出，请调用 `Runner.run_streamed`，消费 `result.stream_events()` 直到完成，然后按上文相同方式执行 `result.to_state()` 和恢复步骤。 +若要在等待审批时流式传输输出，请调用 `Runner.run_streamed`，消费 `result.stream_events()` 直到完成，然后按照上面展示的相同 `result.to_state()` 和恢复步骤操作。 -## 仓库模式与代码示例 +## 仓库模式和代码示例 -- **流式审批**：`examples/agent_patterns/human_in_the_loop_stream.py` 展示如何清空 `stream_events()`，随后批准待处理工具调用，并通过 `Runner.run_streamed(agent, state)` 恢复。 -- **自定义拒绝文本**：`examples/agent_patterns/human_in_the_loop_custom_rejection.py` 展示当审批被拒绝时，如何结合运行级 `tool_error_formatter` 与按调用 `rejection_message` 覆盖。 -- **智能体作为工具的审批**：`Agent.as_tool(..., needs_approval=...)` 在委派智能体任务需要审查时应用同样的中断流程。嵌套中断仍会暴露在外层运行上，因此应恢复原始顶层智能体，而不是嵌套智能体。 -- **本地 shell 与 apply_patch 工具**：`ShellTool` 和 `ApplyPatchTool` 也支持 `needs_approval`。使用 `state.approve(interruption, always_approve=True)` 或 `state.reject(..., always_reject=True)` 可缓存后续调用的决策。自动决策可提供 `on_approval`（见 `examples/tools/shell.py`）；手动决策则处理中断（见 `examples/tools/shell_human_in_the_loop.py`）。托管 shell 环境不支持 `needs_approval` 或 `on_approval`；参见[工具指南](tools.md)。 -- **本地 MCP 服务**：在 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` 上使用 `require_approval` 以管控 MCP 工具调用（见 `examples/mcp/get_all_mcp_tools_example/main.py` 和 `examples/mcp/tool_filter_example/main.py`）。 -- **托管 MCP 服务**：在 `HostedMCPTool` 上将 `require_approval` 设为 `"always"` 以强制 HITL，可选提供 `on_approval_request` 自动批准或拒绝（见 `examples/hosted_mcp/human_in_the_loop.py` 和 `examples/hosted_mcp/on_approval.py`）。对可信服务可使用 `"never"`（`examples/hosted_mcp/simple.py`）。 -- **会话与记忆**：向 `Runner.run` 传入会话，使审批与会话历史可跨多轮保留。SQLite 和 OpenAI Conversations 会话变体见 `examples/memory/memory_session_hitl_example.py` 与 `examples/memory/openai_session_hitl_example.py`。 -- **Realtime 智能体**：Realtime 演示通过 WebSocket 消息，使用 `RealtimeSession` 上的 `approve_tool_call` / `reject_tool_call` 批准或拒绝工具调用（服务端处理见 `examples/realtime/app/server.py`，API 说明见 [Realtime 指南](realtime/guide.md#tool-approvals)）。 +- **流式传输审批**: `examples/agent_patterns/human_in_the_loop_stream.py` 展示了如何消费完 `stream_events()`，然后在使用 `Runner.run_streamed(agent, state)` 恢复之前批准待处理的工具调用。 +- **自定义拒绝文本**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py` 展示了在审批被拒绝时，如何将运行级 `tool_error_formatter` 与按调用的 `rejection_message` 覆盖结合使用。 +- **智能体作为工具的审批**: `Agent.as_tool(..., needs_approval=...)` 会在委派的智能体任务需要审查时应用相同的中断流程。嵌套中断仍会呈现在外层运行上，因此应恢复原始顶层智能体，而不是嵌套智能体。 +- **本地 shell 和 apply_patch 工具**: `ShellTool` 和 `ApplyPatchTool` 也支持 `needs_approval`。使用 `state.approve(interruption, always_approve=True)` 或 `state.reject(..., always_reject=True)` 可缓存未来调用的决策。对于自动决策，请提供 `on_approval`（参见 `examples/tools/shell.py`）；对于手动决策，请处理中断（参见 `examples/tools/shell_human_in_the_loop.py`）。托管 shell 环境不支持 `needs_approval` 或 `on_approval`；请参阅[工具指南](tools.md)。 +- **本地 MCP 服务**: 在 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` 上使用 `require_approval` 来拦截 MCP 工具调用（参见 `examples/mcp/get_all_mcp_tools_example/main.py` 和 `examples/mcp/tool_filter_example/main.py`）。 +- **托管 MCP 服务**: 在 `HostedMCPTool` 上将 `require_approval` 设置为 `"always"` 以强制 HITL，并可选择提供 `on_approval_request` 来自动批准或拒绝（参见 `examples/hosted_mcp/human_in_the_loop.py` 和 `examples/hosted_mcp/on_approval.py`）。对于可信服务，请使用 `"never"`（`examples/hosted_mcp/simple.py`）。 +- **会话和记忆**: 将会话传给 `Runner.run`，使审批和对话历史能够跨多个轮次保留。SQLite 和 OpenAI Conversations 会话变体位于 `examples/memory/memory_session_hitl_example.py` 和 `examples/memory/openai_session_hitl_example.py`。 +- **Realtime 智能体**: Realtime 演示公开了 WebSocket 消息，可通过 `RealtimeSession` 上的 `approve_tool_call` / `reject_tool_call` 批准或拒绝工具调用（有关服务端处理程序，请参见 `examples/realtime/app/server.py`；有关 API 表面，请参阅 [Realtime 指南](realtime/guide.md#tool-approvals)）。 -## 长时审批 +## 长时间运行的审批 -`RunState` 设计为可持久化。使用 `state.to_json()` 或 `state.to_string()` 将待处理工作存入数据库或队列，并可稍后用 `RunState.from_json(...)` 或 `RunState.from_string(...)` 重建。 +`RunState` 设计为可持久化。使用 `state.to_json()` 或 `state.to_string()` 将待处理工作存储在数据库或队列中，并稍后使用 `RunState.from_json(...)` 或 `RunState.from_string(...)` 重新创建。 有用的序列化选项： -- `context_serializer`：自定义非映射上下文对象的序列化方式。 -- `context_deserializer`：在使用 `RunState.from_json(...)` 或 `RunState.from_string(...)` 加载状态时重建非映射上下文对象。 -- `strict_context=True`：除非上下文本身已是映射，或你提供了合适的序列化器/反序列化器，否则序列化或反序列化失败。 -- `context_override`：加载状态时替换序列化上下文。这在你不想恢复原始上下文对象时很有用，但不会从已序列化载荷中移除该上下文。 -- `include_tracing_api_key=True`：当你需要恢复后的工作继续使用相同凭证导出追踪时，在序列化追踪载荷中包含 tracing API key。 - -序列化后的运行状态包含你的应用上下文以及 SDK 管理的运行时元数据，例如审批、用量、序列化的 `tool_input`、嵌套 agent-as-tool 恢复、追踪元数据以及服务端管理的会话设置。如果你计划存储或传输序列化状态，请将 `RunContextWrapper.context` 视为持久化数据，避免在其中放置机密信息，除非你有意让其随状态传递。 +- `context_serializer`: 自定义非映射上下文对象的序列化方式。 +- `context_deserializer`: 使用 `RunState.from_json(...)` 或 `RunState.from_string(...)` 加载状态时，重建非映射上下文对象。 +- `strict_context=True`: 除非上下文已经是一个 + 映射，或你提供了相应的序列化器/反序列化器，否则序列化或反序列化将失败。 +- `context_override`: 加载状态时替换已序列化的上下文。当你 + 不想恢复原始上下文对象时，这很有用，但它不会从 + 已序列化的载荷中移除该上下文。 +- `include_tracing_api_key=True`: 当你需要恢复后的工作继续使用相同凭证导出追踪时， + 在序列化的追踪载荷中包含追踪 API 密钥。 + +序列化后的运行状态包括你的应用上下文，以及 SDK 管理的运行时元数据，例如审批、 +用量、序列化的 `tool_input`、嵌套的智能体作为工具恢复、追踪元数据以及由服务管理的 +对话设置。如果你计划存储或传输序列化状态，请将 +`RunContextWrapper.context` 视为持久化数据，并避免在其中放置机密信息，除非你 +明确希望它们随状态一起传递。 ## 待处理任务版本管理 -如果审批可能会搁置一段时间，请将智能体定义或 SDK 的版本标记与序列化状态一起存储。这样在模型、提示词或工具定义变更时，你就可以将反序列化路由到匹配的代码路径，避免不兼容问题。 \ No newline at end of file +如果审批可能搁置一段时间，请将你的智能体定义或 SDK 的版本标记与序列化状态一起存储。然后，你可以将反序列化路由到匹配的代码路径，以避免在模型、提示词或工具定义发生变化时出现不兼容问题。 \ No newline at end of file diff --git a/docs/zh/index.md b/docs/zh/index.md index 73d7a6ebf6..fc8f34d3c5 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -4,51 +4,51 @@ 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 -- **Agents as tools / 任务转移**，允许智能体将特定任务委派给其他智能体 -- **安全防护措施**，用于验证智能体的输入和输出 +- **智能体**，即配备指令和工具的 LLM +- **Agents as tools / 任务转移**，允许智能体将特定任务委派给其他智能体 +- **安全防护措施**，支持对智能体输入和输出进行验证 -与 Python 结合使用时，这些基本组件足以表达工具与智能体之间的复杂关系，并让你无需陡峭的学习曲线即可构建真实应用。此外，SDK 内置**追踪**功能，可帮助你可视化和调试智能体流程，也可对其进行评估，甚至为你的应用微调模型。 +结合 Python，这些基本组件足以表达工具与智能体之间的复杂关系，并让你无需陡峭的学习曲线即可构建真实世界的应用。此外，SDK 内置**追踪**，可用于可视化和调试你的智能体式流程，也可用于评估这些流程，甚至为你的应用微调模型。 -## 使用 Agents SDK 的原因 +## 使用 Agents SDK 的理由 -SDK 有两条核心设计原则： +SDK 有两个核心设计原则： -1. 功能足够值得使用，但基本组件足够少，便于快速学习。 -2. 开箱即用表现出色，同时你也可以精确自定义发生的行为。 +1. 功能足够实用，但基本组件足够少，便于快速学习。 +2. 开箱即用，同时可以精确自定义运行方式。 以下是 SDK 的主要功能： -- **智能体循环**：内置智能体循环，可处理工具调用，将结果发回 LLM，并持续运行直到任务完成。 -- **Python 优先**：使用内置语言特性来编排和串联智能体，而不需要学习新的抽象。 -- **Agents as tools / 任务转移**：用于在多个智能体之间协调和委派工作的强大机制。 -- **沙盒智能体**：在真实隔离的工作区中运行专家智能体，支持由清单定义的文件、沙盒客户端选择以及可恢复的沙盒会话。 -- **安全防护措施**：与智能体执行并行运行输入验证和安全检查，并在检查未通过时快速失败。 -- **工具调用**：将任何 Python 函数转换为工具，并自动生成 schema，且由 Pydantic 提供验证能力。 -- **MCP 服务工具调用**：内置 MCP 服务工具集成，其工作方式与工具调用相同。 -- **会话**：用于在智能体循环中维护工作上下文的持久化记忆层。 -- **人在回路中**：内置机制，用于在智能体运行过程中让人类参与。 -- **追踪**：内置追踪功能，用于可视化、调试和监控工作流，并支持 OpenAI 的评估、微调和蒸馏工具套件。 -- **Realtime Agents**：使用 `gpt-realtime-2` 构建强大的语音智能体，支持自动中断检测、上下文管理、安全防护措施等。 +- **智能体循环**：内置智能体循环，可处理工具调用、将结果发送回 LLM，并持续运行直到任务完成。 +- **Python 优先**：使用内置语言特性来编排和串联智能体，而无需学习新的抽象。 +- **Agents as tools / 任务转移**：一种强大的机制，用于在多个智能体之间协调和委派工作。 +- **沙盒智能体**：在真实隔离工作区中运行专家智能体，支持由清单定义的文件、沙盒客户端选择以及可恢复的沙盒会话。 +- **安全防护措施**：与智能体执行并行运行输入验证和安全检查，并在检查未通过时快速失败。 +- **工具调用**：将任何 Python 函数转换为工具，自动生成 schema，并通过 Pydantic 进行验证。 +- **MCP 服务工具调用**：内置 MCP 服务工具集成，其工作方式与工具调用相同。 +- **会话**：用于在智能体循环中维护工作上下文的持久记忆层。 +- **人在回路**：内置机制，用于在智能体运行过程中引入人工参与。 +- **追踪**：内置追踪，用于可视化、调试和监控工作流，并支持 OpenAI 的评估、微调和蒸馏工具套件。 +- **实时智能体**：使用 `gpt-realtime-2`、自动中断检测、上下文管理、安全防护措施等构建强大的语音智能体。 -## Agents SDK 还是 Responses API？ +## Agents SDK 与 Responses API 的选择 -对于 OpenAI 模型，SDK 默认使用 Responses API，但它在模型调用之上增加了更高层级的运行时。 +SDK 默认将 Responses API 用于 OpenAI模型，但它在模型调用之上增加了更高层的运行时。 在以下情况下直接使用 Responses API： -- 你想自行掌控循环、工具分发和状态处理 -- 你的工作流生命周期较短，主要是返回模型响应 +- 你希望自行掌控循环、工具分派和状态处理 +- 你的工作流生命周期较短，且主要目标是返回模型响应 在以下情况下使用 Agents SDK： -- 你希望运行时管理轮次、工具执行、安全防护措施、任务转移或会话 -- 你的智能体需要生成产物，或跨多个协调步骤运行 -- 你需要通过[沙盒智能体](sandbox_agents.md)获得真实工作区或可恢复执行 +- 你希望由运行时管理轮次、工具执行、安全防护措施、任务转移或会话 +- 你的智能体需要生成产物，或跨多个协调步骤运行 +- 你需要通过[沙盒智能体](sandbox_agents.md)获得真实工作区或可恢复执行 -你不需要在全局范围内二选一。许多应用会将 SDK 用于托管工作流，并在较低层级的路径中直接调用 Responses API。 +你不必在全局范围内二选一。许多应用会使用 SDK 处理托管工作流，并在较底层路径中直接调用 Responses API。 ## 安装 @@ -56,7 +56,7 @@ SDK 有两条核心设计原则： pip install openai-agents ``` -## Hello World 示例 +## Hello world 示例 ```python from agents import Agent, Runner @@ -71,31 +71,31 @@ print(result.final_output) # Infinite loop's dance. ``` -（_如果运行此示例，请确保已设置 `OPENAI_API_KEY` 环境变量_） +_(如果运行此示例，请确保设置 `OPENAI_API_KEY` 环境变量)_ ```bash export OPENAI_API_KEY=sk-... ``` -## 起点 +## 入门起点 -- 使用[快速入门](quickstart.md)构建你的第一个基于文本的智能体。 -- 然后在[运行智能体](running_agents.md#choose-a-memory-strategy)中决定如何跨轮次携带状态。 -- 如果任务依赖真实文件、代码仓库或隔离的每智能体工作区状态，请阅读[沙盒智能体快速入门](sandbox_agents.md)。 -- 如果你正在任务转移与管理器式编排之间做选择，请阅读[智能体编排](multi_agent.md)。 +- 通过[快速入门](quickstart.md)构建你的第一个基于文本的智能体。 +- 然后在[运行智能体](running_agents.md#choose-a-memory-strategy)中决定如何在多个轮次之间保留状态。 +- 如果任务依赖真实文件、代码仓库或每个智能体隔离的工作区状态，请阅读[沙盒智能体快速入门](sandbox_agents.md)。 +- 如果你正在任务转移和管理器式编排之间做选择，请阅读[智能体编排](multi_agent.md)。 ## 路径选择 -当你知道自己想完成的工作，但不知道哪一页提供说明时，请使用此表。 +当你知道想完成的工作，但不知道应查看哪个页面时，请使用此表。 -| 目标 | 起点 | +| 目标 | 从这里开始 | | --- | --- | -| 构建第一个文本智能体并查看一次完整运行 | [快速入门](quickstart.md) | -| 添加工具调用、托管工具或 agents as tools | [工具](tools.md) | -| 在真实隔离的工作区中运行编码、审查或文档智能体 | [沙盒智能体快速入门](sandbox_agents.md)和[沙盒客户端](sandbox/clients.md) | -| 在任务转移与管理器式编排之间做决定 | [智能体编排](multi_agent.md) | -| 跨轮次保留记忆 | [运行智能体](running_agents.md#choose-a-memory-strategy)和[会话](sessions/index.md) | -| 使用 OpenAI 模型、websocket 传输或非 OpenAI 提供方 | [模型](models/index.md) | +| 构建第一个文本智能体，并查看一次完整运行 | [快速入门](quickstart.md) | +| 添加工具调用、托管工具或 Agents as tools | [工具](tools.md) | +| 在真实隔离工作区中运行编码、审查或文档智能体 | [沙盒智能体快速入门](sandbox_agents.md)和[沙盒客户端](sandbox/clients.md) | +| 在任务转移和管理器式编排之间做选择 | [智能体编排](multi_agent.md) | +| 在多个轮次之间保留记忆 | [运行智能体](running_agents.md#choose-a-memory-strategy)和[会话](sessions/index.md) | +| 使用 OpenAI模型、websocket 传输或非 OpenAI提供商 | [模型](models/index.md) | | 查看输出、运行项、中断和恢复状态 | [结果](results.md) | -| 使用 `gpt-realtime-2` 构建低延迟语音智能体 | [Realtime agents 快速入门](realtime/quickstart.md)和[Realtime 传输](realtime/transport.md) | +| 使用 `gpt-realtime-2` 构建低延迟语音智能体 | [实时智能体快速入门](realtime/quickstart.md)和[实时传输](realtime/transport.md) | | 构建语音转文本 / 智能体 / 文本转语音流水线 | [语音流水线快速入门](voice/quickstart.md) | \ No newline at end of file diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md index 6380976fac..4e3a01767c 100644 --- a/docs/zh/mcp.md +++ b/docs/zh/mcp.md @@ -4,30 +4,32 @@ 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服务，或构建自己的MCP服务，向智能体公开 +基于文件系统、HTTP或连接器支持的工具。 -## MCP 集成选择 +## MCP集成选择 -在将 MCP 服务接入智能体之前，请先决定工具调用应在哪里执行，以及你可以访问哪些传输方式。下表汇总了 Python SDK 支持的选项。 +在将MCP服务接入智能体之前，请先确定工具调用应在哪里执行，以及你能够访问哪些传输方式。 +下表总结了Python SDK支持的选项。 | 你的需求 | 推荐选项 | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| 让 OpenAI 的 Responses API 代表模型调用一个可公开访问的 MCP 服务| 通过 [`HostedMCPTool`][agents.tool.HostedMCPTool] 使用**托管 MCP 服务工具** | -| 连接到你在本地或远程运行的 Streamable HTTP 服务 | 通过 [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 使用 **Streamable HTTP MCP 服务** | -| 与实现了带 Server-Sent Events 的 HTTP 的服务通信 | 通过 [`MCPServerSse`][agents.mcp.server.MCPServerSse] 使用**带 SSE 的 HTTP MCP 服务** | -| 启动本地进程并通过 stdin/stdout 通信 | 通过 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 使用 **stdio MCP 服务** | +| 让OpenAI的Responses API代表模型调用可公开访问的MCP服务| **托管MCP服务工具**，通过[`HostedMCPTool`][agents.tool.HostedMCPTool] | +| 连接到你在本地或远程运行的Streamable HTTP服务 | **Streamable HTTP MCP服务**，通过[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] | +| 与实现HTTP with Server-Sent Events的服务通信 | **HTTP with SSE MCP服务**，通过[`MCPServerSse`][agents.mcp.server.MCPServerSse] | +| 启动本地进程并通过stdin/stdout通信 | **stdio MCP服务**，通过[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] | -以下各节将介绍每种选项、配置方式，以及何时应优先选择某种传输方式。 +以下各节将逐一介绍每个选项、其配置方式，以及何时应优先选择某种传输方式。 -## 智能体级 MCP 配置 +## 智能体级MCP配置 -除了选择传输方式之外，你还可以通过设置 `Agent.mcp_config` 来调优 MCP 工具的准备方式。 +除了选择传输方式外，还可以通过设置`Agent.mcp_config`来调整MCP工具的准备方式。 ```python from agents import Agent @@ -49,32 +51,33 @@ agent = Agent( 说明： -- `convert_schemas_to_strict` 是尽力而为的。如果某个 schema 无法转换，将使用原始 schema。 -- `failure_error_function` 控制 MCP 工具调用失败如何呈现给模型。 -- 当未设置 `failure_error_function` 时，SDK 会使用默认的工具错误格式化器。 -- 服务级别的 `failure_error_function` 会覆盖该服务上的 `Agent.mcp_config["failure_error_function"]`。 -- `include_server_in_tool_names` 是可选开启的。启用后，每个本地 MCP 工具都会以确定性的、带服务前缀的名称公开给模型，这有助于在多个 MCP 服务发布同名工具时避免冲突。生成的名称是 ASCII 安全的，会保持在函数工具名称长度限制内，并避免与同一智能体上的现有本地函数工具和已启用的任务转移名称冲突。SDK 仍会在原始服务上调用原始 MCP 工具名称。 +- `convert_schemas_to_strict`会尽力执行。如果某个schema无法转换，则使用原始schema。 +- `failure_error_function`控制如何向模型呈现MCP工具调用失败。 +- 当未设置`failure_error_function`时，SDK会使用默认工具错误格式化器。 +- 服务级`failure_error_function`会覆盖该服务的`Agent.mcp_config["failure_error_function"]`。 +- `include_server_in_tool_names`需要主动启用。启用后，每个本地MCP工具都会以带有确定性服务前缀的名称公开给模型，这有助于在多个MCP服务发布同名工具时避免冲突。生成的名称是ASCII安全的，保持在工具调用名称长度限制内，并会避开同一智能体上现有的本地工具调用名称和已启用的任务转移名称。SDK仍会在原始服务上调用原始MCP工具名称。 -## 各传输方式的通用模式 +## 跨传输方式的通用模式 选择传输方式后，大多数集成都需要做出相同的后续决策： -- 如何只公开部分工具（[工具过滤](#tool-filtering)）。 -- 服务是否还提供可复用的提示词（[提示词](#prompts)）。 -- 是否应缓存 `list_tools()`（[缓存](#caching)）。 -- MCP 活动如何出现在追踪中（[追踪](#tracing)）。 +- 如何只公开工具子集（[工具筛选](#tool-filtering)）。 +- 服务是否也提供可复用的提示词（[提示词](#prompts)）。 +- 是否应缓存`list_tools()`（[缓存](#caching)）。 +- MCP活动如何显示在追踪中（[追踪](#tracing)）。 -对于本地 MCP 服务（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`），审批策略和每次调用的 `_meta` 负载也是通用概念。Streamable HTTP 一节展示了最完整的示例，相同模式也适用于其他本地传输方式。 +对于本地MCP服务（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`），审批策略和每次调用的`_meta`载荷也是通用概念。Streamable HTTP部分展示了最完整的示例，同样的模式也适用于其他本地传输方式。 -## 1. 托管 MCP 服务工具 +## 1. 托管MCP服务工具 -托管工具会将整个工具往返过程推送到 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 工具 +### 基础托管MCP工具 -通过将 [`HostedMCPTool`][agents.tool.HostedMCPTool] 添加到智能体的 `tools` 列表来创建托管工具。`tool_config` -字典与发送到 REST API 的 JSON 保持一致： +通过将[`HostedMCPTool`][agents.tool.HostedMCPTool]添加到智能体的`tools`列表来创建托管工具。`tool_config` +字典与发送给REST API的JSON保持一致： ```python import asyncio @@ -106,13 +109,14 @@ async def main() -> None: asyncio.run(main()) ``` -托管服务会自动公开其工具；你无需将其添加到 `mcp_servers`。 +该托管服务会自动公开其工具；你无需将其添加到`mcp_servers`。 -如果希望托管工具搜索延迟加载托管 MCP 服务，请设置 `tool_config["defer_loading"] = True` 并将 [`ToolSearchTool`][agents.tool.ToolSearchTool] 添加到智能体。此功能仅在 OpenAI Responses 模型上受支持。有关完整的工具搜索设置和约束，请参阅[工具](tools.md#hosted-tool-search)。 +如果希望托管工具搜索延迟加载托管MCP服务，请设置`tool_config["defer_loading"] = True`并将[`ToolSearchTool`][agents.tool.ToolSearchTool]添加到智能体中。此功能仅在OpenAI Responses模型上受支持。有关完整的工具搜索设置和约束，请参阅[工具](tools.md#hosted-tool-search)。 -### 流式托管 MCP 结果 +### 托管MCP结果流式传输 -托管工具支持流式传输结果，方式与函数工具完全相同。使用 `Runner.run_streamed` 在模型仍在工作时消费增量 MCP 输出： +托管工具支持结果流式传输，方式与工具调用完全相同。使用`Runner.run_streamed`在模型仍在工作时 +消费增量MCP输出： ```python result = Runner.run_streamed(agent, "Summarise this repository's top languages") @@ -124,8 +128,9 @@ print(result.final_output) ### 可选审批流程 -如果某个服务可以执行敏感操作，你可以要求在每次工具执行前进行人工或程序化审批。在 `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 @@ -153,11 +158,12 @@ agent = Agent( ) ``` -该回调可以是同步或异步的，并且会在模型需要审批数据以继续运行时被调用。 +该回调可以是同步或异步的，并会在模型需要审批数据以继续运行时被调用。 ### 连接器支持的托管服务 -托管 MCP 也支持 OpenAI 连接器。无需指定 `server_url`，而是提供 `connector_id` 和访问令牌。Responses API 会处理身份验证，托管服务会公开连接器的工具。 +托管MCP还支持OpenAI连接器。无需指定`server_url`，而是提供`connector_id`和访问令牌。 +Responses API会处理身份验证，托管服务会公开该连接器的工具。 ```python import os @@ -173,13 +179,14 @@ HostedMCPTool( ) ``` -完整可运行的托管工具示例——包括流式传输、审批和连接器——位于 +完整可运行的托管工具示例（包括流式传输、审批和连接器）位于 [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)。 -## 2. Streamable HTTP MCP 服务 +## 2. Streamable HTTP MCP服务 当你希望自行管理网络连接时，请使用 -[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你控制传输方式，或希望在自己的基础设施内运行服务并保持低延迟时，Streamable HTTP 服务非常适合。 +[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你能够控制 +传输方式，或希望在自己的基础设施中运行服务并保持低延迟时，Streamable HTTP服务是理想选择。 ```python import asyncio @@ -214,25 +221,25 @@ 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)）。 -- `require_approval` 在本地 MCP 工具上启用人在回路中的审批策略。 -- `failure_error_function` 自定义模型可见的 MCP 工具失败消息；将其设置为 `None` 则改为抛出错误。 -- `tool_meta_resolver` 在 `call_tool()` 之前注入每次调用的 MCP `_meta` 负载。 +- `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)）。 +- `require_approval`在本地MCP工具上启用人在环路审批策略。 +- `failure_error_function`自定义模型可见的MCP工具失败消息；将其设为`None`则会改为抛出错误。 +- `tool_meta_resolver`在`call_tool()`之前注入每次调用的MCP `_meta`载荷。 -### 本地 MCP 服务的审批策略 +### 本地MCP服务的审批策略 -`MCPServerStdio`、`MCPServerSse` 和 `MCPServerStreamableHttp` 都接受 `require_approval`。 +`MCPServerStdio`、`MCPServerSse`和`MCPServerStreamableHttp`均接受`require_approval`。 支持的形式： -- 对所有工具使用 `"always"` 或 `"never"`。 -- `True` / `False`（等同于 always/never）。 -- 按工具映射，例如 `{"delete_file": "always", "read_file": "never"}`。 +- 对所有工具使用`"always"`或`"never"`。 +- `True` / `False`（等同于always/never）。 +- 按工具映射，例如`{"delete_file": "always", "read_file": "never"}`。 - 分组对象： `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`。 @@ -245,11 +252,11 @@ async with MCPServerStreamableHttp( ... ``` -有关完整的暂停/恢复流程，请参阅[人在回路中](human_in_the_loop.md)以及 `examples/mcp/get_all_mcp_tools_example/main.py`。 +如需完整的暂停/恢复流程，请参阅[人在环路](human_in_the_loop.md)和`examples/mcp/get_all_mcp_tools_example/main.py`。 -### 使用 `tool_meta_resolver` 的每次调用元数据 +### 使用`tool_meta_resolver`的每次调用元数据 -当你的 MCP 服务期望在 `_meta` 中接收请求元数据（例如租户 ID 或追踪上下文）时，请使用 `tool_meta_resolver`。下面的示例假设你将 `dict` 作为 `context` 传给 `Runner.run(...)`。 +当你的MCP服务希望在`_meta`中接收请求元数据（例如租户ID或追踪上下文）时，请使用`tool_meta_resolver`。下面的示例假设你向`Runner.run(...)`传入一个`dict`作为`context`。 ```python from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext @@ -270,20 +277,20 @@ server = MCPServerStreamableHttp( ) ``` -如果你的运行上下文是 Pydantic 模型、dataclass 或自定义类，请改用属性访问来读取租户 ID。 +如果你的运行上下文是Pydantic模型、dataclass或自定义类，请改用属性访问来读取租户ID。 -### MCP 工具输出：文本和图像 +### MCP工具输出：文本和图像 -当 MCP 工具返回图像内容时，SDK 会自动将其映射为图像工具输出条目。混合文本/图像响应会作为输出项列表转发，因此智能体可以像消费常规函数工具的图像输出一样消费 MCP 图像结果。 +当MCP工具返回图像内容时，SDK会自动将其映射为图像工具输出条目。混合文本/图像响应会作为输出项列表转发，因此智能体可以像消费常规工具调用的图像输出一样消费MCP图像结果。 -## 3. 带 SSE 的 HTTP MCP 服务 +## 3. HTTP with SSE MCP服务 !!! warning - MCP 项目已弃用 Server-Sent Events 传输。对于新的集成，请优先使用 Streamable HTTP 或 stdio，并仅为旧版服务保留 SSE。 + MCP项目已弃用Server-Sent Events传输方式。新的集成应优先使用Streamable HTTP或stdio，仅为旧版服务保留SSE。 -如果 MCP 服务实现了带 SSE 的 HTTP 传输，请实例化 -[`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，其 API 与 Streamable HTTP 服务相同。 +如果MCP服务实现了HTTP with SSE传输方式，请实例化 +[`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，该API与Streamable HTTP服务完全相同。 ```python @@ -310,10 +317,10 @@ async with MCPServerSse( print(result.final_output) ``` -## 4. stdio MCP 服务 +## 4. stdio MCP服务 -对于作为本地子进程运行的 MCP 服务，请使用 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK 会生成该 -进程、保持管道打开，并在上下文管理器退出时自动关闭它们。此选项有助于快速概念验证，或当服务只公开命令行入口点时使用。 +对于作为本地子进程运行的MCP服务，请使用[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK会生成该 +进程、保持管道打开，并在上下文管理器退出时自动关闭它们。此选项有助于快速概念验证，或在服务仅公开命令行入口点时使用。 ```python from pathlib import Path @@ -339,10 +346,10 @@ async with MCPServerStdio( print(result.final_output) ``` -## 5. MCP 服务管理器 +## 5. MCP服务管理器 -当你有多个 MCP 服务时，使用 `MCPServerManager` 预先连接它们，并将已连接的子集公开给你的智能体。 -有关构造函数选项和重连行为，请参阅 [MCPServerManager API 参考](ref/mcp/manager.md)。 +当你有多个MCP服务时，请使用`MCPServerManager`预先连接它们，并向你的智能体公开已连接的子集。 +有关构造函数选项和重连行为，请参阅[MCPServerManager API参考](ref/mcp/manager.md)。 ```python from agents import Agent, Runner @@ -365,23 +372,24 @@ async with MCPServerManager(servers) as manager: 关键行为： -- 当 `drop_failed_servers=True`（默认值）时，`active_servers` 仅包含成功连接的服务。 -- 失败会记录在 `failed_servers` 和 `errors` 中。 -- 设置 `strict=True` 以在第一次连接失败时抛出异常。 -- 调用 `reconnect(failed_only=True)` 重试失败的服务，或调用 `reconnect(failed_only=False)` 重启所有服务。 -- 使用 `connect_timeout_seconds`、`cleanup_timeout_seconds` 和 `connect_in_parallel` 调优生命周期行为。 +- 当`drop_failed_servers=True`（默认值）时，`active_servers`仅包含已成功连接的服务。 +- 失败会记录在`failed_servers`和`errors`中。 +- 设置`strict=True`可在首次连接失败时抛出错误。 +- 调用`reconnect(failed_only=True)`可重试失败的服务，或调用`reconnect(failed_only=False)`重启所有服务。 +- 使用`connect_timeout_seconds`、`cleanup_timeout_seconds`和`connect_in_parallel`来调优生命周期行为。 ## 常见服务能力 -以下各节适用于各种 MCP 服务传输方式（具体 API 表面取决于服务类）。 +以下各节适用于各种MCP服务传输方式（确切的API范围取决于服务类）。 -## 工具过滤 +## 工具筛选 -每个 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 @@ -399,11 +407,13 @@ 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]的可调用对象。该可调用对象可以是 +同步或异步的，并在应公开该工具时返回`True`。 ```python from pathlib import Path @@ -427,14 +437,15 @@ async with MCPServerStdio( ... ``` -过滤器上下文会公开活动的 `run_context`、请求工具的 `agent`，以及 `server_name`。 +筛选上下文会公开活动的`run_context`、请求工具的`agent`以及`server_name`。 ## 提示词 -MCP 服务还可以提供动态生成智能体 instructions 的提示词。支持提示词的服务会公开两个方法： +MCP服务还可以提供用于动态生成智能体指令的提示词。支持提示词的服务会公开两个 +方法： -- `list_prompts()` 枚举可用的提示词模板。 -- `get_prompt(name, arguments)` 获取一个具体提示词，可选择带参数。 +- `list_prompts()`枚举可用的提示词模板。 +- `get_prompt(name, arguments)`获取具体提示词，可选择带参数。 ```python from agents import Agent @@ -454,20 +465,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) +![MCP追踪截图](../assets/images/mcp-tracing.jpg) ## 延伸阅读 - [Model Context Protocol](https://modelcontextprotocol.io/) – 规范和设计指南。 -- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的 stdio、SSE 和 Streamable HTTP 示例。 -- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 完整的托管 MCP 演示，包括审批和连接器。 +- [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/zh/models/index.md b/docs/zh/models/index.md index b30f776880..8dfe6ca522 100644 --- a/docs/zh/models/index.md +++ b/docs/zh/models/index.md @@ -4,31 +4,31 @@ 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 模型 | 使用默认的 OpenAI 提供方和 Responses 模型路径 | [OpenAI 模型](#openai-models) | -| 通过 websocket 传输使用 OpenAI Responses API | 保持 Responses 模型路径并启用 websocket 传输 | [Responses WebSocket 传输](#responses-websocket-transport) | -| 使用一个非 OpenAI 提供方 | 从内置提供方集成点开始 | [非 OpenAI 模型](#non-openai-models) | -| 在多个智能体之间混用模型或提供方 | 按每次运行或每个智能体选择提供方，并查看功能差异 | [在一个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨提供方混用模型](#mixing-models-across-providers) | -| 调整高级 OpenAI Responses 请求设置 | 在 OpenAI Responses 路径上使用 `ModelSettings` | [高级 OpenAI Responses 设置](#advanced-openai-responses-settings) | -| 为非 OpenAI 或混合提供方路由使用第三方适配器 | 比较受支持的 beta 适配器，并验证你计划发布的提供方路径 | [第三方适配器](#third-party-adapters) | +| 仅使用OpenAI模型 | 使用默认OpenAI提供商和Responses模型路径 | [OpenAI模型](#openai-models) | +| 通过 WebSocket 传输使用OpenAI Responses API | 保持Responses模型路径并启用 WebSocket 传输 | [Responses WebSocket 传输](#responses-websocket-transport) | +| 使用一个非OpenAI提供商 | 从内置提供商集成点开始 | [非OpenAI模型](#non-openai-models) | +| 在多个智能体之间混用模型或提供商 | 按每次运行或每个智能体选择提供商，并查看功能差异 | [单个工作流中的模型混用](#mixing-models-in-one-workflow)和[跨提供商的模型混用](#mixing-models-across-providers) | +| 调整高级OpenAI Responses请求设置 | 在OpenAI Responses路径上使用 `ModelSettings` | [高级OpenAI Responses设置](#advanced-openai-responses-settings) | +| 为非OpenAI或混合提供商路由使用第三方适配器 | 比较受支持的 beta 适配器，并验证你计划上线的提供商路径 | [第三方适配器](#third-party-adapters) | -## OpenAI 模型 +## OpenAI模型 -对于大多数仅使用 OpenAI 的应用，推荐路径是通过默认 OpenAI 提供方使用字符串模型名称，并保持在 Responses 模型路径上。 +对于大多数仅使用OpenAI的应用，推荐路径是将字符串模型名称与默认OpenAI提供商配合使用，并保持在Responses模型路径上。 -当你在初始化 `Agent` 时未指定模型，将使用默认模型。默认值目前是 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)，并为低延迟智能体工作流设置 `reasoning.effort="none"` 和 `verbosity="low"`。如果你有访问权限，我们建议将智能体设置为 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，以在保留显式 `model_settings` 的同时获得更高质量。 +如果在初始化 `Agent` 时未指定模型，则会使用默认模型。当前默认模型是 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)，并设置 `reasoning.effort="none"` 和 `verbosity="low"`，适用于低延迟智能体工作流。如果你具备访问权限，我们建议将智能体设置为 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，以在保留显式 `model_settings` 的同时获得更高质量。 -如果你想切换到其他模型，例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，有两种方式配置智能体。 +如果你想切换到其他模型，例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，有两种方式可以配置智能体。 ### 默认模型 @@ -39,7 +39,7 @@ export OPENAI_DEFAULT_MODEL=gpt-5.5 python3 my_awesome_agent.py ``` -其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果没有为智能体设置模型，将使用此次运行的模型。 +其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果没有为某个智能体设置模型，则会使用这次运行的模型。 ```python from agents import Agent, RunConfig, Runner @@ -58,7 +58,7 @@ result = await Runner.run( #### GPT-5 模型 -当你以这种方式使用任何 GPT-5 模型（例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)）时，SDK 会应用默认的 `ModelSettings`。它会设置适用于大多数用例的最佳选项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： +当你以这种方式使用任何 GPT-5 模型（例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)）时，SDK会应用默认的 `ModelSettings`。它会设置最适合大多数使用场景的配置。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`： ```python from openai.types.shared import Reasoning @@ -74,35 +74,35 @@ my_agent = Agent( ) ``` -为降低延迟，建议在 GPT-5 模型中使用 `reasoning.effort="none"`。 +为了降低延迟，建议在 GPT-5 模型中使用 `reasoning.effort="none"`。 #### ComputerTool 模型选择 -如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求上的有效模型会决定 SDK 发送哪种 computer-tool 载荷。显式的 `gpt-5.5` 请求使用 GA 内置 `computer` 工具，而显式的 `computer-use-preview` 请求保留较旧的 `computer_use_preview` 载荷。 +如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际Responses请求上的生效模型会决定SDK发送哪种计算机工具 payload。显式的 `gpt-5.5` 请求会使用 GA 内置 `computer` 工具，而显式的 `computer-use-preview` 请求会保留较旧的 `computer_use_preview` payload。 -由提示词管理的调用是主要例外。如果提示词模板拥有模型，并且 SDK 从请求中省略 `model`，SDK 会默认使用兼容预览版的 computer 载荷，这样它就不会猜测提示词固定了哪个模型。若要在该流程中保持 GA 路径，请在请求中显式设置 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 +由 prompt 管理的调用是主要例外。如果 prompt 模板拥有模型，并且SDK从请求中省略 `model`，SDK会默认使用兼容预览版的计算机 payload，以免猜测该 prompt 固定了哪个模型。若要在该流程中保持 GA 路径，请在请求中显式设置 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 -注册了 [`ComputerTool`][agents.tool.ComputerTool] 后，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 会被规范化为与有效请求模型匹配的内置选择器。如果未注册 `ComputerTool`，这些字符串会继续像普通函数名称一样运行。 +注册了 [`ComputerTool`][agents.tool.ComputerTool] 时，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 会被规范化为与生效请求模型匹配的内置选择器。如果没有注册 `ComputerTool`，这些字符串会继续像普通函数名称一样工作。 -兼容预览版的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程，应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制使用 GA 选择器。完整迁移详情请参阅[工具](../tools.md#computertool-and-the-responses-computer-tool)。 +兼容预览版的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的 prompt 管理流程，应传入一个具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制使用 GA 选择器。完整迁移详情请参见[工具](../tools.md#computertool-and-the-responses-computer-tool)。 #### 非 GPT-5 模型 -如果你传入非 GPT-5 模型名称且没有自定义 `model_settings`，SDK 会回退到与任何模型兼容的通用 `ModelSettings`。 +如果传入非 GPT-5 模型名称且没有自定义 `model_settings`，SDK会回退到与任何模型兼容的通用 `ModelSettings`。 -### 仅 Responses 支持的工具检索功能 +### 仅 Responses 支持的工具搜索特性 -以下工具功能仅受 OpenAI Responses 模型支持： +以下工具特性仅OpenAI Responses模型支持： - [`ToolSearchTool`][agents.tool.ToolSearchTool] - [`tool_namespace()`][agents.tool.tool_namespace] -- `@function_tool(defer_loading=True)` 以及其他延迟加载的 Responses 工具界面 +- `@function_tool(defer_loading=True)` 以及其他延迟加载的Responses工具接口 -这些功能在 Chat Completions 模型和非 Responses 后端上会被拒绝。使用延迟加载工具时，请将 `ToolSearchTool()` 添加到智能体，并让模型通过 `auto` 或 `required` 工具选择加载工具，而不是强制使用裸命名空间名称或仅延迟的函数名称。设置详情和当前限制请参阅[工具](../tools.md#hosted-tool-search)。 +Chat Completions模型和非Responses后端会拒绝这些特性。使用延迟加载工具时，请向智能体添加 `ToolSearchTool()`，并让模型通过 `auto` 或 `required` tool choice 加载工具，而不是强制使用裸命名空间名称或仅延迟加载的函数名称。设置详情和当前约束请参见[工具](../tools.md#hosted-tool-search)。 ### Responses WebSocket 传输 -默认情况下，OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI 支持的模型时，你可以选择启用 websocket 传输。 +默认情况下，OpenAI Responses API请求使用 HTTP 传输。使用OpenAI支持的模型时，你可以选择启用 WebSocket 传输。 #### 基本设置 @@ -112,13 +112,13 @@ from agents import set_default_openai_responses_transport set_default_openai_responses_transport("websocket") ``` -这会影响由默认 OpenAI 提供方解析的 OpenAI Responses 模型（包括字符串模型名称，例如 `"gpt-5.5"`）。 +这会影响由默认OpenAI提供商解析的OpenAI Responses模型（包括诸如 `"gpt-5.5"` 之类的字符串模型名称）。 -传输选择发生在 SDK 将模型名称解析为模型实例时。如果你传入具体的 [`Model`][agents.models.interface.Model] 对象，它的传输已经固定：[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 websocket，[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP，而 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 保持在 Chat Completions 上。如果你传入 `RunConfig(model_provider=...)`，则该提供方会控制传输选择，而不是全局默认值。 +传输选择发生在SDK将模型名称解析为模型实例时。如果传入具体的 [`Model`][agents.models.interface.Model] 对象，它的传输已经固定：[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 WebSocket，[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP，而 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 保持在Chat Completions上。如果传入 `RunConfig(model_provider=...)`，则由该提供商控制传输选择，而不是使用全局默认值。 -#### 提供方或运行级设置 +#### 提供商级或运行级设置 -你也可以按提供方或按运行配置 websocket 传输： +你也可以按提供商或按运行配置 WebSocket 传输： ```python from agents import Agent, OpenAIProvider, RunConfig, Runner @@ -139,7 +139,7 @@ result = await Runner.run( ) ``` -OpenAI 支持的提供方还接受可选的智能体注册配置。这是一个高级选项，适用于你的 OpenAI 设置需要提供方级注册元数据（例如 harness ID）的情况。 +OpenAI支持的提供商还接受可选的智能体注册配置。这是一个高级选项，适用于你的OpenAI设置需要提供商级注册元数据（例如 harness ID）的场景。 ```python from agents import ( @@ -165,14 +165,14 @@ result = await Runner.run( #### 使用 `MultiProvider` 的高级路由 -如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `any-llm/...` 模型名称），请使用 [`MultiProvider`][agents.MultiProvider]，并在那里设置 `openai_use_responses_websocket=True`。 +如果需要基于前缀的模型路由（例如在同一次运行中混用 `openai/...` 和 `any-llm/...` 模型名称），请使用 [`MultiProvider`][agents.MultiProvider]，并在那里设置 `openai_use_responses_websocket=True`。 -`MultiProvider` 保留两个历史默认值： +`MultiProvider` 保留了两个历史默认行为： -- `openai/...` 被视为 OpenAI 提供方的别名，因此 `openai/gpt-4.1` 会以模型 `gpt-4.1` 的形式路由。 +- `openai/...` 被视为OpenAI提供商的别名，因此 `openai/gpt-4.1` 会被路由为模型 `gpt-4.1`。 - 未知前缀会引发 `UserError`，而不是被透传。 -当你将 OpenAI 提供方指向期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式选择透传行为。在启用了 websocket 的设置中，也要在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： +当你将OpenAI提供商指向期望字面命名空间模型 ID 的OpenAI兼容端点时，请显式选择透传行为。在启用 WebSocket 的设置中，也请在 `MultiProvider` 上保留 `openai_use_responses_websocket=True`： ```python from agents import Agent, MultiProvider, RunConfig, Runner @@ -198,39 +198,39 @@ result = await Runner.run( ) ``` -当后端期望字面量 `openai/...` 字符串时，使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（例如 `openrouter/openai/gpt-4.1-mini`）时，使用 `unknown_prefix_mode="model_id"`。这些选项也适用于 websocket 传输之外的 `MultiProvider`；此示例保持启用 websocket，因为它是本节所述传输设置的一部分。相同选项也可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。 +当后端期望字面 `openai/...` 字符串时，请使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（例如 `openrouter/openai/gpt-4.1-mini`）时，请使用 `unknown_prefix_mode="model_id"`。这些选项也适用于 WebSocket 传输之外的 `MultiProvider`；此示例保持启用 WebSocket，因为它是本节所述传输设置的一部分。同样的选项也可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。 -如果你在通过 `MultiProvider` 路由时需要相同的提供方级注册元数据，请传入 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`，它会被转发到底层 OpenAI 提供方。 +如果你在通过 `MultiProvider` 路由时需要相同的提供商级注册元数据，请传入 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`，它会被转发到底层OpenAI提供商。 -如果你使用自定义 OpenAI 兼容端点或代理，websocket 传输还需要兼容的 websocket `/responses` 端点。在这些设置中，你可能需要显式设置 `websocket_base_url`。 +如果你使用自定义OpenAI兼容端点或代理，WebSocket 传输还需要兼容的 WebSocket `/responses` 端点。在这些设置中，你可能需要显式设置 `websocket_base_url`。 -#### 说明 +#### 注意事项 -- 这是通过 websocket 传输的 Responses API，而不是 [Realtime API](../realtime/guide.md)。它不适用于 Chat Completions 或非 OpenAI 提供方，除非它们支持 Responses websocket `/responses` 端点。 +- 这是通过 WebSocket 传输使用的Responses API，而不是 [Realtime API](../realtime/guide.md)。它不适用于Chat Completions或非OpenAI提供商，除非它们支持Responses WebSocket `/responses` 端点。 - 如果你的环境中尚未提供 `websockets` 包，请安装它。 -- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于你希望在多个轮次（以及嵌套的 agent-as-tool 调用）之间复用同一个 websocket 连接的多轮工作流，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助函数。请参阅[运行智能体](../running_agents.md)指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。 -- 对于长推理轮次或存在延迟尖峰的网络，请使用 `responses_websocket_options` 自定义 websocket keepalive 行为。增大 `ping_timeout` 以容忍延迟的 pong 帧，或设置 `ping_timeout=None` 以在保持 ping 启用的同时禁用心跳超时。当可靠性比 websocket 延迟更重要时，优先使用 HTTP/SSE 传输。 +- 启用 WebSocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多个轮次（以及嵌套的智能体作为工具调用）之间复用同一个 WebSocket 连接的多轮工作流，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助函数。请参见[运行智能体](../running_agents.md)指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。 +- 对于长时间推理轮次或存在延迟尖峰的网络，请使用 `responses_websocket_options` 自定义 WebSocket 保活行为。增大 `ping_timeout` 以容忍延迟的 pong 帧，或设置 `ping_timeout=None` 以在保持 ping 启用的同时禁用心跳超时。当可靠性比 WebSocket 延迟更重要时，请优先使用 HTTP/SSE 传输。 -## 非 OpenAI 模型 +## 非OpenAI模型 -如果你需要非 OpenAI 提供方，请从 SDK 的内置提供方集成点开始。在许多设置中，这已经足够，无需添加第三方适配器。每种模式的示例位于 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 +如果需要非OpenAI提供商，请从SDK的内置提供商集成点开始。在许多设置中，这已经足够，无需添加第三方适配器。每种模式的代码示例位于 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 -### 非 OpenAI 提供方集成方式 +### 非OpenAI提供商集成方式 | 方法 | 适用场景 | 范围 | | --- | --- | --- | -| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应成为大多数或所有智能体的默认端点 | 全局默认 | -| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义提供方应应用于单次运行 | 每次运行 | -| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同提供方或具体模型对象 | 每个智能体 | -| 第三方适配器 | 你需要由适配器管理的提供方覆盖范围或路由，而内置路径无法提供 | 参阅[第三方适配器](#third-party-adapters) | +| [`set_default_openai_client`][agents.set_default_openai_client] | 一个OpenAI兼容端点应作为大多数或所有智能体的默认端点 | 全局默认 | +| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义提供商应应用于单次运行 | 按运行 | +| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同的提供商或具体模型对象 | 按智能体 | +| 第三方适配器 | 你需要内置路径无法提供的、由适配器管理的提供商覆盖范围或路由 | 参见[第三方适配器](#third-party-adapters) | -你可以通过这些内置路径集成其他 LLM 提供方： +你可以通过这些内置路径集成其他LLM提供商： -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)。 +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)。 -在你没有来自 `platform.openai.com` 的 API key 的情况下，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[不同的追踪进程](../tracing.md)。 +如果你没有来自 `platform.openai.com` 的 API key，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置[其他追踪进程](../tracing.md)。 ``` python from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled @@ -245,19 +245,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model !!! note - 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM 提供方仍不支持 Responses API。如果你的 LLM 提供方支持它，我们建议使用 Responses。 + 在这些代码示例中，我们使用Chat Completions API/模型，因为许多LLM提供商仍不支持Responses API。如果你的LLM提供商支持它，我们建议使用Responses。 -## 在一个工作流中混用模型 +## 单个工作流中的模型混用 -在单个工作流中，你可能希望为每个智能体使用不同的模型。例如，可以使用较小、更快的模型进行分流，同时使用更大、更强的模型处理复杂任务。配置 [`Agent`][agents.Agent] 时，你可以通过以下任一方式选择特定模型： +在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以使用更小、更快的模型进行初筛，同时使用更大、能力更强的模型处理复杂任务。配置 [`Agent`][agents.Agent] 时，你可以通过以下任一方式选择特定模型： 1. 传入模型名称。 -2. 传入任意模型名称 + 一个能够将该名称映射到 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 +2. 传入任意模型名称 + 可将该名称映射到 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。 3. 直接提供 [`Model`][agents.models.interface.Model] 实现。 !!! note - 虽然我们的 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 两种形态，但我们建议每个工作流使用单一模型形态，因为这两种形态支持不同的功能和工具集合。如果你的工作流需要混用不同模型形态，请确保你使用的所有功能在两者上都可用。 + 虽然我们的SDK同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 这两种形态，但我们建议每个工作流使用单一模型形态，因为这两种形态支持的功能和工具集合不同。如果你的工作流需要混合搭配模型形态，请确保你使用的所有功能在两者上都可用。 ```python from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel @@ -290,10 +290,10 @@ async def main(): print(result.final_output) ``` -1. 直接设置 OpenAI 模型名称。 +1. 直接设置OpenAI模型的名称。 2. 提供 [`Model`][agents.models.interface.Model] 实现。 -当你想进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供可选的模型配置参数，例如 temperature。 +当你想进一步配置智能体所使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供了可选的模型配置参数，例如 temperature。 ```python from agents import Agent, ModelSettings @@ -306,22 +306,22 @@ english_agent = Agent( ) ``` -## 高级 OpenAI Responses 设置 +## 高级OpenAI Responses设置 -当你使用 OpenAI Responses 路径并需要更多控制时，请从 `ModelSettings` 开始。 +当你使用OpenAI Responses路径并需要更多控制时，请从 `ModelSettings` 开始。 ### 常见高级 `ModelSettings` 选项 -使用 OpenAI Responses API 时，多个请求字段已经有直接的 `ModelSettings` 字段，因此无需为它们使用 `extra_args`。 +使用OpenAI Responses API时，一些请求字段已经有直接对应的 `ModelSettings` 字段，因此不需要为它们使用 `extra_args`。 -- `parallel_tool_calls`：允许或禁止在同一轮中进行多个工具调用。 -- `truncation`：设置为 `"auto"`，让 Responses API 在上下文即将溢出时丢弃最旧的对话项，而不是失败。 -- `store`：控制生成的响应是否存储在服务端以供后续检索。这对于依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程很重要。 -- `context_management`：配置服务端上下文处理，例如带有 `compact_threshold` 的 Responses 压缩。 -- `prompt_cache_retention`：让缓存的提示词前缀保留更长时间，例如使用 `"24h"`。 -- `response_include`：请求更丰富的响应载荷，例如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 -- `top_logprobs`：请求输出文本的 top-token logprobs。SDK 还会自动添加 `message.output_text.logprobs`。 -- `retry`：选择启用由 runner 管理的模型调用重试设置。请参阅 [Runner 管理的重试](#runner-managed-retries)。 +- `parallel_tool_calls`：允许或禁止在同一轮次中进行多个工具调用。 +- `truncation`：设置为 `"auto"` 可让Responses API在上下文将要溢出时丢弃最早的对话项，而不是失败。 +- `store`：控制生成的响应是否存储在服务端以便之后检索。这对于依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程很重要。 +- `context_management`：配置服务端上下文处理，例如带有 `compact_threshold` 的Responses压缩。 +- `prompt_cache_retention`：更长时间保留缓存的 prompt 前缀，例如使用 `"24h"`。 +- `response_include`：请求更丰富的响应 payload，例如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。 +- `top_logprobs`：请求输出文本的 top-token logprobs。SDK还会自动添加 `message.output_text.logprobs`。 +- `retry`：为模型调用选择启用由 runner 管理的重试设置。参见[由 Runner 管理的重试](#runner-managed-retries)。 ```python from agents import Agent, ModelSettings @@ -341,15 +341,15 @@ research_agent = Agent( ) ``` -当你设置 `store=False` 时，Responses API 不会保留该响应用于后续服务端检索。这对于无状态或零数据保留风格的流程很有用，但也意味着原本会复用响应 ID 的功能需要改为依赖本地管理的状态。例如，当最后一个响应未被存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认的 `"auto"` 压缩路径切换为基于输入的压缩。请参阅[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 +当你设置 `store=False` 时，Responses API不会保留该响应以供之后进行服务端检索。这对于无状态或零数据保留风格的流程很有用，但也意味着原本会复用响应 ID 的功能需要依赖本地管理的状态。例如，当最后一个响应未被存储时，[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将其默认的 `"auto"` 压缩路径切换为基于输入的压缩。请参见[会话指南](../sessions/index.md#openai-responses-compaction-sessions)。 -服务端压缩不同于 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]。`context_management=[{"type": "compaction", "compact_threshold": ...}]` 会随每个 Responses API 请求发送，并且当渲染后的上下文超过阈值时，API 可以将压缩项作为响应的一部分发出。`OpenAIResponsesCompactionSession` 会在轮次之间调用独立的 `responses.compact` 端点，并重写本地会话历史。 +服务端压缩不同于 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]。`context_management=[{"type": "compaction", "compact_threshold": ...}]` 会随每个Responses API请求一起发送，并且当渲染后的上下文超过阈值时，API可以将压缩项作为响应的一部分发出。`OpenAIResponsesCompactionSession` 会在轮次之间调用独立的 `responses.compact` 端点，并重写本地会话历史。 -### 传递 `extra_args` +### `extra_args` 的传递方式 -当你需要 SDK 尚未在顶层直接公开的提供方特定或更新的请求字段时，请使用 `extra_args`。 +当你需要提供商特定的请求字段，或SDK尚未在顶层直接暴露的较新请求字段时，请使用 `extra_args`。 -此外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可以使用 `extra_args` 传递。不要同时通过直接的 `ModelSettings` 字段设置相同的请求字段。 +此外，当你使用OpenAI的Responses API时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们在顶层不可用，你也可以使用 `extra_args` 传入它们。不要同时通过直接的 `ModelSettings` 字段设置相同请求字段。 ```python from agents import Agent, ModelSettings @@ -365,9 +365,9 @@ english_agent = Agent( ) ``` -## Runner 管理的重试 +## 由 Runner 管理的重试 -重试仅在运行时生效，并且需要选择启用。除非你设置 `ModelSettings(retry=...)` 且你的重试策略选择重试，否则 SDK 不会重试一般模型请求。 +重试仅在运行时生效且需要显式启用。除非你设置了 `ModelSettings(retry=...)`，并且你的重试策略选择重试，否则SDK不会重试一般模型请求。 ```python from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies @@ -401,79 +401,79 @@ agent = Agent( | 字段 | 类型 | 说明 | | --- | --- | --- | -| `max_retries` | `int | None` | 初始请求之后允许的重试次数。 | -| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试且未返回显式延迟时的默认延迟策略。`backoff.max_delay` 仅限制此处计算出的退避延迟。它不会限制策略返回的显式延迟或 retry-after 提示。 | +| `max_retries` | `int | None` | 初始请求之后允许的重试尝试次数。 | +| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试但未返回显式延迟时使用的默认延迟策略。`backoff.max_delay` 只会限制这个计算得出的 backoff 延迟。它不会限制策略返回的显式延迟或 retry-after 提示。 | | `policy` | `RetryPolicy | None` | 决定是否重试的回调。该字段仅在运行时生效，不会被序列化。 | -重试策略会接收 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含： +重试策略会收到包含以下内容的 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]： -- `attempt` 和 `max_retries`，以便你可以做出感知尝试次数的决策。 -- `stream`，以便你可以在流式和非流式行为之间分支。 +- `attempt` 和 `max_retries`，以便你根据尝试次数做出决策。 +- `stream`，以便你在流式传输和非流式传输行为之间分支。 - `error`，用于原始检查。 - `normalized` 事实，例如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。 -- 当底层模型适配器可以提供重试指导时的 `provider_advice`。 +- 当底层模型适配器能够提供重试指导时，会包含 `provider_advice`。 -策略可以返回： +策略可以返回以下任一项： -- `True` / `False`，表示简单的重试决策。 -- 当你希望覆盖延迟或附加诊断原因时，返回 [`RetryDecision`][agents.retry.RetryDecision]。 +- `True` / `False`，用于简单的重试决策。 +- 当你想覆盖延迟或附加诊断原因时，返回 [`RetryDecision`][agents.retry.RetryDecision]。 -SDK 在 `retry_policies` 上导出开箱即用的辅助函数： +SDK在 `retry_policies` 上导出了现成辅助函数： | 辅助函数 | 行为 | | --- | --- | -| `retry_policies.never()` | 始终选择不重试。 | -| `retry_policies.provider_suggested()` | 在提供方重试建议可用时遵循该建议。 | +| `retry_policies.never()` | 始终不启用重试。 | +| `retry_policies.provider_suggested()` | 在提供商重试建议可用时遵循该建议。 | | `retry_policies.network_error()` | 匹配暂时性传输和超时故障。 | | `retry_policies.http_status([...])` | 匹配选定的 HTTP 状态码。 | -| `retry_policies.retry_after()` | 仅在 retry-after 提示可用时重试，并使用该延迟。此辅助函数将 retry-after 值视为显式策略延迟，因此 `backoff.max_delay` 不会限制它。 | -| `retry_policies.any(...)` | 当任一嵌套策略选择重试时重试。 | -| `retry_policies.all(...)` | 仅当每个嵌套策略都选择重试时才重试。 | +| `retry_policies.retry_after()` | 仅在 retry-after 提示可用时重试，并使用该延迟。该辅助函数会将 retry-after 值视为显式策略延迟，因此 `backoff.max_delay` 不会限制它。 | +| `retry_policies.any(...)` | 当任一嵌套策略选择启用时重试。 | +| `retry_policies.all(...)` | 仅当每个嵌套策略都选择启用时重试。 | -组合策略时，`provider_suggested()` 是最安全的首个构建块，因为当提供方能够区分时，它会保留提供方否决和重放安全批准。 +组合策略时，`provider_suggested()` 是最安全的首个构建块，因为当提供商能够区分时，它会保留提供商否决和重放安全批准。 ##### 安全边界 -某些失败永远不会自动重试： +某些故障永远不会自动重试： - 中止错误。 -- 提供方建议将重放标记为不安全的请求。 -- 输出已经以会使重放不安全的方式开始后的流式运行。 +- 提供商建议将重放标记为不安全的请求。 +- 输出已经以会使重放不安全的方式开始之后的流式传输运行。 -使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这些请求，仅靠 `network_error()` 或 `http_status([500])` 等非提供方谓词是不够的。重试策略应包含来自提供方的重放安全批准，通常通过 `retry_policies.provider_suggested()` 实现。 +使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这些请求，`network_error()` 或 `http_status([500])` 等非提供商判断条件本身并不足够。重试策略应包含来自提供商的重放安全批准，通常通过 `retry_policies.provider_suggested()` 实现。 ##### Runner 与智能体的合并行为 `retry` 会在 runner 级和智能体级 `ModelSettings` 之间进行深度合并： -- 智能体可以只覆盖 `retry.max_retries`，并仍然继承 runner 的 `policy`。 -- 智能体可以只覆盖 `retry.backoff` 的一部分，并保留来自 runner 的同级 backoff 字段。 +- 智能体可以只覆盖 `retry.max_retries`，同时仍继承 runner 的 `policy`。 +- 智能体可以只覆盖 `retry.backoff` 的一部分，并保留 runner 中同级的 backoff 字段。 - `policy` 仅在运行时生效，因此序列化后的 `ModelSettings` 会保留 `max_retries` 和 `backoff`，但省略回调本身。 -如需更完整的示例，请参阅 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 和[适配器支持的重试示例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。 +更多完整代码示例请参见 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 和[由适配器支持的重试示例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。 -## 非 OpenAI 提供方故障排除 +## 非OpenAI提供商故障排查 ### 追踪客户端错误 401 -如果你遇到与追踪相关的错误，这是因为 traces 会上传到 OpenAI 服务，而你没有 OpenAI API key。你有三个选项来解决此问题： +如果遇到与追踪相关的错误，这是因为追踪数据会上传到OpenAI服务，而你没有OpenAI API key。你有三个选项可解决此问题： 1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。 -2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传 traces，并且必须来自 [platform.openai.com](https://platform.openai.com/)。 -3. 使用非 OpenAI 追踪进程。请参阅[追踪文档](../tracing.md#custom-tracing-processors)。 +2. 为追踪设置OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。此 API key 仅用于上传追踪数据，且必须来自 [platform.openai.com](https://platform.openai.com/)。 +3. 使用非OpenAI追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。 ### Responses API 支持 -SDK 默认使用 Responses API，但许多其他 LLM 提供方仍不支持它。因此你可能会看到 404 或类似问题。要解决此问题，你有两个选项： +SDK默认使用Responses API，但许多其他LLM提供商仍不支持它。因此你可能会看到 404 错误或类似问题。要解决此问题，你有两个选项： 1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。如果你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`，这会生效。 -2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 +2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。代码示例在[此处](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。 ### Structured outputs 支持 -一些模型提供方不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误： +一些模型提供商不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下的错误： ``` @@ -481,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' ``` -这是一些模型提供方的局限——它们支持 JSON 输出，但不允许你指定用于输出的 `json_schema`。我们正在努力修复这一点，但建议依赖支持 JSON schema 输出的提供方，否则你的应用会经常因格式错误的 JSON 而中断。 +这是一些模型提供商的不足——它们支持 JSON 输出，但不允许你指定输出要使用的 `json_schema`。我们正在修复此问题，但我们建议依赖确实支持 JSON schema 输出的提供商，否则你的应用经常会因为格式错误的 JSON 而出错。 -## 跨提供方混用模型 +## 跨提供商的模型混用 -你需要了解模型提供方之间的功能差异，否则可能会遇到错误。例如，OpenAI 支持 structured outputs、多模态输入，以及托管的文件检索和网络检索，但许多其他提供方不支持这些功能。请注意这些限制： +你需要了解模型提供商之间的功能差异，否则可能会遇到错误。例如，OpenAI支持 structured outputs、多模态输入，以及托管的文件检索和网络检索，但许多其他提供商不支持这些功能。请注意这些限制： -- 不要将不受支持的 `tools` 发送给无法理解它们的提供方 +- 不要向无法理解的提供商发送不受支持的 `tools` - 在调用仅支持文本的模型之前，过滤掉多模态输入 -- 请注意，不支持结构化 JSON 输出的提供方偶尔会生成无效 JSON。 +- 请注意，不支持结构化 JSON 输出的提供商偶尔会生成无效 JSON。 ## 第三方适配器 -仅当 SDK 的内置提供方集成点不足时，才使用第三方适配器。如果你仅使用此 SDK 的 OpenAI 模型，请优先使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于你需要将 OpenAI 模型与非 OpenAI 提供方结合使用，或需要由适配器管理的提供方覆盖范围或路由，而内置路径无法提供的情况。适配器会在 SDK 与上游模型提供方之间增加另一层兼容层，因此功能支持和请求语义可能因提供方而异。SDK 目前包含 Any-LLM 和 LiteLLM，作为尽力而为的 beta 适配器集成。 +仅当SDK的内置提供商集成点不足够时，才使用第三方适配器。如果你只通过此SDK使用OpenAI模型，请优先使用内置的 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于需要将OpenAI模型与非OpenAI提供商组合使用，或需要内置路径无法提供的、由适配器管理的提供商覆盖范围或路由的场景。适配器会在SDK和上游模型提供商之间增加另一层兼容层，因此功能支持和请求语义可能因提供商而异。SDK目前包含 Any-LLM 和 LiteLLM，作为尽力而为的 beta 版适配器集成。 ### Any-LLM -Any-LLM 支持以尽力而为的 beta 形式包含在内，适用于你需要由 Any-LLM 管理的提供方覆盖范围或路由的情况。 +Any-LLM 支持以尽力而为的 beta 形式提供，适用于你需要由Any-LLM管理的提供商覆盖范围或路由的场景。 -根据上游提供方路径，Any-LLM 可能使用 Responses API、Chat Completions 兼容 API，或提供方特定的兼容层。 +根据上游提供商路径，Any-LLM 可能会使用Responses API、Chat Completions兼容 API，或提供商特定的兼容层。 -如果你需要 Any-LLM，请安装 `openai-agents[any-llm]`，然后从 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 或 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) 开始。你可以将 `any-llm/...` 模型名称与 [`MultiProvider`][agents.MultiProvider] 一起使用，直接实例化 `AnyLLMModel`，或在运行范围使用 `AnyLLMProvider`。如果你需要显式固定模型界面，请在构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。 +如果需要 Any-LLM，请安装 `openai-agents[any-llm]`，然后从 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 或 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) 开始。你可以将 `any-llm/...` 模型名称与 [`MultiProvider`][agents.MultiProvider] 一起使用，直接实例化 `AnyLLMModel`，或在运行范围内使用 `AnyLLMProvider`。如果需要显式固定模型接口，请在构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。 -Any-LLM 仍是第三方适配器层，因此提供方依赖和能力差距由上游 Any-LLM 而不是 SDK 定义。当上游提供方返回使用情况指标时，它们会自动传播，但流式 Chat Completions 后端可能需要 `ModelSettings(include_usage=True)` 才会发出使用情况块。如果你依赖 structured outputs、工具调用、使用情况报告或 Responses 特定行为，请验证你计划部署的确切提供方后端。 +Any-LLM 仍是第三方适配器层，因此提供商依赖和能力差距由上游Any-LLM定义，而不是由SDK定义。当上游提供商返回使用量指标时，这些指标会自动传播，但流式传输的Chat Completions后端可能需要先设置 `ModelSettings(include_usage=True)` 才会发出 usage 片段。如果你依赖 structured outputs、工具调用、使用量报告或Responses特定行为，请验证你计划部署的确切提供商后端。 ### LiteLLM -LiteLLM 支持以尽力而为的 beta 形式包含在内，适用于你需要 LiteLLM 特定的提供方覆盖范围或路由的情况。 +LiteLLM 支持以尽力而为的 beta 形式提供，适用于你需要 LiteLLM 特定的提供商覆盖范围或路由的场景。 -如果你需要 LiteLLM，请安装 `openai-agents[litellm]`，然后从 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 或 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) 开始。你可以使用 `litellm/...` 模型名称，或直接实例化 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 +如果需要 LiteLLM，请安装 `openai-agents[litellm]`，然后从 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 或 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) 开始。你可以使用 `litellm/...` 模型名称，或直接实例化 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]。 -一些 LiteLLM 支持的提供方默认不会填充 SDK 使用情况指标。如果你需要使用情况报告，请传入 `ModelSettings(include_usage=True)`，并且如果你依赖 structured outputs、工具调用、使用情况报告或适配器特定路由行为，请验证你计划部署的确切提供方后端。 \ No newline at end of file +一些由LiteLLM支持的提供商默认不会填充SDK使用量指标。如果需要使用量报告，请传入 `ModelSettings(include_usage=True)`；如果你依赖 structured outputs、工具调用、使用量报告或适配器特定的路由行为，请验证你计划部署的确切提供商后端。 \ No newline at end of file diff --git a/docs/zh/models/litellm.md b/docs/zh/models/litellm.md index 3c32c8df8b..30a41518de 100644 --- a/docs/zh/models/litellm.md +++ b/docs/zh/models/litellm.md @@ -8,6 +8,6 @@ search: window.location.replace("../#third-party-adapters"); -本页面已移动到[模型中的第三方适配器部分](index.md#third-party-adapters)。 +此页面已移至[模型中的第三方适配器部分](index.md#third-party-adapters)。 -如果未自动重定向，请使用上方链接。 \ No newline at end of file +如果没有自动重定向，请使用上面的链接。 \ No newline at end of file diff --git a/docs/zh/multi_agent.md b/docs/zh/multi_agent.md index f84f153362..f2947077ce 100644 --- a/docs/zh/multi_agent.md +++ b/docs/zh/multi_agent.md @@ -4,61 +4,61 @@ search: --- # 智能体编排 -编排是指你应用中智能体的流程。哪些智能体运行、按什么顺序运行，以及它们如何决定下一步发生什么？主要有两种智能体编排方式： +编排指的是应用中智能体的流程：哪些智能体会运行、以什么顺序运行，以及它们如何决定接下来发生什么？编排智能体主要有两种方式： -1. 让LLM做决策：利用LLM的智能进行规划、推理，并据此决定采取哪些步骤。 -2. 通过代码编排：通过你的代码来确定智能体流程。 +1. 让 LLM 做决策：利用 LLM 的智能进行规划、推理，并据此决定要采取哪些步骤。 +2. 通过代码编排：通过你的代码来确定智能体的流程。 -你可以混合使用这些模式。每种方式都有各自的权衡，详见下文。 +你也可以混合搭配这些模式。它们各有取舍，如下所述。 -## 通过LLM编排 +## 通过 LLM 编排 -智能体是配备了指令、工具调用和任务转移的LLM。这意味着，对于开放式任务，LLM可以自主规划如何完成任务，使用工具采取行动并获取数据，并通过任务转移将任务委派给子智能体。例如，一个研究智能体可以配备如下工具： +智能体是配备了 instructions、tools 和任务转移的 LLM。这意味着，面对开放式任务时，LLM 可以自主规划如何处理任务：使用工具执行操作并获取数据，并使用任务转移将任务委派给子智能体。例如，一个研究智能体可以配备如下工具： - 网络检索，用于在线查找信息 -- 文件检索与检索回传，用于搜索专有数据和连接 +- 文件检索与检索，用于搜索专有数据和连接 - 计算机操作，用于在计算机上执行操作 - 代码执行，用于进行数据分析 -- 向擅长规划、报告撰写等工作的专门智能体进行任务转移 +- 任务转移，用于转交给擅长规划、报告撰写等工作的专门智能体。 -### 核心SDK模式 +### 核心 SDK 模式 在 Python SDK 中，最常见的两种编排模式是： -| 模式 | 工作方式 | 最适用场景 | +| 模式 | 工作方式 | 最适合的场景 | | --- | --- | --- | -| Agents as tools | 管理智能体保持对对话的控制，并通过 `Agent.as_tool()` 调用专家智能体。 | 你希望由一个智能体负责最终答案、整合多个专家的输出，或在一个位置统一执行共享安全防护措施。 | -| 任务转移 | 分流智能体将对话路由给某个专家，该专家在本轮剩余时间内成为活动智能体。 | 你希望由专家直接回复、保持提示词聚焦，或在不由管理者转述结果的情况下切换指令。 | +| Agents as tools | 管理器智能体保持对对话的控制，并通过 `Agent.as_tool()` 调用专门智能体。 | 你希望由一个智能体负责最终答案、组合多个专门智能体的输出，或在一个地方统一执行共享的安全防护措施。 | +| 任务转移 | 分诊智能体将对话路由到专门智能体，而该专门智能体会在本轮剩余过程中成为活跃智能体。 | 你希望专门智能体直接响应、保持提示词聚焦，或在不由管理器叙述结果的情况下切换 instructions。 | -当专家只需协助完成边界清晰的子任务、但不应接管面向用户的对话时，使用**Agents as tools**。当“路由”本身就是工作流的一部分，且你希望被选中的专家主导下一阶段交互时，使用**任务转移**。 +当专门智能体应协助完成一个有边界的子任务、但不应接管面向用户的对话时，请使用**agents as tools**。当路由本身是工作流的一部分，并且你希望被选中的专门智能体负责交互的下一部分时，请使用**任务转移**。 -你也可以将两者结合。一个分流智能体可以先转移给专家，而该专家仍可将其他智能体作为工具调用来处理更窄的子任务。 +你也可以将两者结合使用。分诊智能体可以任务转移给专门智能体，而该专门智能体仍然可以将其他智能体作为工具来调用，以处理范围较窄的子任务。 -这种模式非常适合开放式任务，且你希望依赖LLM的智能。这里最重要的策略是： +当任务是开放式的，并且你希望依赖 LLM 的智能时，这种模式非常适合。这里最重要的策略是： -1. 投入高质量提示词。明确可用工具、如何使用它们，以及它必须遵守的参数边界。 -2. 监控并迭代你的应用。找出问题出现的位置，并迭代优化提示词。 -3. 允许智能体自省与改进。例如，让它在循环中运行并自我评估；或提供错误信息并让它自行改进。 -4. 使用在单一任务上表现卓越的专门智能体，而不是期望一个通用智能体样样精通。 -5. 投入使用[评测](https://platform.openai.com/docs/guides/evals)。这能让你训练智能体持续改进并更擅长任务。 +1. 投入精力编写好的提示词。明确说明有哪些工具可用、如何使用它们，以及必须在哪些参数范围内运行。 +2. 监控你的应用并不断迭代。观察问题出现在哪里，并迭代你的提示词。 +3. 允许智能体自省并改进。例如，让它在循环中运行并自我评议；或者提供错误消息，让它改进。 +4. 使用在某一项任务上表现出色的专门智能体，而不是期望一个通用智能体擅长所有事情。 +5. 投入使用[评估](https://platform.openai.com/docs/guides/evals)。这可以帮助你训练智能体，使其改进并更擅长完成任务。 -如果你想了解这种编排风格背后的核心 SDK 基本组件，请从[工具](tools.md)、[任务转移](handoffs.md)和[运行智能体](running_agents.md)开始。 +如果你想了解这种编排方式背后的核心 SDK 基础组件，请从[工具](tools.md)、[任务转移](handoffs.md)和[运行智能体](running_agents.md)开始。 ## 通过代码编排 -虽然通过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) 中提供了多个示例。 +我们在 [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) 中提供了许多代码示例。 ## 相关指南 -- [智能体](agents.md)：了解组合模式与智能体配置。 -- [工具](tools.md#agents-as-tools)：了解 `Agent.as_tool()` 与管理者风格编排。 -- [任务转移](handoffs.md)：了解专门智能体之间的委派。 -- [运行智能体](running_agents.md)：了解按次运行的编排控制与对话状态。 -- [快速开始](quickstart.md)：查看最小化端到端任务转移示例。 \ No newline at end of file +- [智能体](agents.md)：组合模式和智能体配置。 +- [工具](tools.md#agents-as-tools)：`Agent.as_tool()` 和管理器式编排。 +- [任务转移](handoffs.md)：专门智能体之间的委派。 +- [运行智能体](running_agents.md)：每次运行的编排控制和对话状态。 +- [快速入门](quickstart.md)：一个最小化的端到端任务转移示例。 \ No newline at end of file diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index 955ac1a587..56afce88a8 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -4,9 +4,9 @@ search: --- # 快速入门 -## 项目和虚拟环境的创建 +## 项目与虚拟环境的创建 -你只需执行一次。 +你只需要执行一次。 ```bash mkdir my_project @@ -16,7 +16,7 @@ python -m venv .venv ### 虚拟环境的激活 -每次启动新的终端会话时都要执行此操作。 +每次启动新的终端会话时都需要执行此操作。 在 macOS 或 Linux 上： @@ -60,9 +60,9 @@ $env:OPENAI_API_KEY = "sk-..." set "OPENAI_API_KEY=sk-..." ``` -## 第一个智能体的创建 +## 首个智能体的创建 -智能体通过 instructions、名称以及可选配置（例如特定模型）来定义。 +智能体由 instructions、名称以及特定模型等可选配置定义。 ```python from agents import Agent @@ -73,7 +73,7 @@ agent = Agent( ) ``` -## 第一个智能体的运行 +## 首个智能体的运行 使用 [`Runner`][agents.run.Runner] 执行智能体，并获取返回的 [`RunResult`][agents.result.RunResult]。 @@ -94,23 +94,23 @@ if __name__ == "__main__": asyncio.run(main()) ``` -对于第二轮，你可以将 `result.to_input_list()` 传回 `Runner.run(...)`，附加一个 [session](sessions/index.md)，或使用 `conversation_id` / `previous_response_id` 复用 OpenAI 服务管理的状态。[运行智能体](running_agents.md)指南对这些方法进行了比较。 +对于第二轮对话，你可以将 `result.to_input_list()` 传回 `Runner.run(...)`，附加一个[会话](sessions/index.md)，或者使用 `conversation_id` / `previous_response_id` 复用 OpenAI 服务端管理的状态。[运行智能体](running_agents.md)指南会比较这些方法。 -可使用以下经验法则： +可按以下经验法则选择： -| 如果你想要... | 从以下方式开始... | +| 如果你想要... | 从...开始 | | --- | --- | -| 完全手动控制且与提供商无关的历史记录 | `result.to_input_list()` | +| 完全手动控制和与提供商无关的历史记录 | `result.to_input_list()` | | 由 SDK 为你加载和保存历史记录 | [`session=...`](sessions/index.md) | -| OpenAI 管理的服务端延续 | `previous_response_id` 或 `conversation_id` | +| 由 OpenAI 管理的服务端延续 | `previous_response_id` 或 `conversation_id` | -有关取舍和确切行为，请参阅[运行智能体](running_agents.md#choose-a-memory-strategy)。 +有关权衡取舍和确切行为，请参阅[运行智能体](running_agents.md#choose-a-memory-strategy)。 -当任务主要依赖提示词、工具和对话状态时，请使用普通的 `Agent` 加 `Runner`。如果智能体应在隔离工作区中检查或修改真实文件，请转到 [Sandbox agents 快速入门](sandbox_agents.md)。 +当任务主要存在于提示词、工具和对话状态中时，使用普通的 `Agent` 加 `Runner`。如果智能体需要在隔离的工作区中检查或修改真实文件，请转到[沙盒智能体快速入门](sandbox_agents.md)。 -## 为智能体提供工具 +## 智能体工具的提供 -你可以为智能体提供工具来查找信息或执行操作。 +你可以为智能体提供工具，用于查找信息或执行操作。 ```python import asyncio @@ -142,16 +142,16 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## 添加更多智能体 +## 更多智能体的添加 -在选择多智能体模式之前，先决定谁应拥有最终答案： +在选择多智能体模式之前，请决定最终答案应由谁负责： -- **任务转移**：专家接管本轮中该部分的对话。 -- **Agents as tools**：编排器保持控制，并将专家作为工具调用。 +- **任务转移**：专家智能体会接管该轮对话中的相应部分。 +- **Agents as tools**：编排者保持控制，并将专家智能体作为工具调用。 -本快速入门继续使用**任务转移**，因为它是最简短的第一个示例。有关管理器风格的模式，请参阅[智能体编排](multi_agent.md)和[工具：agents as tools](tools.md#agents-as-tools)。 +本快速入门继续使用**任务转移**，因为这是最短的入门示例。有关管理者式模式，请参阅[智能体编排](multi_agent.md)和[工具：agents as tools](tools.md#agents-as-tools)。 -可以用同样的方式定义其他智能体。`handoff_description` 会为路由智能体提供有关何时委派的额外上下文。 +其他智能体也可以用同样的方式定义。`handoff_description` 会为路由智能体提供有关何时委派的额外上下文。 ```python from agents import Agent @@ -171,7 +171,7 @@ math_tutor_agent = Agent( ## 任务转移的定义 -在智能体上，你可以定义一组可选的传出任务转移选项，供其在解决任务时选择。 +在智能体上，你可以定义一组可选的外部任务转移选项，供它在解决任务时选择。 ```python triage_agent = Agent( @@ -183,7 +183,7 @@ triage_agent = Agent( ## 智能体编排的运行 -运行器会处理各个智能体的执行、任何任务转移以及任何工具调用。 +运行器会处理各个智能体的执行、所有任务转移以及所有工具调用。 ```python import asyncio @@ -205,21 +205,21 @@ if __name__ == "__main__": ## 参考代码示例 -该仓库包含相同核心模式的完整脚本： +仓库包含相同核心模式的完整脚本： - [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) 用于首次运行。 - [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) 用于工具调用。 - [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) 用于多智能体路由。 -## 查看追踪 +## 追踪的查看 -要回顾智能体运行期间发生的情况，请前往 [OpenAI Dashboard 中的 Trace viewer](https://platform.openai.com/traces)查看智能体运行的追踪。 +若要回顾智能体运行期间发生的情况，请前往 [OpenAI Dashboard 中的追踪查看器](https://platform.openai.com/traces)，查看智能体运行的追踪。 ## 后续步骤 -学习如何构建更复杂的智能体式流程： +了解如何构建更复杂的智能体式流程： - 了解如何配置[智能体](agents.md)。 -- 了解[运行智能体](running_agents.md)和 [sessions](sessions/index.md)。 -- 如果工作应在真实工作区内进行，请了解 [Sandbox agents](sandbox_agents.md)。 +- 了解[运行智能体](running_agents.md)和[会话](sessions/index.md)。 +- 如果工作应在真实工作区内进行，请了解[沙盒智能体](sandbox_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 555420100a..6c65530cef 100644 --- a/docs/zh/realtime/guide.md +++ b/docs/zh/realtime/guide.md @@ -4,52 +4,52 @@ search: --- # Realtime 智能体指南 -本指南说明 OpenAI Agents SDK 的 realtime 层如何映射到 OpenAI Realtime API，以及 Python SDK 在其之上添加了哪些额外行为。 +本指南说明 OpenAI Agents SDK的Realtime层如何映射到 OpenAI Realtime API，以及 Python SDK 在其之上增加了哪些额外行为。 !!! warning "Beta 功能" - Realtime 智能体处于 beta 阶段。随着我们改进实现，预计会有一些破坏性变更。 + Realtime 智能体处于 beta 阶段。随着我们改进实现，可能会出现一些破坏性变更。 !!! note "从这里开始" 如果你想使用默认的 Python 路径，请先阅读[快速入门](quickstart.md)。如果你正在决定你的应用应使用服务端 WebSocket 还是 SIP，请阅读 [Realtime 传输](transport.md)。浏览器 WebRTC 传输不属于 Python SDK 的一部分。 -## 概述 +## 概览 -Realtime 智能体会与 Realtime API 保持长连接，以便模型能够增量处理文本和音频、流式传输音频输出、调用工具，并在每一轮无需重新启动新请求的情况下处理中断。 +Realtime 智能体会与 Realtime API 保持一个长连接，使模型能够增量处理文本和音频、流式传输音频输出、调用工具，并在无需每轮对话都重新发起新请求的情况下处理打断。 主要的 SDK 组件包括： -- **RealtimeAgent**: 单个 realtime 专家的 instructions、工具、输出安全防护措施和任务转移 -- **RealtimeRunner**: 将起始智能体连接到 realtime 传输的会话工厂 -- **RealtimeSession**: 用于发送输入、接收事件、跟踪历史并执行工具的实时会话 -- **RealtimeModel**: 传输抽象。默认值是 OpenAI 的服务端 WebSocket 实现。 +- **RealtimeAgent**：一个 Realtime 专家智能体的指令、工具、输出安全防护措施和任务转移 +- **RealtimeRunner**：会话工厂，将起始智能体连接到 Realtime 传输层 +- **RealtimeSession**：实时会话，用于发送输入、接收事件、跟踪历史记录并执行工具 +- **RealtimeModel**：传输抽象。默认是 OpenAI 的服务端 WebSocket 实现。 ## 会话生命周期 -典型的 realtime 会话如下： +典型的 Realtime 会话如下： 1. 创建一个或多个 `RealtimeAgent`。 2. 使用起始智能体创建一个 `RealtimeRunner`。 -3. 调用 `await runner.run()` 以获取 `RealtimeSession`。 +3. 调用 `await runner.run()` 以获取一个 `RealtimeSession`。 4. 使用 `async with session:` 或 `await session.enter()` 进入会话。 5. 使用 `send_message()` 或 `send_audio()` 发送用户输入。 6. 迭代会话事件，直到对话结束。 -与纯文本运行不同，`runner.run()` 不会立即生成最终结果。它会返回一个实时会话对象，该对象会让本地历史、后台工具执行、安全防护措施状态以及活动智能体配置与传输层保持同步。 +与纯文本运行不同，`runner.run()` 不会立即生成最终结果。它会返回一个实时会话对象，该对象会让本地历史记录、后台工具执行、安全防护措施状态以及活动智能体配置与传输层保持同步。 -默认情况下，`RealtimeRunner` 使用 `OpenAIRealtimeWebSocketModel`，因此默认的 Python 路径是连接到 Realtime API 的服务端 WebSocket 连接。如果传入不同的 `RealtimeModel`，相同的会话生命周期和智能体功能仍然适用，但连接机制可能会改变。 +默认情况下，`RealtimeRunner` 使用 `OpenAIRealtimeWebSocketModel`，因此默认的 Python 路径是连接到 Realtime API 的服务端 WebSocket。如果传入不同的 `RealtimeModel`，相同的会话生命周期和智能体功能仍然适用，但连接机制可能会改变。 -## 智能体和会话配置 +## 智能体与会话配置 -`RealtimeAgent` 有意比常规 `Agent` 类型更窄： +`RealtimeAgent` 的范围有意比常规 `Agent` 类型更窄： - 模型选择在会话级别配置，而不是按智能体配置。 -- 不支持 structured outputs。 -- 可以配置语音，但在会话已经生成过语音音频后就无法更改。 -- Instructions、工具调用、任务转移、钩子和输出安全防护措施仍然都可用。 +- 不支持 Structured outputs。 +- 可以配置语音，但在会话已经生成过语音音频后无法更改。 +- 指令、工具调用、任务转移、钩子和输出安全防护措施仍然都可以使用。 -`RealtimeSessionModelSettings` 同时支持较新的嵌套 `audio` 配置和较旧的扁平别名。新代码建议使用嵌套形式，并从 `gpt-realtime-2` 开始构建新的 realtime 智能体： +`RealtimeSessionModelSettings` 同时支持较新的嵌套 `audio` 配置和较旧的扁平别名。新代码建议优先使用嵌套形式，并为新的 Realtime 智能体从 `gpt-realtime-2` 开始： ```python runner = RealtimeRunner( @@ -73,11 +73,11 @@ runner = RealtimeRunner( 有用的会话级设置包括： -- `audio.input.format`, `audio.output.format` +- `audio.input.format`、`audio.output.format` - `audio.input.transcription` - `audio.input.noise_reduction` - `audio.input.turn_detection` -- `audio.output.voice`, `audio.output.speed` +- `audio.output.voice`、`audio.output.speed` - `output_modalities` - `tool_choice` - `prompt` @@ -91,13 +91,13 @@ runner = RealtimeRunner( - `tool_error_formatter` - `tracing_disabled` -完整的类型化接口请参阅 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。 +完整的类型化接口面请参见 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。 -## 输入和输出 +## 输入与输出 ### 文本和结构化用户消息 -使用 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] 发送纯文本或结构化 realtime 消息。 +使用 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] 发送纯文本或结构化 Realtime 消息。 ```python from agents.realtime import RealtimeUserInputMessage @@ -115,7 +115,7 @@ message: RealtimeUserInputMessage = { await session.send_message(message) ``` -结构化消息是在 realtime 对话中包含图像输入的主要方式。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) 中的示例 Web 演示会以这种方式转发 `input_image` 消息。 +结构化消息是在 Realtime 对话中包含图像输入的主要方式。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) 中的示例 Web 演示就是以这种方式转发 `input_image` 消息。 ### 音频输入 @@ -125,21 +125,21 @@ await session.send_message(message) await session.send_audio(audio_bytes) ``` -如果服务端轮次检测被禁用，你需要负责标记轮次边界。高级便捷方法是： +如果禁用了服务端回合检测，你需要负责标记回合边界。高层便捷方法是： ```python await session.send_audio(audio_bytes, commit=True) ``` -如果需要更低级别的控制，也可以通过底层模型传输发送原始客户端事件，例如 `input_audio_buffer.commit`。 +如果你需要更低层的控制，也可以通过底层模型传输层发送原始客户端事件，例如 `input_audio_buffer.commit`。 ### 手动响应控制 -`session.send_message()` 会使用高级路径发送用户输入，并为你启动响应。原始音频缓冲并**不会**在每种配置中都自动执行相同操作。 +`session.send_message()` 会通过高层路径发送用户输入，并为你启动响应。原始音频缓冲在所有配置中**并不会**自动执行相同操作。 -在 Realtime API 层面，手动轮次控制意味着用原始 `session.update` 清除 `turn_detection`，然后自行发送 `input_audio_buffer.commit` 和 `response.create`。 +在 Realtime API 层面，手动回合控制意味着使用原始 `session.update` 清空 `turn_detection`，然后自行发送 `input_audio_buffer.commit` 和 `response.create`。 -如果你正在手动管理轮次，可以通过模型传输发送原始客户端事件： +如果你正在手动管理回合，可以通过模型传输层发送原始客户端事件： ```python from agents.realtime.model_inputs import RealtimeModelSendRawMessage @@ -153,45 +153,45 @@ await session.model.send_event( ) ``` -此模式在以下情况下很有用： +此模式适用于以下情况： -- `turn_detection` 被禁用，并且你想决定模型何时响应 +- `turn_detection` 已禁用，并且你想决定模型何时响应 - 你想在触发响应前检查或拦截用户输入 - 你需要为带外响应使用自定义提示词 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) 中的 SIP 示例使用原始 `response.create` 来强制发送开场问候。 -## 事件、历史和中断 +## 事件、历史记录和打断 -`RealtimeSession` 会发出更高层级的 SDK 事件，同时在你需要时仍会转发原始模型事件。 +`RealtimeSession` 会发出更高层的 SDK 事件，同时在你需要时仍会转发原始模型事件。 -高价值的会话事件包括： +高价值会话事件包括： -- `audio`, `audio_end`, `audio_interrupted` -- `agent_start`, `agent_end` -- `tool_start`, `tool_end`, `tool_approval_required` +- `audio`、`audio_end`、`audio_interrupted` +- `agent_start`、`agent_end` +- `tool_start`、`tool_end`、`tool_approval_required` - `handoff` -- `history_added`, `history_updated` +- `history_added`、`history_updated` - `guardrail_tripped` - `input_audio_timeout_triggered` - `error` - `raw_model_event` -对 UI 状态最有用的事件通常是 `history_added` 和 `history_updated`。它们会将会话的本地历史作为 `RealtimeItem` 对象公开，包括用户消息、助手消息和工具调用。 +对 UI 状态最有用的事件通常是 `history_added` 和 `history_updated`。它们会将会话的本地历史记录公开为 `RealtimeItem` 对象，包括用户消息、助手消息和工具调用。 -### 中断和播放跟踪 +### 打断和播放跟踪 -当用户打断助手时，会话会发出 `audio_interrupted` 并更新历史，使服务端对话与用户实际听到的内容保持一致。 +当用户打断助手时，会话会发出 `audio_interrupted` 并更新历史记录，以便服务端对话与用户实际听到的内容保持一致。 -在低延迟本地播放中，默认播放跟踪器通常已经足够。在远程或延迟播放场景中，尤其是电话场景，请使用 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]，这样中断截断会基于实际播放进度，而不是假设所有生成的音频都已经被听到。 +在低延迟本地播放中，默认播放跟踪器通常已经足够。在远程或延迟播放场景中，尤其是电话场景，请使用 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]，以便根据实际播放进度而不是假设所有已生成音频都已被听到来进行打断截断。 -[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) 中的 Twilio 示例展示了此模式。 +[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) 中的 Twilio 示例展示了这种模式。 ## 工具、审批、任务转移和安全防护措施 ### 工具调用 -Realtime 智能体支持在实时对话期间使用工具调用： +Realtime 智能体支持在实时对话中使用工具调用： ```python from agents import function_tool @@ -212,7 +212,7 @@ agent = RealtimeAgent( ### 工具审批 -工具调用可以要求在执行前进行人工审批。发生这种情况时，会话会发出 `tool_approval_required` 并暂停工具运行，直到你调用 `approve_tool_call()` 或 `reject_tool_call()`。 +工具调用可以要求在执行前获得人工批准。发生这种情况时，会话会发出 `tool_approval_required`，并暂停工具运行，直到你调用 `approve_tool_call()` 或 `reject_tool_call()`。 ```python async for event in session: @@ -220,11 +220,11 @@ async for event in session: await session.approve_tool_call(event.call_id) ``` -有关具体的服务端审批循环，请参阅 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)。人在回路文档也会在[人在回路](../human_in_the_loop.md)中指回此流程。 +有关具体的服务端审批循环，请参见 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)。人在回路文档也会在[人在回路](../human_in_the_loop.md)中回到这一流程。 ### 任务转移 -Realtime 任务转移允许一个智能体将实时对话转交给另一位专家： +Realtime 任务转移允许一个智能体将实时对话转交给另一个专家智能体： ```python from agents.realtime import RealtimeAgent, realtime_handoff @@ -241,11 +241,11 @@ main_agent = RealtimeAgent( ) ``` -裸 `RealtimeAgent` 任务转移会被自动包装，而 `realtime_handoff(...)` 允许你自定义名称、描述、验证、回调和可用性。Realtime 任务转移不支持常规任务转移 `input_filter`。 +裸 `RealtimeAgent` 任务转移会被自动包装，而 `realtime_handoff(...)` 可让你自定义名称、描述、验证、回调和可用性。Realtime 任务转移**不**支持常规任务转移的 `input_filter`。 ### 安全防护措施 -Realtime 智能体仅支持输出安全防护措施。它们基于去抖后的转录文本累积运行，而不是在每个部分 token 上运行，并且会发出 `guardrail_tripped` 而不是抛出异常。 +Realtime 智能体仅支持输出安全防护措施。它们会在经过防抖处理的转写累积内容上运行，而不是在每个部分 token 上运行，并且会发出 `guardrail_tripped`，而不是抛出异常。 ```python from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail @@ -265,17 +265,17 @@ agent = RealtimeAgent( ) ``` -当 realtime 输出安全防护措施被触发时，会话会中断活动响应，强制执行 -`response.cancel`，发出 `guardrail_tripped`，并发送一条后续用户消息来指出 -被触发的安全防护措施，以便模型生成替代响应。你的音频播放器仍应 -监听 `audio_interrupted` 并立即停止本地播放，因为安全防护措施基于 -去抖后的转录文本运行，而在触发线触发时，可能已经缓冲了一些音频。 +当 Realtime 输出安全防护措施被触发时，会话会打断活动响应，强制执行 +`response.cancel`，发出 `guardrail_tripped`，并发送一条后续用户消息，指明被触发的 +安全防护措施，以便模型生成替代响应。你的音频播放器仍应 +监听 `audio_interrupted` 并立即停止本地播放，因为安全防护措施运行在 +经过防抖处理的转写文本上，且触发器触发时可能已有部分音频被缓冲。 -## SIP 和电话 +## SIP 与电话 -Python SDK 通过 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] 提供一流的 SIP attach 流程。 +Python SDK 通过 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] 提供一等支持的 SIP 挂接流程。 -当呼叫通过 Realtime Calls API 到达，并且你想将智能体会话附加到生成的 `call_id` 时，请使用它： +当呼叫通过 Realtime Calls API 到达，并且你想将智能体会话挂接到生成的 `call_id` 时，请使用它： ```python from agents.realtime import RealtimeRunner @@ -292,18 +292,18 @@ async with await runner.run( ... ``` -如果需要先接听呼叫，并且希望接听 payload 与智能体派生的会话配置匹配，请使用 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`。完整流程见 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)。 +如果你需要先接受呼叫，并且希望接受载荷与基于智能体生成的会话配置匹配，请使用 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`。完整流程见 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)。 -## 低级访问和自定义端点 +## 低层访问和自定义端点 你可以通过 `session.model` 访问底层传输对象。 在以下情况下使用它： - 通过 `session.model.add_listener(...)` 使用自定义监听器 -- 原始客户端事件，例如 `response.create` 或 `session.update` +- 使用原始客户端事件，例如 `response.create` 或 `session.update` - 通过 `model_config` 处理自定义 `url`、`headers` 或 `api_key` -- 将 `call_id` 附加到现有 realtime 呼叫 +- 将 `call_id` 挂接到现有 Realtime 呼叫 `RealtimeModelConfig` 支持： @@ -314,9 +314,9 @@ async with await runner.run( - `playback_tracker` - `call_id` -此代码库随附的 `call_id` 示例是 SIP。更广泛的 Realtime API 也会在一些服务端控制流中使用 `call_id`，但这里没有将它们打包为 Python 示例。 +此仓库随附的 `call_id` 示例是 SIP。更广泛的 Realtime API 也会将 `call_id` 用于某些服务端控制流程，但这些流程在此处未打包为 Python 示例。 -连接到 Azure OpenAI 时，请传入 GA Realtime 端点 URL 和显式 headers。例如： +连接到 Azure OpenAI 时，请传入 GA Realtime 端点 URL 和显式标头。例如： ```python session = await runner.run( @@ -327,7 +327,7 @@ session = await runner.run( ) ``` -对于基于 token 的身份验证，请在 `headers` 中使用 bearer token： +对于基于令牌的身份验证，请在 `headers` 中使用 bearer token： ```python session = await runner.run( @@ -338,7 +338,7 @@ session = await runner.run( ) ``` -如果传入 `headers`，SDK 不会自动添加 `Authorization`。避免将旧版 beta 路径（`/openai/realtime?api-version=...`）与 realtime 智能体一起使用。 +如果传入 `headers`，SDK 不会自动添加 `Authorization`。请避免在 Realtime 智能体中使用旧版 beta 路径（`/openai/realtime?api-version=...`）。 ## 延伸阅读 diff --git a/docs/zh/realtime/quickstart.md b/docs/zh/realtime/quickstart.md index 05e4145d87..1a9e3b3d63 100644 --- a/docs/zh/realtime/quickstart.md +++ b/docs/zh/realtime/quickstart.md @@ -4,21 +4,21 @@ search: --- # 快速入门 -Python SDK 中的实时智能体是基于 OpenAI Realtime API、通过 WebSocket 传输构建的服务端低延迟智能体。 +Python SDK 中的实时智能体是基于通过 WebSocket 传输的 OpenAI Realtime API 构建的服务端低延迟智能体。 !!! warning "Beta 功能" - 实时智能体处于 beta 阶段。随着我们改进实现，预计会有一些破坏性变更。 + 实时智能体目前处于 Beta 阶段。随着我们改进实现，预计可能会有一些破坏性变更。 !!! note "Python SDK 边界" - Python SDK **不**提供浏览器 WebRTC 传输。本页仅涵盖通过服务端 WebSocket 由 Python 管理的实时会话。使用此 SDK 进行服务端编排、工具、审批和电话集成。另请参阅[实时传输](transport.md)。 + Python SDK **不**提供浏览器 WebRTC 传输。本页仅介绍通过服务端 WebSocket 由 Python 管理的实时会话。使用此 SDK 进行服务端编排、工具、审批和电话集成。另请参阅[实时传输](transport.md)。 -## 前提条件 +## 先决条件 - Python 3.10 或更高版本 - OpenAI API 密钥 -- 基本了解 OpenAI Agents SDK +- 基本熟悉 OpenAI Agents SDK ## 安装 @@ -49,7 +49,7 @@ agent = RealtimeAgent( ### 3. 配置运行器 -对于新代码，建议使用嵌套的 `audio.input` / `audio.output` 会话设置结构。对于新的实时智能体，请从 `gpt-realtime-2` 开始。 +新代码建议优先使用嵌套的 `audio.input` / `audio.output` 会话设置结构。对于新的实时智能体，请从 `gpt-realtime-2` 开始。 ```python runner = RealtimeRunner( @@ -106,29 +106,29 @@ if __name__ == "__main__": `session.send_message()` 接受纯字符串或结构化实时消息。对于原始音频块，请使用 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]。 -## 本快速入门不包含的内容 +## 本快速入门未包含的内容 - 麦克风采集和扬声器播放代码。请参阅 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 中的实时示例。 -- SIP / 电话附加流程。请参阅[实时传输](transport.md)和 [SIP 小节](guide.md#sip-and-telephony)。 +- SIP / 电话连接流程。请参阅[实时传输](transport.md)和 [SIP 部分](guide.md#sip-and-telephony)。 ## 关键设置 -基本会话可用后，大多数人接下来会使用的设置包括： +基本会话正常工作后，大多数人接下来会用到的设置包括： - `model_name` - `audio.input.format`, `audio.output.format` - `audio.input.transcription` - `audio.input.noise_reduction` -- `audio.input.turn_detection` 用于自动轮次检测 +- `audio.input.turn_detection`，用于自动轮次检测 - `audio.output.voice` - `tool_choice`, `prompt`, `tracing` - `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter` -较旧的扁平别名，例如 `input_audio_format`、`output_audio_format`、`input_audio_transcription` 和 `turn_detection` 仍然可用，但对于新代码，建议使用嵌套的 `audio` 设置。 +较旧的扁平别名（如 `input_audio_format`、`output_audio_format`、`input_audio_transcription` 和 `turn_detection`）仍然可用，但新代码建议优先使用嵌套的 `audio` 设置。 -对于手动轮次控制，请使用原始的 `session.update` / `input_audio_buffer.commit` / `response.create` 流程，如[实时智能体指南](guide.md#manual-response-control)中所述。 +如需手动控制轮次，请使用原始的 `session.update` / `input_audio_buffer.commit` / `response.create` 流程，具体见[实时智能体指南](guide.md#manual-response-control)。 -完整模式请参阅 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。 +完整架构请参阅 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 和 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]。 ## 连接选项 @@ -138,7 +138,7 @@ if __name__ == "__main__": export OPENAI_API_KEY="your-api-key-here" ``` -或者在启动会话时直接传入： +或在启动会话时直接传入： ```python session = await runner.run(model_config={"api_key": "your-api-key"}) @@ -148,15 +148,15 @@ session = await runner.run(model_config={"api_key": "your-api-key"}) - `url`：自定义 WebSocket 端点 - `headers`：自定义请求标头 -- `call_id`：附加到现有实时通话。在此仓库中，记录的附加流程是 SIP。 +- `call_id`：连接到现有实时通话。在此仓库中，记录的连接流程是 SIP。 - `playback_tracker`：报告用户实际听到了多少音频 -如果你显式传入 `headers`，SDK 将**不会**为你注入 `Authorization` 标头。 +如果你显式传入 `headers`，SDK **不会**为你注入 `Authorization` 标头。 -连接到 Azure OpenAI 时，请在 `model_config["url"]` 中传入 GA Realtime 端点 URL，并显式传入标头。避免将旧版 beta 路径（`/openai/realtime?api-version=...`）与实时智能体一起使用。详情请参阅[实时智能体指南](guide.md#low-level-access-and-custom-endpoints)。 +连接到 Azure OpenAI 时，请在 `model_config["url"]` 中传入 GA Realtime 端点 URL，并显式传入标头。使用实时智能体时，请避免使用旧版 Beta 路径（`/openai/realtime?api-version=...`）。详情请参阅[实时智能体指南](guide.md#low-level-access-and-custom-endpoints)。 ## 后续步骤 -- 阅读[实时传输](transport.md)，以在服务端 WebSocket 和 SIP 之间进行选择。 +- 阅读[实时传输](transport.md)，以便在服务端 WebSocket 和 SIP 之间做出选择。 - 阅读[实时智能体指南](guide.md)，了解生命周期、结构化输入、审批、任务转移、安全防护措施和低级控制。 - 浏览 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) 中的示例。 \ No newline at end of file diff --git a/docs/zh/realtime/transport.md b/docs/zh/realtime/transport.md index 6eb2cbf1a2..c2285c42ec 100644 --- a/docs/zh/realtime/transport.md +++ b/docs/zh/realtime/transport.md @@ -2,75 +2,75 @@ search: exclude: true --- -# Realtime 传输 +# 实时传输 -使用本页面来判断 realtime 智能体如何适配你的 Python 应用。 +使用本页判断实时智能体如何适配你的 Python 应用程序。 !!! note "Python SDK 边界" - Python SDK **不**包含浏览器 WebRTC 传输。本页面仅介绍 Python SDK 的传输选择：服务端 WebSockets 和 SIP 附加流程。浏览器 WebRTC 是独立的平台主题，文档见官方指南 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/)。 + Python SDK **不**包含浏览器 WebRTC 传输。本页仅讨论 Python SDK 的传输选择：服务端 WebSocket 和 SIP 接入流程。浏览器 WebRTC 是一个单独的平台主题，记录在官方 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 指南中。 ## 决策指南 -| 目标 | 起步项 | 原因 | +| 目标 | 从这里开始 | 原因 | | --- | --- | --- | -| 构建由服务端管理的 realtime 应用 | [Quickstart](quickstart.md) | 默认的 Python 路径是由 `RealtimeRunner` 管理的服务端 WebSocket 会话。 | -| 理解应选择哪种传输和部署形态 | 本页面 | 在你确定传输或部署形态之前先参考此页。 | -| 将智能体附加到电话或 SIP 通话 | [Realtime guide](guide.md) 和 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 仓库提供了由 `call_id` 驱动的 SIP 附加流程。 | +| 构建由服务端管理的实时应用 | [快速入门](quickstart.md) | 默认的 Python 路径是由 `RealtimeRunner` 管理的服务端 WebSocket 会话。 | +| 了解应选择哪种传输和部署形态 | 本页 | 在确定传输或部署形态之前使用本页。 | +| 将智能体接入电话或 SIP 通话 | [实时指南](guide.md) 和 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 该仓库提供了由 `call_id` 驱动的 SIP 接入流程。 | -## 服务端 WebSocket 是默认 Python 路径 +## 默认 Python 路径：服务端 WebSocket -除非你传入自定义 `RealtimeModel`，否则 `RealtimeRunner` 使用 `OpenAIRealtimeWebSocketModel`。 +除非你传入自定义 `RealtimeModel`，否则 `RealtimeRunner` 会使用 `OpenAIRealtimeWebSocketModel`。 -这意味着标准的 Python 拓扑如下： +这意味着标准 Python 拓扑如下： 1. 你的 Python 服务创建一个 `RealtimeRunner`。 2. `await runner.run()` 返回一个 `RealtimeSession`。 -3. 进入该会话并发送文本、结构化消息或音频。 -4. 消费 `RealtimeSessionEvent` 项，并将音频或转录转发到你的应用。 +3. 进入会话并发送文本、结构化消息或音频。 +4. 消费 `RealtimeSessionEvent` 项，并将音频或转录文本转发到你的应用程序。 -这是核心演示应用、CLI 示例和 Twilio Media Streams 示例使用的拓扑： +这是核心演示应用、CLI 示例和 Twilio Media Streams 示例所使用的拓扑： - [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app) - [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli) - [`examples/realtime/twilio`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio) -当你的服务负责音频管线、工具执行、审批流程和历史记录处理时，请使用此路径。 +当你的服务负责音频管道、工具执行、审批流程和历史记录处理时，请使用此路径。 -## SIP 附加是电话路径 +## 电话路径：SIP 接入 -对于本仓库中记录的电话流程，Python SDK 通过 `call_id` 附加到现有 realtime 通话。 +对于此仓库中记录的电话流程，Python SDK 会通过 `call_id` 接入现有的实时通话。 该拓扑如下： -1. OpenAI 向你的服务发送 webhook，例如 `realtime.call.incoming`。 -2. 你的服务通过 Realtime Calls API 接受通话。 -3. 你的 Python 服务启动 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`。 -4. 会话使用 `model_config={"call_id": ...}` 建立连接，然后像其他 realtime 会话一样处理事件。 +1. OpenAI 向你的服务发送一个 webhook，例如 `realtime.call.incoming`。 +2. 你的服务通过 Realtime Calls API 接受该通话。 +3. 你的 Python 服务启动一个 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`。 +4. 会话使用 `model_config={"call_id": ...}` 连接，然后像任何其他实时会话一样处理事件。 这是 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) 中展示的拓扑。 -更广义的 Realtime API 也会在某些服务端控制模式中使用 `call_id`，但本仓库提供的附加示例是 SIP。 +更广泛的 Realtime API 也会在一些服务端控制模式中使用 `call_id`，但此仓库提供的接入示例是 SIP。 -## 浏览器 WebRTC 不属于此 SDK 范围 +## 本 SDK 范围之外的浏览器 WebRTC -如果你应用的主要客户端是使用 Realtime WebRTC 的浏览器： +如果你的应用的主要客户端是使用 Realtime WebRTC 的浏览器： -- 将其视为超出本仓库 Python SDK 文档范围。 -- 使用官方文档 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 和 [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) 来了解客户端流程和事件模型。 -- 如果你需要在浏览器 WebRTC 客户端之上使用 sideband 服务端连接，请使用官方指南 [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/)。 -- 不要期待本仓库提供浏览器侧 `RTCPeerConnection` 抽象或现成的浏览器 WebRTC 示例。 +- 将其视为不在此仓库的 Python SDK 文档范围内。 +- 使用官方 [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 和 [实时对话](https://developers.openai.com/api/docs/guides/realtime-conversations/)文档，了解客户端流程和事件模型。 +- 如果你需要在浏览器 WebRTC 客户端之上使用旁路服务端连接，请使用官方 [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 指南。 +- 不要期望此仓库提供浏览器端 `RTCPeerConnection` 抽象或现成的浏览器 WebRTC 示例。 -本仓库目前也未提供浏览器 WebRTC 加 Python sideband 的示例。 +此仓库目前也未提供浏览器 WebRTC 加 Python 旁路服务端示例。 -## 自定义端点和附加点 +## 自定义端点和接入点 -[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] 中的传输配置接口让你可以调整默认路径： +[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] 中的传输配置界面允许你调整默认路径： -- `url`: 覆盖 WebSocket 端点 -- `headers`: 提供显式请求头，例如 Azure 认证请求头 -- `api_key`: 直接传递 API key 或通过回调传递 -- `call_id`: 附加到现有 realtime 通话。在本仓库中，文档化示例是 SIP。 -- `playback_tracker`: 上报实际播放进度以处理中断 +- `url`：覆盖 WebSocket 端点 +- `headers`：提供显式标头，例如 Azure 身份验证标头 +- `api_key`：直接传入 API key，或通过回调传入 +- `call_id`：接入现有实时通话。在此仓库中，记录的示例是 SIP。 +- `playback_tracker`：报告实际播放进度，以便处理中断 -选定拓扑后，详细的生命周期和能力接口请参见 [Realtime agents guide](guide.md)。 \ No newline at end of file +选择拓扑后，请参阅[实时智能体指南](guide.md)，了解详细生命周期和能力界面。 \ No newline at end of file diff --git a/docs/zh/release.md b/docs/zh/release.md index 9a73fe38c5..8e12ea4ff9 100644 --- a/docs/zh/release.md +++ b/docs/zh/release.md @@ -4,15 +4,15 @@ search: --- # 发布流程/变更日志 -该项目遵循略有修改的语义化版本控制，采用 `0.Y.Z` 的形式。开头的 `0` 表示 SDK 仍在快速演进。各组成部分按如下方式递增： +该项目遵循略微修改过的语义化版本控制，版本形式为 `0.Y.Z`。开头的 `0` 表示 SDK 仍在快速演进。各组成部分按如下方式递增： -## Minor（`Y`）版本 +## 次版本（`Y`） -对于任何未标记为 beta 的公共接口中的**破坏性变更**，我们会递增 minor 版本 `Y`。例如，从 `0.0.x` 到 `0.1.x` 可能包含破坏性变更。 +对于任何未标记为 beta 的公共接口中的**破坏性变更**，我们会增加次版本 `Y`。例如，从 `0.0.x` 升级到 `0.1.x` 可能包含破坏性变更。 -如果你不想遇到破坏性变更，我们建议在项目中固定使用 `0.0.x` 版本。 +如果你不希望遇到破坏性变更，建议在项目中固定使用 `0.0.x` 版本。 -## Patch（`Z`）版本 +## 补丁版本（`Z`） 对于非破坏性变更，我们会递增 `Z`： @@ -25,9 +25,9 @@ search: ### 0.17.0 -在此版本中，沙箱本地源材料化会将 `LocalFile.src` 和 `LocalDir.src` 保持在材料化 `base_dir` 内，除非源路径被 `Manifest.extra_path_grants` 覆盖。`base_dir` 是应用 manifest 时 SDK 进程的当前工作目录；相对本地源会从该目录解析，而绝对本地源必须已位于该目录内，或位于显式授权之下。这修复了一个本地制品边界问题，但可能会影响那些有意将受信任主机文件或目录从该基目录之外复制到沙箱工作区的应用程序。 +在此版本中，沙盒本地源物化会将 `LocalFile.src` 和 `LocalDir.src` 保持在物化 `base_dir` 内，除非源路径被 `Manifest.extra_path_grants` 覆盖。`base_dir` 是应用 manifest 时 SDK 进程的当前工作目录；相对本地源会从该目录解析，而绝对本地源必须已经位于该目录内，或位于显式授权之下。这修复了一个本地产物边界问题，但可能会影响那些有意将该基础目录之外的受信任主机文件或目录复制到沙盒工作区的应用。 -要迁移，请在 manifest 级别使用 `SandboxPathGrant` 授权受信任的主机根目录；如果沙箱只需要读取这些文件，最好设为只读： +要迁移，请使用 `SandboxPathGrant` 在 manifest 级别授予受信任的主机根路径；如果沙盒只需要读取这些文件，最好授予只读权限： ```python from pathlib import Path @@ -54,13 +54,13 @@ manifest = Manifest( ) ``` -请将 `extra_path_grants` 视为受信任的应用程序配置。除非你的应用程序已批准这些主机路径，否则不要从模型输出或其他不受信任的 manifest 输入中填充授权。 +请将 `extra_path_grants` 视为受信任的应用配置。除非你的应用已经批准了这些主机路径，否则不要从模型输出或其他不受信任的 manifest 输入中填充授权。 ### 0.16.0 -在此版本中，SDK 默认模型现在是 `gpt-5.4-mini`，而不是 `gpt-4.1`。这会影响未显式设置模型的智能体和运行。由于新的默认值是 GPT-5 模型，隐式默认模型设置现在包含 GPT-5 默认值，例如 `reasoning.effort="none"` 和 `verbosity="low"`。 +在此版本中，SDK 默认模型现在是 `gpt-5.4-mini`，而不是 `gpt-4.1`。这会影响未显式设置模型的智能体和运行。由于新的默认模型是 GPT-5 模型，隐式默认模型设置现在包含 GPT-5 默认值，例如 `reasoning.effort="none"` 和 `verbosity="low"`。 -如果需要保留之前的默认模型行为，请在智能体或运行配置中显式设置模型，或设置 `OPENAI_DEFAULT_MODEL` 环境变量： +如果你需要保持之前的默认模型行为，请在智能体或运行配置中显式设置模型，或设置 `OPENAI_DEFAULT_MODEL` 环境变量： ```python agent = Agent(name="Assistant", model="gpt-4.1") @@ -69,13 +69,13 @@ agent = Agent(name="Assistant", model="gpt-4.1") 亮点： - `Runner.run`、`Runner.run_sync` 和 `Runner.run_streamed` 现在接受 `max_turns=None` 以禁用轮次限制。 -- 沙箱工作区水合现在会拒绝包含指向归档根目录之外的符号链接的 tar 归档，包括绝对符号链接目标；这适用于本地、Docker 以及由提供方支持的沙箱实现。 +- 沙盒工作区水合现在会拒绝包含指向归档根目录之外的符号链接的 tar 归档，包括绝对符号链接目标；这适用于本地、Docker 以及由提供商支持的沙盒实现。 ### 0.15.0 -在此版本中，模型拒绝现在会显式以 `ModelRefusalError` 暴露，而不是被当作空文本输出处理，或在 structured outputs 场景下导致运行循环重试直到 `MaxTurnsExceeded`。 +在此版本中，模型拒绝现在会显式呈现为 `ModelRefusalError`，而不是被视为空文本输出；对于 structured outputs，也不再导致运行循环持续重试直到 `MaxTurnsExceeded`。 -这会影响此前预期仅包含拒绝的模型响应会以 `final_output == ""` 完成的代码。若要在不抛出异常的情况下处理拒绝，请提供 `model_refusal` 运行错误处理器： +这会影响此前预期仅包含拒绝的模型响应会以 `final_output == ""` 完成的代码。若要在不抛出异常的情况下处理拒绝，请提供 `model_refusal` 运行错误处理程序： ```python result = Runner.run_sync( @@ -85,85 +85,85 @@ result = Runner.run_sync( ) ``` -对于 structured outputs 智能体，该处理器可以返回与智能体输出 schema 匹配的值，SDK 会像验证其他运行错误处理器最终输出一样验证它。 +对于使用 structured outputs 的智能体，处理程序可以返回与智能体输出架构匹配的值，SDK 会像验证其他运行错误处理程序最终输出一样验证它。 ### 0.14.0 -此 minor 版本**没有**引入破坏性变更，但新增了一个重要的 beta 功能领域：Sandbox Agents，以及在本地、容器化和托管环境中使用它们所需的运行时、后端和文档支持。 +此次次版本发布**没有**引入破坏性变更，但新增了一个重要的 beta 功能领域：沙盒智能体，以及在本地、容器化和托管环境中使用它们所需的运行时、后端和文档支持。 亮点： -- 新增了以 `SandboxAgent`、`Manifest` 和 `SandboxRunConfig` 为核心的 beta 沙箱运行时接口，使智能体能够在持久隔离工作区中处理文件、目录、Git 仓库、挂载、快照以及恢复支持。 -- 通过 `UnixLocalSandboxClient` 和 `DockerSandboxClient` 新增了用于本地和容器化开发的沙箱执行后端，并通过可选 extras 提供了 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 和 Vercel 的托管提供方集成。 -- 新增沙箱记忆支持，使未来运行可以复用先前运行中的经验，并支持渐进式披露、多轮分组、可配置隔离边界，以及包括 S3 支持工作流在内的持久化记忆示例。 -- 新增了更广泛的工作区与恢复模型，包括本地和合成工作区条目、用于 S3/R2/GCS/Azure Blob Storage/S3 Files 的远程存储挂载、可移植快照，以及通过 `RunState`、`SandboxSessionState` 或已保存快照实现的恢复流程。 -- 在 `examples/sandbox/` 下新增了大量沙箱示例和教程，涵盖使用 skills、任务转移、记忆、提供方特定设置的编码任务，以及代码审查、dataroom QA 和网站克隆等端到端工作流。 -- 扩展了核心运行时和追踪栈，加入支持沙箱的会话准备、能力绑定、状态序列化、统一追踪、提示词缓存键默认值，以及更安全的敏感 MCP 输出遮蔽。 +- 新增了一个以 `SandboxAgent`、`Manifest` 和 `SandboxRunConfig` 为中心的 beta 沙盒运行时接口，使智能体能够在持久化隔离工作区内处理文件、目录、Git 仓库、挂载、快照和恢复支持。 +- 新增了用于本地和容器化开发的沙盒执行后端，可通过 `UnixLocalSandboxClient` 和 `DockerSandboxClient` 使用；还通过可选 extras 为 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 和 Vercel 提供托管提供商集成。 +- 新增了沙盒记忆支持，使未来运行可以复用先前运行的经验，并支持渐进式披露、多轮分组、可配置隔离边界，以及包含 S3 支持工作流的持久化记忆代码示例。 +- 新增了更广泛的工作区和恢复模型，包括本地与合成工作区条目、用于 S3/R2/GCS/Azure Blob Storage/S3 Files 的远程存储挂载、可移植快照，以及通过 `RunState`、`SandboxSessionState` 或已保存快照进行恢复的流程。 +- 在 `examples/sandbox/` 下新增了大量沙盒代码示例和教程，涵盖带技能的编码任务、任务转移、记忆、特定提供商设置，以及代码审查、数据室问答和网站克隆等端到端工作流。 +- 扩展了核心运行时和追踪栈，加入了沙盒感知的会话准备、能力绑定、状态序列化、统一追踪、提示词缓存键默认值，以及更安全的敏感 MCP 输出遮蔽。 ### 0.13.0 -此 minor 版本**没有**引入破坏性变更，但包含一次值得注意的 Realtime 默认值更新，以及新的 MCP 能力和运行时稳定性修复。 +此次次版本发布**没有**引入破坏性变更，但包含一次值得注意的 Realtime 默认值更新，以及新的 MCP 能力和运行时稳定性修复。 亮点： -- 默认 websocket Realtime 模型现在是 `gpt-realtime-1.5`，因此新的 Realtime 智能体设置无需额外配置即可使用更新的模型。 -- `MCPServer` 现在公开 `list_resources()`、`list_resource_templates()` 和 `read_resource()`，并且 `MCPServerStreamableHttp` 现在公开 `session_id`，使可流式 HTTP 会话可以在重连或无状态 worker 之间恢复。 -- Chat Completions 集成现在可以通过 `should_replay_reasoning_content` 选择启用 reasoning-content replay，从而改善 LiteLLM/DeepSeek 等适配器的提供方特定推理/工具调用连续性。 -- 修复了多个运行时和会话边界情况，包括 `SQLAlchemySession` 中并发首次写入、推理剥离后带有孤立 assistant 消息 ID 的压缩请求、`remove_all_tools()` 遗留 MCP/推理项，以及工具调用批处理执行器中的竞态问题。 +- 默认 websocket Realtime 模型现在是 `gpt-realtime-1.5`，因此新的 Realtime 智能体设置无需额外配置即可使用较新的模型。 +- `MCPServer` 现在公开 `list_resources()`、`list_resource_templates()` 和 `read_resource()`，并且 `MCPServerStreamableHttp` 现在公开 `session_id`，因此可流式传输的 HTTP 会话可以在重新连接或无状态 worker 之间恢复。 +- Chat Completions 集成现在可以通过 `should_replay_reasoning_content` 选择启用推理内容重放，从而改善 LiteLLM/DeepSeek 等适配器中特定提供商的推理/工具调用连续性。 +- 修复了若干运行时和会话边缘情况，包括 `SQLAlchemySession` 中的并发首次写入、推理剥离后包含孤立 assistant 消息 ID 的压缩请求、`remove_all_tools()` 遗留 MCP/推理项，以及工具调用批量执行器中的竞态条件。 ### 0.12.0 -此 minor 版本**没有**引入破坏性变更。主要功能新增请查看[发布说明](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)。 +此次次版本发布**没有**引入破坏性变更。请查看[发布说明](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)以了解主要功能新增内容。 ### 0.11.0 -此 minor 版本**没有**引入破坏性变更。主要功能新增请查看[发布说明](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)。 +此次次版本发布**没有**引入破坏性变更。请查看[发布说明](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)以了解主要功能新增内容。 ### 0.10.0 -此 minor 版本**没有**引入破坏性变更，但为 OpenAI Responses 用户包含了一个重要的新功能领域：Responses API 的 websocket 传输支持。 +此次次版本发布**没有**引入破坏性变更，但它为 OpenAI Responses 用户包含了一个重要的新功能领域：Responses API 的 websocket 传输支持。 亮点： -- 为 OpenAI Responses 模型新增了 websocket 传输支持（选择启用；HTTP 仍为默认传输）。 -- 新增了 `responses_websocket_session()` 辅助函数 / `ResponsesWebSocketSession`，用于在多轮运行之间复用共享的支持 websocket 的提供方和 `RunConfig`。 -- 新增了一个 websocket 流式传输示例（`examples/basic/stream_ws.py`），涵盖流式传输、工具、审批和后续轮次。 +- 为 OpenAI Responses 模型新增了 websocket 传输支持（需选择启用；HTTP 仍是默认传输）。 +- 新增了 `responses_websocket_session()` 辅助函数 / `ResponsesWebSocketSession`，用于在多轮运行中复用支持共享 websocket 的提供商和 `RunConfig`。 +- 新增了一个 websocket 流式传输代码示例（`examples/basic/stream_ws.py`），涵盖流式传输、工具、审批和后续轮次。 ### 0.9.0 -在此版本中，Python 3.9 不再受支持，因为该主要版本已在三个月前达到 EOL。请升级到更新的运行时版本。 +在此版本中，不再支持 Python 3.9，因为该主版本已在三个月前达到 EOL。请升级到更新的运行时版本。 -此外，`Agent#as_tool()` 方法返回值的类型提示已从 `Tool` 缩窄为 `FunctionTool`。此变更通常不会造成破坏性问题，但如果你的代码依赖更宽泛的联合类型，可能需要在你的代码侧进行一些调整。 +此外，`Agent#as_tool()` 方法返回值的类型提示已从 `Tool` 收窄为 `FunctionTool`。此更改通常不应导致破坏性问题，但如果你的代码依赖更宽泛的联合类型，可能需要在你的代码侧做一些调整。 ### 0.8.0 -在此版本中，两项运行时行为变更可能需要迁移工作： +在此版本中，有两项运行时行为变更可能需要迁移工作： -- 包装**同步** Python 可调用对象的工具调用现在会通过 `asyncio.to_thread(...)` 在线程池线程上执行，而不是在事件循环线程上运行。如果你的工具逻辑依赖线程局部状态或线程亲和资源，请迁移到异步工具实现，或在工具代码中显式处理线程亲和性。 -- 本地 MCP 工具失败处理现在可配置，默认行为可能返回对模型可见的错误输出，而不是使整个运行失败。如果你依赖快速失败语义，请设置 `mcp_config={"failure_error_function": None}`。服务级别的 `failure_error_function` 值会覆盖智能体级别设置，因此请在每个具有显式处理器的本地 MCP 服务上设置 `failure_error_function=None`。 +- 封装**同步** Python 可调用对象的工具调用现在会通过 `asyncio.to_thread(...)` 在 worker 线程上执行，而不是在事件循环线程上运行。如果你的工具逻辑依赖线程局部状态或线程亲和资源，请迁移到异步工具实现，或在工具代码中显式处理线程亲和性。 +- 本地 MCP 工具失败处理现在可配置，默认行为可以返回模型可见的错误输出，而不是使整个运行失败。如果你依赖快速失败语义，请设置 `mcp_config={"failure_error_function": None}`。服务级 `failure_error_function` 值会覆盖智能体级设置，因此请在每个具有显式处理程序的本地 MCP 服务上设置 `failure_error_function=None`。 ### 0.7.0 -在此版本中，有一些行为变更可能影响现有应用程序： +在此版本中，有一些行为变更可能会影响现有应用： - 嵌套任务转移历史现在是**选择启用**（默认禁用）。如果你依赖 v0.6.x 默认的嵌套行为，请显式设置 `RunConfig(nest_handoff_history=True)`。 -- `gpt-5.1` / `gpt-5.2` 的默认 `reasoning.effort` 已更改为 `"none"`（此前由 SDK 默认值配置的默认值为 `"low"`）。如果你的提示词或质量/成本配置依赖 `"low"`，请在 `model_settings` 中显式设置它。 +- `gpt-5.1` / `gpt-5.2` 的默认 `reasoning.effort` 已更改为 `"none"`（此前由 SDK 默认值配置的默认值是 `"low"`）。如果你的提示词或质量/成本配置依赖 `"low"`，请在 `model_settings` 中显式设置它。 ### 0.6.0 -在此版本中，默认任务转移历史现在会打包成一条 assistant 消息，而不是暴露原始的用户/assistant 轮次，从而为下游智能体提供简洁、可预测的回顾 -- 现有的单消息任务转移转录现在默认会在 `` 块之前以“For context, here is the conversation so far between the user and the previous agent:”开头，使下游智能体获得清晰标注的回顾 +在此版本中，默认任务转移历史现在会打包成单条 assistant 消息，而不是暴露原始用户/助手轮次，从而为下游智能体提供简洁、可预测的摘要 +- 现有的单消息任务转移转录现在默认会在 `` 块之前以 "For context, here is the conversation so far between the user and the previous agent:" 开头，因此下游智能体会获得带有清晰标签的摘要 ### 0.5.0 此版本没有引入任何可见的破坏性变更，但包含一些新功能和若干重要的底层更新： -- 新增支持 `RealtimeRunner` 处理 [SIP 协议连接](https://platform.openai.com/docs/guides/realtime-sip) +- 新增了对 `RealtimeRunner` 处理 [SIP 协议连接](https://platform.openai.com/docs/guides/realtime-sip)的支持 - 为兼容 Python 3.14，大幅修订了 `Runner#run_sync` 的内部逻辑 ### 0.4.0 -在此版本中，不再支持 [openai](https://pypi.org/project/openai/) 包 v1.x 版本。请将 openai v2.x 与此 SDK 配合使用。 +在此版本中，不再支持 [openai](https://pypi.org/project/openai/) 包 v1.x 版本。请将 openai v2.x 与此 SDK 一起使用。 ### 0.3.0 @@ -171,8 +171,8 @@ result = Runner.run_sync( ### 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] 有两个新 params：`run_context` 和 `agent`。你需要将这些 params 添加到任何继承 `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 afb254db30..6d91afbdf5 100644 --- a/docs/zh/repl.md +++ b/docs/zh/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`（然后按回车），或使用键盘快捷键 `Ctrl-D`。 \ No newline at end of file +要结束此聊天会话，只需输入 `quit` 或 `exit`（然后按 Enter），或使用 `Ctrl-D` 键盘快捷键。 \ No newline at end of file diff --git a/docs/zh/results.md b/docs/zh/results.md index ea1d1af298..b4fbe23dd4 100644 --- a/docs/zh/results.md +++ b/docs/zh/results.md @@ -4,95 +4,95 @@ search: --- # 结果 -当你调用 `Runner.run` 方法时，会收到以下两种结果类型之一： +调用 `Runner.run` 方法时，你会收到以下两种结果类型之一： - 来自 `Runner.run(...)` 或 `Runner.run_sync(...)` 的 [`RunResult`][agents.result.RunResult] - 来自 `Runner.run_streamed(...)` 的 [`RunResultStreaming`][agents.result.RunResultStreaming] -二者都继承自 [`RunResultBase`][agents.result.RunResultBase]，后者暴露共享的结果表面，例如 `final_output`、`new_items`、`last_agent`、`raw_responses` 和 `to_state()`。 +二者都继承自 [`RunResultBase`][agents.result.RunResultBase]，后者公开了共享的结果接口，例如 `final_output`、`new_items`、`last_agent`、`raw_responses` 和 `to_state()`。 -`RunResultStreaming` 添加了特定于流式传输的控制项，例如 [`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete] 和 [`cancel(...)`][agents.result.RunResultStreaming.cancel]。 +`RunResultStreaming` 增加了流式传输专用控制项，例如 [`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete] 和 [`cancel(...)`][agents.result.RunResultStreaming.cancel]。 -## 正确结果表面的选择 +## 合适的结果接口 -大多数应用只需要少数结果属性或辅助方法： +大多数应用只需要少数几个结果属性或辅助方法： | 如果你需要... | 使用 | | --- | --- | | 展示给用户的最终答案 | `final_output` | -| 带有完整本地转录、可用于重放的下一轮输入列表 | `to_input_list()` | -| 包含智能体、工具、任务转移和审批元数据的丰富运行项 | `new_items` | +| 可用于重放的下一轮输入列表，包含完整本地转录记录 | `to_input_list()` | +| 包含智能体、工具、任务转移和审批元数据的丰富运行条目 | `new_items` | | 通常应处理下一轮用户输入的智能体 | `last_agent` | -| 使用 `previous_response_id` 的 OpenAI Responses API 链接 | `last_response_id` | -| 待审批项和可恢复快照 | `interruptions` 和 `to_state()` | -| 关于当前嵌套 `Agent.as_tool()` 调用的元数据 | `agent_tool_invocation` | -| 原始模型调用或安全防护措施诊断信息 | `raw_responses` 和安全防护措施结果数组 | +| 使用 `previous_response_id` 进行 OpenAI Responses API 链接 | `last_response_id` | +| 待处理审批和可恢复快照 | `interruptions` 和 `to_state()` | +| 当前嵌套 `Agent.as_tool()` 调用的元数据 | `agent_tool_invocation` | +| 原始模型调用或安全防护措施诊断 | `raw_responses` 和安全防护措施结果数组 | ## 最终输出 [`final_output`][agents.result.RunResultBase.final_output] 属性包含最后运行的智能体的最终输出。它可能是： -- `str`，如果最后的智能体没有定义 `output_type` -- `last_agent.output_type` 类型的对象，如果最后的智能体定义了输出类型 -- `None`，如果运行在生成最终输出之前停止，例如因为在审批中断处暂停 +- 一个 `str`，如果最后一个智能体未定义 `output_type` +- `last_agent.output_type` 类型的对象，如果最后一个智能体定义了输出类型 +- `None`，如果运行在产生最终输出之前停止，例如因审批中断而暂停 !!! note - `final_output` 的类型为 `Any`。任务转移可能会改变哪个智能体结束运行，因此 SDK 无法静态获知所有可能的输出类型。 + `final_output` 的类型为 `Any`。任务转移可能会改变哪个智能体结束运行，因此 SDK 无法静态得知所有可能的输出类型。 在流式传输模式下，`final_output` 会保持为 `None`，直到流处理完成。有关逐事件流程，请参阅[流式传输](streaming.md)。 -## 输入、下一轮历史和新项 +## 输入、下一轮历史记录和新条目 -这些表面回答不同的问题： +这些接口回答的是不同问题： -| 属性或辅助方法 | 包含内容 | 最适合 | +| 属性或辅助方法 | 包含的内容 | 最适合 | | --- | --- | --- | -| [`input`][agents.result.RunResultBase.input] | 此运行片段的基础输入。如果任务转移输入过滤器重写了历史，则这里反映运行继续使用的已过滤输入。 | 审计此运行实际使用的输入 | -| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 运行的输入项视图。默认的 `mode="preserve_all"` 会保留从 `new_items` 转换而来的完整历史；`mode="normalized"` 会在任务转移过滤重写模型历史时优先使用规范的延续输入。 | 手动聊天循环、客户端管理的对话状态，以及普通项历史检查 | -| [`new_items`][agents.result.RunResultBase.new_items] | 带有智能体、工具、任务转移和审批元数据的丰富 [`RunItem`][agents.items.RunItem] 包装器。 | 日志、UI、审计和调试 | +| [`input`][agents.result.RunResultBase.input] | 此运行片段的基础输入。如果任务转移输入过滤器重写了历史记录，这里会反映运行继续时所使用的过滤后输入。 | 审计此运行实际使用了什么作为输入 | +| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 运行的输入条目视图。默认 `mode="preserve_all"` 会保留来自 `new_items` 的完整转换后历史记录；`mode="normalized"` 会在任务转移过滤重写模型历史记录时优先使用规范续接输入。 | 手动聊天循环、客户端管理的对话状态，以及普通条目历史记录检查 | +| [`new_items`][agents.result.RunResultBase.new_items] | 包含智能体、工具、任务转移和审批元数据的丰富 [`RunItem`][agents.items.RunItem] 包装器。 | 日志、UI、审计和调试 | | [`raw_responses`][agents.result.RunResultBase.raw_responses] | 运行中每次模型调用产生的原始 [`ModelResponse`][agents.items.ModelResponse] 对象。 | 提供方级诊断或原始响应检查 | -实际使用中： +实践中： -- 当你想要运行的普通输入项视图时，使用 `to_input_list()`。 -- 当你想要在任务转移过滤或嵌套任务转移历史重写之后，用于下一次 `Runner.run(..., input=...)` 调用的规范本地输入时，使用 `to_input_list(mode="normalized")`。 -- 当你希望 SDK 为你加载和保存历史时，使用 [`session=...`](sessions/index.md)。 -- 如果你使用 OpenAI 服务端管理状态以及 `conversation_id` 或 `previous_response_id`，通常只传递新的用户输入并复用已存储的 ID，而不是重新发送 `to_input_list()`。 -- 当你需要用于日志、UI 或审计的完整转换历史时，使用默认的 `to_input_list()` 模式或 `new_items`。 +- 当你想要运行的普通输入条目视图时，使用 `to_input_list()`。 +- 当你希望在任务转移过滤或嵌套任务转移历史记录重写后，为下一次 `Runner.run(..., input=...)` 调用获得规范本地输入时，使用 `to_input_list(mode="normalized")`。 +- 当你希望 SDK 为你加载和保存历史记录时，使用 [`session=...`](sessions/index.md)。 +- 如果你使用带有 `conversation_id` 或 `previous_response_id` 的 OpenAI服务管理状态，通常只传递新的用户输入，并复用已存储的 ID，而不是重新发送 `to_input_list()`。 +- 当你需要用于日志、UI 或审计的完整转换后历史记录时，使用默认的 `to_input_list()` 模式或 `new_items`。 -与 JavaScript SDK 不同，Python 不会为仅按模型形状表示的增量暴露单独的 `output` 属性。当你需要 SDK 元数据时使用 `new_items`，当你需要原始模型载荷时检查 `raw_responses`。 +与 JavaScript SDK 不同，Python 不会公开一个单独的 `output` 属性来仅表示模型形态的增量。当你需要 SDK 元数据时，使用 `new_items`；当你需要原始模型载荷时，检查 `raw_responses`。 -计算机工具重放遵循原始 Responses 载荷形状。预览模型的 `computer_call` 项会保留单个 `action`，而 `gpt-5.5` 计算机调用可以保留批量的 `actions[]`。[`to_input_list()`][agents.result.RunResultBase.to_input_list] 和 [`RunState`][agents.run_state.RunState] 会保留模型生成的任一形状，因此手动重放、暂停/恢复流程和已存储的转录可在预览版和 GA 计算机工具调用中继续工作。本地执行结果仍会在 `new_items` 中显示为 `computer_call_output` 项。 +计算机工具重放遵循原始 Responses 载荷结构。预览模型的 `computer_call` 条目会保留单个 `action`，而 `gpt-5.5` 计算机调用可以保留批处理的 `actions[]`。[`to_input_list()`][agents.result.RunResultBase.to_input_list] 和 [`RunState`][agents.run_state.RunState] 会保留模型生成的任一结构，因此手动重放、暂停/恢复流程和已存储的转录记录都能继续适用于预览版和 GA 计算机工具调用。本地执行结果仍会以 `computer_call_output` 条目的形式出现在 `new_items` 中。 -### 新项 +### 新条目 -[`new_items`][agents.result.RunResultBase.new_items] 为你提供运行期间所发生事情的最丰富视图。常见项类型包括： +[`new_items`][agents.result.RunResultBase.new_items] 为你提供运行期间所发生事件的最丰富视图。常见条目类型包括： - 用于助手消息的 [`MessageOutputItem`][agents.items.MessageOutputItem] -- 用于推理项的 [`ReasoningItem`][agents.items.ReasoningItem] -- 用于 Responses 工具检索请求和已加载工具检索结果的 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 和 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem] -- 用于工具调用及其结果的 [`ToolCallItem`][agents.items.ToolCallItem] 和 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] +- 用于推理条目的 [`ReasoningItem`][agents.items.ReasoningItem] +- 用于 Responses 工具搜索请求和已加载工具搜索结果的 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 与 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem] +- 用于工具调用及其结果的 [`ToolCallItem`][agents.items.ToolCallItem] 与 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem] - 用于因审批而暂停的工具调用的 [`ToolApprovalItem`][agents.items.ToolApprovalItem] -- 用于任务转移请求和已完成转移的 [`HandoffCallItem`][agents.items.HandoffCallItem] 和 [`HandoffOutputItem`][agents.items.HandoffOutputItem] +- 用于任务转移请求和已完成转移的 [`HandoffCallItem`][agents.items.HandoffCallItem] 与 [`HandoffOutputItem`][agents.items.HandoffOutputItem] -每当你需要智能体关联、工具输出、任务转移边界或审批边界时，请选择 `new_items`，而不是 `to_input_list()`。 +每当你需要智能体关联、工具输出、任务转移边界或审批边界时，应选择 `new_items` 而不是 `to_input_list()`。 -当你使用托管工具检索时，检查 `ToolSearchCallItem.raw_item` 可查看模型发出的检索请求，检查 `ToolSearchOutputItem.raw_item` 可查看本轮加载了哪些命名空间、函数或托管 MCP 服务。 +使用托管工具搜索时，检查 `ToolSearchCallItem.raw_item` 可查看模型发出的搜索请求，检查 `ToolSearchOutputItem.raw_item` 可查看该轮次加载了哪些命名空间、函数或托管 MCP 服务。 ## 对话的继续或恢复 ### 下一轮智能体 -[`last_agent`][agents.result.RunResultBase.last_agent] 包含最后运行的智能体。在任务转移之后，这通常是下一轮用户输入中最适合复用的智能体。 +[`last_agent`][agents.result.RunResultBase.last_agent] 包含最后运行的智能体。在任务转移之后，这通常是下一轮用户输入最适合复用的智能体。 -在流式传输模式下，[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] 会随着运行推进而更新，因此你可以在流结束之前观察任务转移。 +在流式传输模式下，[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] 会随着运行进展而更新，因此你可以在流结束前观察任务转移。 ### 中断和运行状态 -如果工具需要审批，待审批项会通过 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 或 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 暴露出来。这可能包括由直接工具、任务转移后到达的工具，或嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行提出的审批。 +如果工具需要审批，待处理审批会通过 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 或 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 暴露。这可以包括由直接工具引发、由任务转移后到达的工具引发，或由嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行引发的审批。 -调用 [`to_state()`][agents.result.RunResult.to_state] 以捕获可恢复的 [`RunState`][agents.run_state.RunState]，批准或拒绝待处理项，然后使用 `Runner.run(...)` 或 `Runner.run_streamed(...)` 恢复。 +调用 [`to_state()`][agents.result.RunResult.to_state] 可捕获可恢复的 [`RunState`][agents.run_state.RunState]，批准或拒绝待处理条目，然后使用 `Runner.run(...)` 或 `Runner.run_streamed(...)` 恢复。 ```python from agents import Agent, Runner @@ -107,48 +107,48 @@ if result.interruptions: result = await Runner.run(agent, state) ``` -对于流式传输运行，请先消费完 [`stream_events()`][agents.result.RunResultStreaming.stream_events]，然后检查 `result.interruptions` 并从 `result.to_state()` 恢复。完整审批流程请参阅[人在环路](human_in_the_loop.md)。 +对于流式传输运行，请先完成对 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 的消费，然后检查 `result.interruptions` 并从 `result.to_state()` 恢复。有关完整审批流程，请参阅[人在回路](human_in_the_loop.md)。 -### 服务端管理的延续 +### 服务管理的续接 -[`last_response_id`][agents.result.RunResultBase.last_response_id] 是运行中的最新模型响应 ID。当你想继续 OpenAI Responses API 链时，在下一轮将它作为 `previous_response_id` 传回。 +[`last_response_id`][agents.result.RunResultBase.last_response_id] 是运行中最新的模型响应 ID。当你想继续 OpenAI Responses API 链时，在下一轮将它作为 `previous_response_id` 传回。 -如果你已经通过 `to_input_list()`、`session` 或 `conversation_id` 继续对话，通常不需要 `last_response_id`。如果你需要多步骤运行中的每个模型响应，请改为检查 `raw_responses`。 +如果你已经使用 `to_input_list()`、`session` 或 `conversation_id` 继续对话，通常不需要 `last_response_id`。如果需要多步运行中的每个模型响应，请改为检查 `raw_responses`。 -## Agent-as-tool 元数据 +## 智能体作为工具的元数据 -当结果来自嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行时，[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] 会暴露关于外层工具调用的不可变元数据： +当结果来自嵌套的 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行时，[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] 会公开关于外层工具调用的不可变元数据： - `tool_name` - `tool_call_id` - `tool_arguments` -对于普通的顶层运行，`agent_tool_invocation` 为 `None`。 +对于普通顶层运行，`agent_tool_invocation` 为 `None`。 -这在 `custom_output_extractor` 内尤其有用，你可能需要在对嵌套结果进行后处理时使用外层工具名称、调用 ID 或原始参数。有关周边的 `Agent.as_tool()` 模式，请参阅[工具](tools.md)。 +这在 `custom_output_extractor` 内尤其有用，因为在对嵌套结果进行后处理时，你可能需要外层工具名称、调用 ID 或原始参数。有关周围的 `Agent.as_tool()` 模式，请参阅[工具](tools.md)。 -如果你还需要该嵌套运行的已解析结构化输入，请读取 `context_wrapper.tool_input`。这是 [`RunState`][agents.run_state.RunState] 用于通用序列化嵌套工具输入的字段，而 `agent_tool_invocation` 是当前嵌套调用的实时结果访问器。 +如果你还需要该嵌套运行的已解析结构化输入，请读取 `context_wrapper.tool_input`。这是 [`RunState`][agents.run_state.RunState] 用于以通用方式序列化嵌套工具输入的字段，而 `agent_tool_invocation` 是当前嵌套调用的实时结果访问器。 ## 流式传输生命周期和诊断 -[`RunResultStreaming`][agents.result.RunResultStreaming] 继承上文相同的结果表面，但添加了特定于流式传输的控制项： +[`RunResultStreaming`][agents.result.RunResultStreaming] 继承上述相同结果接口，但增加了流式传输专用控制项： - [`stream_events()`][agents.result.RunResultStreaming.stream_events] 用于消费语义流事件 -- [`current_agent`][agents.result.RunResultStreaming.current_agent] 用于在运行中途跟踪活动智能体 -- [`is_complete`][agents.result.RunResultStreaming.is_complete] 用于查看流式运行是否已完全结束 -- [`cancel(...)`][agents.result.RunResultStreaming.cancel] 用于立即停止运行，或在当前轮次后停止运行 +- [`current_agent`][agents.result.RunResultStreaming.current_agent] 用于在运行过程中跟踪活跃智能体 +- [`is_complete`][agents.result.RunResultStreaming.is_complete] 用于查看流式传输运行是否已完全结束 +- [`cancel(...)`][agents.result.RunResultStreaming.cancel] 用于立即停止运行，或在当前轮次结束后停止运行 -持续消费 `stream_events()`，直到异步迭代器结束。流式传输运行只有在该迭代器结束后才算完成，并且在最后一个可见 token 到达后，`final_output`、`interruptions`、`raw_responses` 等摘要属性以及会话持久化副作用可能仍在收尾。 +持续消费 `stream_events()`，直到异步迭代器结束。只有该迭代器结束后，流式传输运行才算完成；并且在最后一个可见 token 到达后，`final_output`、`interruptions`、`raw_responses` 等汇总属性以及会话持久化副作用可能仍在收尾。 -如果你调用 `cancel()`，请继续消费 `stream_events()`，以便取消和清理能够正确完成。 +如果调用 `cancel()`，请继续消费 `stream_events()`，以便取消和清理能够正确完成。 -Python 不会暴露单独的流式 `completed` promise 或 `error` 属性。终止性流式传输失败会通过 `stream_events()` 抛出异常来呈现，而 `is_complete` 反映运行是否已达到其终止状态。 +Python 不会公开单独的流式 `completed` promise 或 `error` 属性。终止性流式传输失败会通过 `stream_events()` 抛出异常来呈现，而 `is_complete` 反映运行是否已到达其终止状态。 ### 原始响应 -[`raw_responses`][agents.result.RunResultBase.raw_responses] 包含运行期间收集的原始模型响应。多步骤运行可能会产生多个响应，例如跨任务转移或重复的模型/工具/模型循环。 +[`raw_responses`][agents.result.RunResultBase.raw_responses] 包含运行期间收集的原始模型响应。多步运行可能会生成多个响应，例如跨任务转移或重复的模型/工具/模型循环。 -[`last_response_id`][agents.result.RunResultBase.last_response_id] 只是 `raw_responses` 中最后一个条目的 ID。 +[`last_response_id`][agents.result.RunResultBase.last_response_id] 只是 `raw_responses` 最后一项中的 ID。 ### 安全防护措施结果 @@ -156,10 +156,10 @@ Python 不会暴露单独的流式 `completed` promise 或 `error` 属性。终 工具安全防护措施则分别通过 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 和 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] 暴露。 -这些数组会在整个运行过程中累积，因此它们对记录决策、存储额外的安全防护措施元数据，或调试运行为何被阻止很有用。 +这些数组会在运行过程中累积，因此它们适用于记录决策、存储额外的安全防护措施元数据，或调试运行为何被阻止。 ### 上下文和用量 -[`context_wrapper`][agents.result.RunResultBase.context_wrapper] 会将你的应用上下文与 SDK 管理的运行时元数据一起暴露，例如审批、用量和嵌套 `tool_input`。 +[`context_wrapper`][agents.result.RunResultBase.context_wrapper] 会公开你的应用上下文，以及由 SDK 管理的运行时元数据，例如审批、用量和嵌套 `tool_input`。 -用量会在 `context_wrapper.usage` 上跟踪。对于流式传输运行，在流的最终分块处理完成之前，用量总计可能会滞后。有关完整包装器形状和持久化注意事项，请参阅[上下文管理](context.md)。 \ No newline at end of file +用量在 `context_wrapper.usage` 上跟踪。对于流式传输运行，用量总计可能会滞后，直到流的最终分块处理完毕。有关完整的包装器结构和持久化注意事项，请参阅[上下文管理](context.md)。 \ No newline at end of file diff --git a/docs/zh/running_agents.md b/docs/zh/running_agents.md index 7acf4a2161..a1dfa2ce9c 100644 --- a/docs/zh/running_agents.md +++ b/docs/zh/running_agents.md @@ -2,7 +2,7 @@ search: exclude: true --- -# 运行智能体 +# 智能体运行 你可以通过 [`Runner`][agents.run.Runner] 类运行智能体。你有 3 个选项： @@ -25,24 +25,24 @@ async def main(): 在[结果指南](results.md)中阅读更多内容。 -## Runner 生命周期和配置 +## Runner 生命周期与配置 ### 智能体循环 -当你使用 `Runner` 中的 run 方法时，需要传入一个起始智能体和输入。输入可以是： +当你使用 `Runner` 中的 run 方法时，会传入一个起始智能体和输入。输入可以是： -- 一个字符串（被视为用户消息）， -- OpenAI Responses API 格式的输入项列表，或 -- 在恢复被中断的运行时使用的 [`RunState`][agents.run_state.RunState]。 +- 一个字符串（视为用户消息）， +- OpenAI Responses API 格式的输入项列表，或 +- 在恢复被中断的运行时使用的 [`RunState`][agents.run_state.RunState]。 -然后 runner 会运行一个循环： +随后 runner 会运行一个循环： -1. 我们用当前输入为当前智能体调用 LLM。 +1. 我们使用当前输入调用当前智能体的 LLM。 2. LLM 生成其输出。 - 1. 如果 LLM 返回 `final_output`，循环结束，并返回结果。 + 1. 如果 LLM 返回 `final_output`，循环结束并返回结果。 2. 如果 LLM 执行任务转移，我们会更新当前智能体和输入，并重新运行循环。 - 3. 如果 LLM 生成工具调用，我们会运行这些工具调用、追加结果，并重新运行循环。 -3. 如果超过传入的 `max_turns`，我们会抛出 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。传入 `max_turns=None` 可禁用此轮数限制。 + 3. 如果 LLM 生成工具调用，我们会运行这些工具调用，追加结果，并重新运行循环。 +3. 如果超过传入的 `max_turns`，我们会抛出 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 异常。传入 `max_turns=None` 可禁用此轮次限制。 !!! note @@ -50,7 +50,7 @@ async def main(): ### 流式传输 -流式传输允许你在 LLM 运行时额外接收流式传输事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含此次运行的完整信息，包括生成的所有新输出。你可以调用 `.stream_events()` 获取流式传输事件。在[流式传输指南](streaming.md)中阅读更多内容。 +流式传输允许你在 LLM 运行时额外接收流式传输事件。流结束后，[`RunResultStreaming`][agents.result.RunResultStreaming] 将包含关于本次运行的完整信息，包括所有新生成的输出。你可以调用 `.stream_events()` 获取流式传输事件。在[流式传输指南](streaming.md)中阅读更多内容。 #### Responses WebSocket 传输（可选辅助工具） @@ -58,11 +58,11 @@ async def main(): 这是通过 websocket 传输的 Responses API，不是 [Realtime API](realtime/guide.md)。 -有关传输选择规则以及具体模型对象或自定义提供方相关的注意事项，请参阅[模型](models/index.md#responses-websocket-transport)。 +有关传输选择规则，以及围绕具体模型对象或自定义提供方的注意事项，请参阅[模型](models/index.md#responses-websocket-transport)。 -##### 模式 1：不使用会话辅助工具（可用） +##### 模式 1：无会话辅助工具（可用） -当你只想使用 websocket 传输，并且不需要 SDK 为你管理共享的提供方/会话时，请使用此模式。 +当你只想使用 websocket 传输，并且不需要 SDK 为你管理共享提供方/会话时，请使用此模式。 ```python import asyncio @@ -85,11 +85,11 @@ async def main(): asyncio.run(main()) ``` -此模式适合单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非你手动复用同一个 `RunConfig` / 提供方实例，否则每次运行都可能重新连接。 +此模式适合单次运行。如果你反复调用 `Runner.run()` / `Runner.run_streamed()`，除非手动复用同一个 `RunConfig` / 提供方实例，否则每次运行都可能重新连接。 ##### 模式 2：使用 `responses_websocket_session()`（建议用于多轮复用） -当你希望在多次运行之间（包括继承同一 `run_config` 的嵌套 agent-as-tool 调用）共享支持 websocket 的提供方和 `RunConfig` 时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 +当你希望在多次运行之间共享支持 websocket 的提供方和 `RunConfig`（包括继承同一 `run_config` 的嵌套 agent-as-tool 调用）时，请使用 [`responses_websocket_session()`][agents.responses_websocket_session]。 ```python import asyncio @@ -119,9 +119,9 @@ async def main(): asyncio.run(main()) ``` -在上下文退出前完成对流式传输结果的消费。如果 websocket 请求仍在进行中时退出上下文，可能会强制关闭共享连接。 +请在上下文退出前完成对流式传输结果的消费。如果在 websocket 请求仍在进行时退出上下文，可能会强制关闭共享连接。 -如果长推理轮次触发 websocket keepalive 超时，请增大 `ping_timeout`，或设置 `ping_timeout=None` 以禁用心跳超时。对于可靠性比 websocket 延迟更重要的运行，请使用 HTTP/SSE 传输。 +如果较长的推理轮次遇到 websocket keepalive 超时，请增大 `ping_timeout`，或设置 `ping_timeout=None` 以禁用心跳超时。对于可靠性比 websocket 延迟更重要的运行，请使用 HTTP/SSE 传输。 ### 运行配置 @@ -129,45 +129,45 @@ asyncio.run(main()) #### 常见运行配置目录 -使用 `RunConfig` 可在不更改每个智能体定义的情况下，覆盖单次运行的行为。 +使用 `RunConfig` 可以在不更改每个智能体定义的情况下，覆盖单次运行的行为。 -##### 模型、提供方和会话默认值 +##### 模型、提供方与会话默认值 -- [`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`。 -- [`session_settings`][agents.run.RunConfig.session_settings]：在运行期间检索历史记录时，覆盖会话级默认值（例如 `SessionSettings(limit=...)`）。 -- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：使用 Sessions 时，自定义每轮之前如何将新的用户输入与会话历史合并。回调可以是同步或异步的。 +- [`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`。 +- [`session_settings`][agents.run.RunConfig.session_settings]：在运行期间检索历史时，覆盖会话级默认值（例如 `SessionSettings(limit=...)`）。 +- [`session_input_callback`][agents.run.RunConfig.session_input_callback]：使用 Sessions 时，自定义每轮之前如何将新的用户输入与会话历史合并。该回调可以是同步或异步的。 -##### 安全防护措施、任务转移和模型输入塑形 +##### 安全防护措施、任务转移与模型输入塑形 -- [`input_guardrails`][agents.run.RunConfig.input_guardrails]、[`output_guardrails`][agents.run.RunConfig.output_guardrails]：要包含在所有运行中的输入或输出安全防护措施列表。 -- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：应用于所有任务转移的全局输入过滤器，前提是该任务转移尚未有自己的过滤器。输入过滤器允许你编辑发送给新智能体的输入。更多详情请参阅 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 中的文档。 -- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：一个选择启用的 beta 功能，会在调用下一个智能体之前，将先前的记录折叠为一条 assistant 消息。在我们稳定嵌套任务转移期间，该功能默认禁用；设置为 `True` 可启用，或保持 `False` 以传递原始记录。当你未传入 `RunConfig` 时，所有 [Runner 方法][agents.run.Runner] 都会自动创建一个 `RunConfig`，因此 quickstarts 和代码示例会保持默认关闭，而任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调仍会继续覆盖它。单个任务转移可以通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 -- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：可选 callable；当你选择启用 `nest_handoff_history` 时，它会接收规范化后的记录（历史 + 任务转移项）。它必须返回要转发给下一个智能体的确切输入项列表，从而允许你在不编写完整任务转移过滤器的情况下替换内置摘要。 -- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：在模型调用前立即编辑已完全准备好的模型输入（instructions 和输入项）的钩子，例如用于裁剪历史或注入系统提示词。 -- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]：控制 runner 将先前输出转换为下一轮模型输入时，是保留还是省略 reasoning item ID。 +- [`input_guardrails`][agents.run.RunConfig.input_guardrails]、[`output_guardrails`][agents.run.RunConfig.output_guardrails]：要包含在所有运行中的输入或输出安全防护措施列表。 +- [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]：如果任务转移尚未设置输入过滤器，则应用于所有任务转移的全局输入过滤器。输入过滤器允许你编辑将发送给新智能体的输入。更多详情请参阅 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 中的文档。 +- [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]：一个选择加入的 beta 功能，会在调用下一个智能体之前，将此前记录折叠为单个 assistant 消息。在我们稳定嵌套任务转移期间，此功能默认禁用；设置为 `True` 可启用，或保留为 `False` 以传递原始记录。当你未传入 `RunConfig` 时，所有 [Runner 方法][agents.run.Runner]都会自动创建一个，因此快速入门和代码示例会保持默认关闭，并且任何显式的 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 回调都会继续覆盖它。单个任务转移可以通过 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] 覆盖此设置。 +- [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]：当你选择加入 `nest_handoff_history` 时，会接收标准化记录（历史 + 任务转移项）的可选可调用对象。它必须返回要转发给下一个智能体的输入项的确切列表，使你可以在不编写完整任务转移过滤器的情况下替换内置摘要。 +- [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]：用于在模型调用前立即编辑已完全准备好的模型输入（instructions 和输入项）的钩子，例如裁剪历史或注入系统提示词。 +- [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]：控制 runner 将先前输出转换为下一轮模型输入时，是否保留或省略 reasoning 项 ID。 -##### 追踪和可观测性 +##### 追踪与可观测性 -- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：允许你为整个运行禁用[追踪](tracing.md)。 -- [`tracing`][agents.run.RunConfig.tracing]：传入 [`TracingConfig`][agents.tracing.TracingConfig] 以覆盖 trace 导出设置，例如每次运行的 tracing API key。 -- [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]：配置 trace 是否包含潜在敏感数据，例如 LLM 和工具调用的输入/输出。 -- [`workflow_name`][agents.run.RunConfig.workflow_name]、[`trace_id`][agents.run.RunConfig.trace_id]、[`group_id`][agents.run.RunConfig.group_id]：设置运行的 tracing 工作流名称、trace ID 和 trace group ID。我们建议至少设置 `workflow_name`。group ID 是一个可选字段，可用于关联多次运行的 trace。 -- [`trace_metadata`][agents.run.RunConfig.trace_metadata]：要包含在所有 trace 中的元数据。 +- [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]：允许你为整个运行禁用[追踪](tracing.md)。 +- [`tracing`][agents.run.RunConfig.tracing]：传入 [`TracingConfig`][agents.tracing.TracingConfig] 以覆盖追踪导出设置，例如每次运行的追踪 API key。 +- [`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]：要包含在所有追踪中的元数据。 -##### 工具执行、审批和工具错误行为 +##### 工具执行、审批与工具错误行为 -- [`tool_execution`][agents.run.RunConfig.tool_execution]：配置本地工具调用在 SDK 侧的执行行为，例如限制同时运行的工具调用数量。 -- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：自定义审批流程中工具调用被拒绝时对模型可见的消息。 +- [`tool_execution`][agents.run.RunConfig.tool_execution]：为本地工具调用配置 SDK 侧执行行为，例如限制同时运行多少个工具调用。 +- [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]：自定义审批流程中工具调用被拒绝时，模型可见的消息。 -嵌套任务转移是一个可选择启用的 beta 功能。通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠记录行为，或设置 `handoff(..., nest_handoff_history=True)` 以仅对特定任务转移启用。如果你更希望保留原始记录（默认行为），请不要设置该标志，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`），以按你的需要精确转发对话。若要更改生成摘要中使用的包装文本，而不编写自定义 mapper，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 来恢复默认值）。 +嵌套任务转移以选择加入 beta 的形式提供。通过传入 `RunConfig(nest_handoff_history=True)` 启用折叠记录行为，或设置 `handoff(..., nest_handoff_history=True)` 为特定任务转移启用该行为。如果你希望保留原始记录（默认行为），请不设置该标志，或提供一个 `handoff_input_filter`（或 `handoff_history_mapper`），按你的需求精确转发对话。若要更改生成摘要中使用的包装文本，而不编写自定义 mapper，请调用 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（以及 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 以恢复默认值）。 #### 运行配置详情 ##### `tool_execution` -当你希望 SDK 为一次运行限制本地 function-tool 并发时，请使用 `tool_execution`。 +当你希望 SDK 限制某次运行的本地函数工具并发度时，请使用 `tool_execution`。 ```python from agents import Agent, RunConfig, Runner, ToolExecutionConfig @@ -183,24 +183,24 @@ result = await Runner.run( ) ``` -`max_function_tool_concurrency=None` 会保留默认行为：当模型在一轮中发出多个 function tool 调用时，SDK 会启动所有发出的本地 function tool 调用。设置一个整数值可限制这些本地 function tool 同时运行的数量。 +`max_function_tool_concurrency=None` 会保留默认行为：当模型在一个轮次中发出多个函数工具调用时，SDK 会启动所有已发出的本地函数工具调用。设置整数值可限制这些本地函数工具同时运行的数量。 -这与提供方侧的 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] 是分开的。`parallel_tool_calls` 控制是否允许模型在单个响应中发出多个工具调用。`tool_execution.max_function_tool_concurrency` 控制模型发出本地 function tool 调用后，SDK 如何执行它们。 +这不同于提供方侧的 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]。`parallel_tool_calls` 控制是否允许模型在单个响应中发出多个工具调用。`tool_execution.max_function_tool_concurrency` 控制 SDK 在模型发出本地函数工具调用后如何执行它们。 ##### `tool_error_formatter` -使用 `tool_error_formatter` 可自定义审批流程中工具调用被拒绝时返回给模型的消息。 +使用 `tool_error_formatter` 可以自定义审批流程中工具调用被拒绝时返回给模型的消息。 -formatter 会接收 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]，其中包含： +formatter 会接收包含以下内容的 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]： -- `kind`：错误目录。当前为 `"approval_rejected"`。 -- `tool_type`：工具运行时（`"function"`、`"computer"`、`"shell"`、`"apply_patch"` 或 `"custom"`）。 -- `tool_name`：工具名称。 -- `call_id`：工具调用 ID。 -- `default_message`：SDK 的默认模型可见消息。 -- `run_context`：活动运行上下文包装器。 +- `kind`：错误目录。目前为 `"approval_rejected"`。 +- `tool_type`：工具运行时（`"function"`、`"computer"`、`"shell"`、`"apply_patch"` 或 `"custom"`）。 +- `tool_name`：工具名称。 +- `call_id`：工具调用 ID。 +- `default_message`：SDK 默认的模型可见消息。 +- `run_context`：当前活跃的运行上下文包装器。 -返回一个字符串以替换消息，或返回 `None` 以使用 SDK 默认值。 +返回一个字符串以替换该消息，或返回 `None` 以使用 SDK 默认值。 ```python from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs @@ -225,52 +225,52 @@ result = Runner.run_sync( ##### `reasoning_item_id_policy` -`reasoning_item_id_policy` 控制当 runner 向前传递历史记录时（例如使用 `RunResult.to_input_list()` 或由会话支持的运行），如何将 reasoning items 转换为下一轮模型输入。 +当 runner 将历史向前传递时（例如使用 `RunResult.to_input_list()` 或由 session 支持的运行时），`reasoning_item_id_policy` 控制 reasoning 项如何转换为下一轮模型输入。 -- `None` 或 `"preserve"`（默认）：保留 reasoning item ID。 -- `"omit"`：从生成的下一轮输入中剥离 reasoning item ID。 +- `None` 或 `"preserve"`（默认）：保留 reasoning 项 ID。 +- `"omit"`：从生成的下一轮输入中移除 reasoning 项 ID。 -使用 `"omit"` 主要是作为一种选择启用的缓解措施，用于处理一类 Responses API 400 错误：某个 reasoning item 携带了 `id`，但没有随后的必需项（例如，`Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 +使用 `"omit"` 主要是作为一种选择加入的缓解措施，用于处理某类 Responses API 400 错误：发送了带有 `id` 的 reasoning 项，但没有必需的后续项（例如 `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。 -在多轮智能体运行中，当 SDK 从先前输出构造后续输入（包括会话持久化、服务管理的对话增量、流式/非流式后续轮次以及恢复路径）时，如果保留了 reasoning item ID，但提供方要求该 ID 必须与其对应的后续项保持配对，就可能发生这种情况。 +在多轮智能体运行中，如果 SDK 根据先前输出构造后续输入（包括 session 持久化、服务端管理的对话增量、流式传输/非流式传输的后续轮次以及恢复路径），并且保留了 reasoning 项 ID，但提供方要求该 ID 必须与对应的后续项保持配对，就可能发生这种情况。 -设置 `reasoning_item_id_policy="omit"` 会保留推理内容，但剥离 reasoning item 的 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量。 +设置 `reasoning_item_id_policy="omit"` 会保留 reasoning 内容，但移除 reasoning 项的 `id`，从而避免在 SDK 生成的后续输入中触发该 API 不变量。 -范围说明： +作用范围说明： -- 这只会更改 SDK 在构建后续输入时生成/转发的 reasoning items。 -- 它不会重写用户提供的初始输入项。 -- `call_model_input_filter` 仍可在应用此策略后有意重新引入 reasoning ID。 +- 这只会改变 SDK 在构建后续输入时生成/转发的 reasoning 项。 +- 它不会重写用户提供的初始输入项。 +- `call_model_input_filter` 仍然可以在应用此策略后有意重新引入 reasoning ID。 -## 状态和对话管理 +## 状态与对话管理 ### 内存策略选择 -有四种常见方式可将状态带入下一轮： +将状态带入下一轮有四种常见方式： -| 策略 | 状态所在位置 | 最适合 | 下一轮传入内容 | +| 策略 | 状态所在位置 | 最适合 | 下一轮传入的内容 | | --- | --- | --- | --- | -| `result.to_input_list()` | 你的应用内存 | 小型聊天循环、完全手动控制、任何提供方 | 来自 `result.to_input_list()` 的列表加上下一个用户消息 | -| `session` | 你的存储加 SDK | 持久聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例，或指向同一存储的另一个实例 | +| `result.to_input_list()` | 你的应用内存 | 小型聊天循环、完全手动控制、任何提供方 | 来自 `result.to_input_list()` 的列表加上下一条用户消息 | +| `session` | 你的存储加 SDK | 持久聊天状态、可恢复运行、自定义存储 | 同一个 `session` 实例，或另一个指向同一存储的实例 | | `conversation_id` | OpenAI Conversations API | 你希望跨 worker 或服务共享的命名服务端对话 | 同一个 `conversation_id` 加上仅新的用户轮次 | -| `previous_response_id` | OpenAI Responses API | 无需创建对话资源的轻量级服务管理延续 | `result.last_response_id` 加上仅新的用户轮次 | +| `previous_response_id` | OpenAI Responses API | 无需创建对话资源的轻量级服务端管理延续 | `result.last_response_id` 加上仅新的用户轮次 | -`result.to_input_list()` 和 `session` 由客户端管理。`conversation_id` 和 `previous_response_id` 由 OpenAI 管理，并且仅在使用 OpenAI Responses API 时适用。在大多数应用中，每个对话选择一种持久化策略。混合使用客户端管理的历史和 OpenAI 管理的状态可能会导致上下文重复，除非你有意协调这两层。 +`result.to_input_list()` 和 `session` 由客户端管理。`conversation_id` 和 `previous_response_id` 由 OpenAI 管理，并且仅在你使用 OpenAI Responses API 时适用。在大多数应用中，每个对话选择一种持久化策略。除非你有意协调这两层，否则将客户端管理的历史与 OpenAI 管理的状态混用可能会导致上下文重复。 !!! note - 会话持久化不能与服务管理的对话设置 + Session 持久化不能与服务端管理的对话设置 （`conversation_id`、`previous_response_id` 或 `auto_previous_response_id`）在 - 同一次运行中组合使用。每次调用请选择一种方法。 + 同一次运行中结合使用。每次调用请选择一种方法。 ### 对话/聊天线程 -调用任何 run 方法都可能导致一个或多个智能体运行（因此也可能有一次或多次 LLM 调用），但它表示聊天对话中的一个逻辑轮次。例如： +调用任意 run 方法都可能导致一个或多个智能体运行（因此产生一次或多次 LLM 调用），但它表示聊天对话中的单个逻辑轮次。例如： 1. 用户轮次：用户输入文本 -2. Runner 运行：第一个智能体调用 LLM、运行工具、向第二个智能体执行任务转移，第二个智能体运行更多工具，然后生成输出。 +2. Runner 运行：第一个智能体调用 LLM、运行工具、执行任务转移到第二个智能体，第二个智能体运行更多工具，然后生成输出。 -在智能体运行结束时，你可以选择向用户展示什么。例如，你可以向用户展示智能体生成的每个新项，或者只展示最终输出。无论哪种方式，用户随后都可能提出后续问题，在这种情况下你可以再次调用 run 方法。 +智能体运行结束时，你可以选择向用户展示什么。例如，你可以向用户展示智能体生成的每个新项，或只展示最终输出。无论哪种方式，用户随后都可能提出后续问题，此时你可以再次调用 run 方法。 #### 手动对话管理 @@ -294,9 +294,9 @@ async def main(): # California ``` -#### 使用会话自动管理对话 +#### 使用 Sessions 的自动对话管理 -为简化流程，你可以使用 [Sessions](sessions/index.md) 自动处理对话历史，而无需手动调用 `.to_input_list()`： +对于更简单的方法，你可以使用 [Sessions](sessions/index.md) 自动处理对话历史，而无需手动调用 `.to_input_list()`： ```python from agents import Agent, Runner, SQLiteSession @@ -322,18 +322,18 @@ async def main(): Sessions 会自动： -- 在每次运行前检索对话历史 -- 在每次运行后存储新消息 -- 为不同的会话 ID 维护独立对话 +- 在每次运行前检索对话历史 +- 在每次运行后存储新消息 +- 为不同 session ID 维护独立对话 更多详情请参阅 [Sessions 文档](sessions/index.md)。 -#### 服务管理的对话 +#### 由服务端管理的对话 -你也可以让 OpenAI 的对话状态功能在服务端管理对话状态，而不是在本地用 `to_input_list()` 或 `Sessions` 处理。这样你无需手动重新发送所有过去消息，也能保留对话历史。对于下面任一服务管理方法，每次请求只传入新轮次的输入，并复用保存的 ID。更多详情请参阅 [OpenAI 对话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 +你也可以让 OpenAI 对话状态功能在服务端管理对话状态，而不是使用 `to_input_list()` 或 `Sessions` 在本地处理。这样你无需手动重新发送所有过去的消息，也能保留对话历史。对于下面任一服务端管理方法，请在每次请求中只传入新轮次的输入，并复用已保存的 ID。更多详情请参阅 [OpenAI 对话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。 -OpenAI 提供两种方式跨轮次跟踪状态： +OpenAI 提供两种跨轮次跟踪状态的方式： ##### 1. 使用 `conversation_id` @@ -360,7 +360,7 @@ async def main(): ##### 2. 使用 `previous_response_id` -另一种选择是**响应链式衔接**，其中每个轮次都会显式链接到上一轮的响应 ID。 +另一种选择是**响应链式连接**，其中每个轮次都显式链接到上一轮的响应 ID。 ```python from agents import Agent, Runner @@ -385,30 +385,32 @@ async def main(): print(f"Assistant: {result.final_output}") ``` -如果运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复，SDK 会保留已保存的 `conversation_id` / `previous_response_id` / `auto_previous_response_id` 设置，因此恢复后的轮次会继续在同一个服务管理的对话中进行。 +如果某次运行因审批而暂停，并且你从 [`RunState`][agents.run_state.RunState] 恢复，则 +SDK 会保留已保存的 `conversation_id` / `previous_response_id` / `auto_previous_response_id` +设置，因此恢复后的轮次会继续在同一个服务端管理的对话中进行。 -`conversation_id` 和 `previous_response_id` 互斥。当你需要一个可跨系统共享的命名对话资源时，请使用 `conversation_id`。当你需要从一轮到下一轮的最轻量 Responses API 延续基本组件时，请使用 `previous_response_id`。 +`conversation_id` 和 `previous_response_id` 互斥。当你需要一个可跨系统共享的命名对话资源时，请使用 `conversation_id`。当你需要从一个轮次到下一个轮次的最轻量 Responses API 延续基本组件时，请使用 `previous_response_id`。 !!! note - SDK 会自动使用退避重试 `conversation_locked` 错误。在服务管理的 - 对话运行中，它会在重试前回退内部对话跟踪器输入，以便 - 可以干净地重新发送相同的已准备项。 + SDK 会自动使用退避策略重试 `conversation_locked` 错误。在服务端管理的 + 对话运行中，它会在重试前回退内部对话跟踪器输入，以便可以干净地重新发送 + 相同的已准备项。 - 在基于本地会话的运行中（不能与 `conversation_id`、 - `previous_response_id` 或 `auto_previous_response_id` 组合使用），SDK 还会尽力 - 回滚最近持久化的输入项，以减少重试后重复的历史条目。 + 在本地 session 驱动的运行中（不能与 `conversation_id`、 + `previous_response_id` 或 `auto_previous_response_id` 结合使用），SDK 还会尽力 + 回滚最近持久化的输入项，以减少重试后的重复历史条目。 - 即使你未配置 `ModelSettings.retry`，也会发生此兼容性重试。有关 - 模型请求上更广泛的选择启用重试行为，请参阅 [Runner 管理的重试](models/index.md#runner-managed-retries)。 + 即使你没有配置 `ModelSettings.retry`，也会发生这种兼容性重试。对于 + 模型请求上更广泛的选择加入式重试行为，请参阅 [Runner 管理的重试](models/index.md#runner-managed-retries)。 -## 钩子和自定义 +## 钩子与自定义 -### 调用模型输入过滤器 +### 模型调用输入过滤器 -使用 `call_model_input_filter` 可在模型调用前立即编辑模型输入。该钩子会接收当前智能体、上下文以及组合后的输入项（存在会话历史时包括会话历史），并返回一个新的 `ModelInputData`。 +使用 `call_model_input_filter` 可以在模型调用前编辑模型输入。该钩子会接收当前智能体、上下文以及合并后的输入项（存在 session 历史时也包括它），并返回一个新的 `ModelInputData`。 -返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其 `input` 字段是必需的，并且必须是输入项列表。返回任何其他形状都会抛出 `UserError`。 +返回值必须是 [`ModelInputData`][agents.run.ModelInputData] 对象。其 `input` 字段是必需的，且必须是输入项列表。返回任何其他结构都会引发 `UserError`。 ```python from agents import Agent, Runner, RunConfig @@ -427,19 +429,19 @@ result = Runner.run_sync( ) ``` -runner 会将已准备输入列表的副本传给该钩子，因此你可以裁剪、替换或重新排序它，而不会就地修改调用方的原始列表。 +runner 会将已准备好的输入列表副本传给该钩子，因此你可以裁剪、替换或重新排序它，而不会原地修改调用方的原始列表。 -如果你正在使用会话，`call_model_input_filter` 会在会话历史已加载并与当前轮次合并后运行。当你想要自定义更早的合并步骤本身时，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 +如果你正在使用 session，`call_model_input_filter` 会在 session 历史已经加载并与当前轮次合并后运行。当你想自定义更早的合并步骤本身时，请使用 [`session_input_callback`][agents.run.RunConfig.session_input_callback]。 -如果你正在使用带有 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 的 OpenAI 服务管理对话状态，该钩子会在下一次 Responses API 调用的已准备载荷上运行。该载荷可能已经只表示新轮次增量，而不是对早期历史的完整重放。只有你返回的项会被标记为已发送，用于该服务管理的延续。 +如果你正在使用 OpenAI 服务端管理的对话状态，并带有 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id`，该钩子会在下一次 Responses API 调用的已准备 payload 上运行。该 payload 可能已经只表示新轮次增量，而不是对早期历史的完整重放。只有你返回的项会被标记为已为该服务端管理的延续发送。 -通过 `run_config` 为每次运行设置该钩子，以编辑敏感数据、裁剪较长历史或注入额外系统指导。 +通过 `run_config` 为每次运行设置该钩子，以脱敏敏感数据、裁剪过长历史，或注入额外系统指导。 -## 错误和恢复 +## 错误与恢复 -### 错误处理程序 +### 错误处理器 -所有 `Runner` 入口点都接受 `error_handlers`，这是一个按错误种类作为键的字典。支持的键是 `"max_turns"` 和 `"model_refusal"`。当你希望返回受控的最终输出，而不是抛出 `MaxTurnsExceeded` 或 `ModelRefusalError` 时，请使用它们。 +所有 `Runner` 入口点都接受 `error_handlers`，这是一个以错误种类为键的 dict。支持的键是 `"max_turns"` 和 `"model_refusal"`。当你希望返回受控的最终输出，而不是抛出 `MaxTurnsExceeded` 或 `ModelRefusalError` 时，请使用它们。 ```python from agents import ( @@ -470,7 +472,7 @@ print(result.final_output) 当你不希望将回退输出追加到对话历史时，请设置 `include_in_history=False`。 -当模型拒绝应产生应用特定的回退，而不是以 `ModelRefusalError` 结束运行时，请使用 `"model_refusal"`。 +当模型拒绝应生成应用特定回退，而不是以 `ModelRefusalError` 结束运行时，请使用 `"model_refusal"`。 ```python from pydantic import BaseModel @@ -502,37 +504,37 @@ result = Runner.run_sync( print(result.final_output) ``` -## 持久执行集成和人类参与回路 +## 持久执行集成与人在环 -对于工具审批暂停/恢复模式，请从专门的[人类参与回路指南](human_in_the_loop.md)开始。 -以下集成用于持久编排，适用于运行可能跨越长时间等待、重试或进程重启的场景。 +对于工具审批暂停/恢复模式，请先阅读专门的[人在环指南](human_in_the_loop.md)。 +以下集成适用于运行可能跨越长时间等待、重试或进程重启时的持久编排。 ### Dapr -你可以使用 Agents SDK [Dapr](https://dapr.io) Diagrid 集成来运行持久、长时间运行的智能体，这些智能体会在失败后自动恢复，并支持人类参与回路。Dapr 是一个供应商中立的 [CNCF](https://cncf.io) 工作流编排器。请在[这里](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)开始使用 Dapr 和 OpenAI agents。 +你可以使用 Agents SDK [Dapr](https://dapr.io) Diagrid 集成来运行持久、长时间运行的智能体，它们支持人在环并能在故障后自动恢复。Dapr 是一个厂商中立的 [CNCF](https://cncf.io) 工作流编排器。在[此处](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)开始使用 Dapr 和 OpenAI 智能体。 ### Temporal -你可以使用 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)。 ### Restate -你可以使用 Agents SDK [Restate](https://restate.dev/) 集成来构建轻量、持久的智能体，包括人工审批、任务转移和会话管理。该集成需要 Restate 的单二进制运行时作为依赖，并支持将智能体作为进程/容器或 serverless 函数运行。 -阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)以获取更多详情。 +你可以使用 Agents SDK [Restate](https://restate.dev/) 集成来构建轻量、持久的智能体，包括人工审批、任务转移和 session 管理。该集成需要 Restate 的单二进制运行时作为依赖，并支持将智能体作为进程/容器或无服务函数运行。 +阅读[概览](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)或查看[文档](https://docs.restate.dev/ai)以了解更多详情。 ### DBOS -你可以使用 Agents SDK [DBOS](https://dbos.dev/) 集成来运行可靠的智能体，它们可在失败和重启之间保留进度。它支持长时间运行的智能体、人类参与回路工作流和任务转移。它同时支持同步和异步方法。该集成仅需要 SQLite 或 Postgres 数据库。查看集成[仓库](https://github.com/dbos-inc/dbos-openai-agents)和[文档](https://docs.dbos.dev/integrations/openai-agents)以获取更多详情。 +你可以使用 Agents SDK [DBOS](https://dbos.dev/) 集成来运行可靠的智能体，并在故障和重启之间保留进度。它支持长时间运行的智能体、人在环工作流和任务转移。它同时支持同步和异步方法。该集成只需要 SQLite 或 Postgres 数据库。查看集成的[代码仓库](https://github.com/dbos-inc/dbos-openai-agents)和[文档](https://docs.dbos.dev/integrations/openai-agents)以了解更多详情。 ## 异常 SDK 会在某些情况下抛出异常。完整列表位于 [`agents.exceptions`][]。概览如下： -- [`AgentsException`][agents.exceptions.AgentsException]：这是 SDK 内部抛出的所有异常的基类。它是一个通用类型，所有其他特定异常都派生自它。 -- [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]：当智能体运行超过传给 `Runner.run`、`Runner.run_sync` 或 `Runner.run_streamed` 方法的 `max_turns` 限制时，会抛出此异常。它表示智能体未能在指定的交互轮数内完成任务。设置 `max_turns=None` 可禁用限制。 -- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）生成意外或无效的输出时，会发生此异常。这可能包括： - - 格式错误的 JSON：当模型为工具调用或在其直接输出中提供格式错误的 JSON 结构时，尤其是在定义了特定 `output_type` 的情况下。 - - 意外的工具相关故障：当模型未能按预期方式使用工具时 -- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当工具调用超过其配置的超时时间，并且该工具使用 `timeout_behavior="raise_exception"` 时，会抛出此异常。 -- [`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` 限制时，会抛出此异常。它表示智能体无法在指定数量的交互轮次内完成任务。设置 `max_turns=None` 可禁用该限制。 +- [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]：当底层模型（LLM）生成意外或无效输出时，会发生此异常。这可能包括： + - 格式不正确的 JSON：当模型为工具调用或在其直接输出中提供格式不正确的 JSON 结构时，尤其是在定义了特定 `output_type` 的情况下。 + - 意外的工具相关失败：当模型未能以预期方式使用工具时 +- [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]：当函数工具调用超过其配置的超时时间，并且该工具使用 `timeout_behavior="raise_exception"` 时，会抛出此异常。 +- [`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/sandbox/clients.md b/docs/zh/sandbox/clients.md index 912c375faf..baa659e8d1 100644 --- a/docs/zh/sandbox/clients.md +++ b/docs/zh/sandbox/clients.md @@ -2,42 +2,42 @@ search: exclude: true --- -# Sandbox 客户端 +# 沙盒客户端 -使用本页来选择 sandbox 工作应在哪运行。在大多数情况下，`SandboxAgent` 定义保持不变，而 sandbox 客户端和特定于客户端的选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中发生变化。 +使用本页选择沙盒任务应在哪里运行。大多数情况下，`SandboxAgent`定义保持不变，而沙盒客户端和客户端特定选项会在[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]中变化。 !!! warning "Beta 功能" - Sandbox 智能体处于 beta 阶段。预计 API 的细节、默认值和支持的能力会在正式可用前发生变化，并且更多高级功能也会随着时间逐步推出。 + 沙盒智能体处于 Beta 阶段。在正式发布前，API 的细节、默认值和支持的功能可能会发生变化；未来也会陆续提供更高级的功能。 ## 决策指南
-| 目标 | 起步选择 | 原因 | +| 目标 | 起点 | 原因 | | --- | --- | --- | -| 在 macOS 或 Linux 上实现最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，适合简单的本地文件系统开发。 | -| 基本的容器隔离 | `DockerSandboxClient` | 在 Docker 中使用特定镜像运行工作负载。 | -| 托管执行或生产风格的隔离 | 托管 sandbox 客户端 | 将工作区边界转移到由提供商管理的环境中。 | +| 在 macOS 或 Linux 上进行最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，便于进行简单的本地文件系统开发。 | +| 基本容器隔离 | `DockerSandboxClient` | 使用特定镜像在 Docker 中运行任务。 | +| 托管执行或生产风格隔离 | 一个托管沙盒客户端 | 将工作区边界移动到由提供商管理的环境中。 |
## 本地客户端 -对于大多数用户，请从以下两种 sandbox 客户端之一开始： +对于大多数用户，请从以下两个沙盒客户端之一开始：
-| 客户端 | 安装 | 适用场景 | 示例 | +| 客户端 | 安装 | 选择场景 | 代码示例 | | --- | --- | --- | --- | -| `UnixLocalSandboxClient` | 无 | 在 macOS 或 Linux 上进行最快的本地迭代。适合作为本地开发的默认选择。 | [Unix 本地入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | -| `DockerSandboxClient` | `openai-agents[docker]` | 你需要容器隔离，或希望使用特定镜像来实现本地一致性。 | [Docker 入门](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) | +| `UnixLocalSandboxClient` | 无 | 在 macOS 或 Linux 上进行最快的本地迭代。适合作为本地开发的默认选择。 | [Unix-local 入门示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) | +| `DockerSandboxClient` | `openai-agents[docker]` | 你需要容器隔离，或需要特定镜像来保持本地环境一致性。 | [Docker 入门示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
-Unix 本地方式是开始针对本地文件系统进行开发的最简单方法。当你需要更强的环境隔离或生产风格的一致性时，再迁移到 Docker 或托管提供商。 +Unix-local 是开始基于本地文件系统进行开发的最简单方式。当你需要更强的环境隔离或生产风格的一致性时，再迁移到 Docker 或托管提供商。 -若要从 Unix 本地切换到 Docker，请保持智能体定义不变，仅修改运行配置： +要从 Unix-local 切换到 Docker，请保持智能体定义不变，只更改运行配置： ```python from docker import from_env as docker_from_env @@ -54,17 +54,17 @@ run_config = RunConfig( ) ``` -当你需要容器隔离或镜像一致性时，请使用此方式。请参见[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。 +当你需要容器隔离或镜像一致性时使用此方式。参见[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。 ## 挂载与远程存储 -挂载条目用于描述要暴露的存储；挂载策略用于描述 sandbox 后端如何附加该存储。从 `agents.sandbox.entries` 导入内置挂载条目和通用策略。托管提供商策略可从 `agents.extensions.sandbox` 或提供商专用扩展包中获取。 +挂载条目描述要暴露哪些存储；挂载策略描述沙盒后端如何附加该存储。请从`agents.sandbox.entries`导入内置挂载条目和通用策略。托管提供商策略可从`agents.extensions.sandbox`或提供商特定的扩展包获得。 常见挂载选项： -- `mount_path`：存储在 sandbox 中显示的位置。相对路径会在清单根目录下解析；绝对路径会按原样使用。 -- `read_only`：默认为 `True`。仅当 sandbox 需要将内容写回挂载存储时，才设置为 `False`。 -- `mount_strategy`：必填。请使用同时匹配挂载条目和 sandbox 后端的策略。 +- `mount_path`: 存储在沙盒中的显示位置。相对路径会在清单根目录下解析；绝对路径按原样使用。 +- `read_only`: 默认值为`True`。仅当沙盒需要写回挂载的存储时，才设置为`False`。 +- `mount_strategy`: 必填。使用同时匹配挂载条目和沙盒后端的策略。 挂载会被视为临时工作区条目。快照和持久化流程会分离或跳过已挂载路径，而不是将已挂载的远程存储复制到保存的工作区中。 @@ -74,25 +74,25 @@ run_config = RunConfig( | 策略或模式 | 适用场景 | 说明 | | --- | --- | --- | -| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | sandbox 镜像可以运行 `rclone`。 | 支持 S3、GCS、R2、Azure Blob 和 Box。`RcloneMountPattern` 可在 `fuse` 模式或 `nfs` 模式下运行。 | -| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 镜像中具有 `mount-s3`，且你希望使用 Mountpoint 风格的 S3 或兼容 S3 的访问方式。 | 支持 `S3Mount` 和 `GCSMount`。 | -| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 镜像中具有 `blobfuse2` 且支持 FUSE。 | 支持 `AzureBlobMount`。 | -| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 镜像中具有 `mount.s3files`，并且能够访问现有的 S3 Files 挂载目标。 | 支持 `S3FilesMount`。 | -| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前附加由卷驱动支持的挂载。 | 仅适用于 Docker。S3、GCS、R2、Azure Blob 和 Box 支持 `rclone`；S3 和 GCS 还支持 `mountpoint`。 | +| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 沙盒镜像可以运行`rclone`。 | 支持 S3、GCS、R2、Azure Blob 和 Box。`RcloneMountPattern`可以在`fuse`模式或`nfs`模式下运行。 | +| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 镜像包含`mount-s3`，并且你需要 Mountpoint 风格的 S3 或 S3 兼容访问。 | 支持`S3Mount`和`GCSMount`。 | +| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 镜像包含`blobfuse2`并支持 FUSE。 | 支持`AzureBlobMount`。 | +| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 镜像包含`mount.s3files`，并且可以访问现有的 S3 Files 挂载目标。 | 支持`S3FilesMount`。 | +| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前附加由卷驱动支持的挂载。 | 仅限 Docker。S3、GCS、R2、Azure Blob 和 Box 支持`rclone`；S3 和 GCS 还支持`mountpoint`。 | ## 支持的托管平台 -当你需要托管环境时，通常可以继续使用相同的 `SandboxAgent` 定义，而只需在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中更换 sandbox 客户端。 +当你需要托管环境时，通常可以沿用相同的`SandboxAgent`定义，只在[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]中更改沙盒客户端。 -如果你使用的是已发布的 SDK，而不是此仓库的检出版本，请通过对应的包 extra 安装 sandbox 客户端依赖。 +如果你使用的是已发布的 SDK，而不是此仓库的检出版本，请通过匹配的软件包 extra 安装沙盒客户端依赖。 -有关特定提供商的设置说明以及仓库内扩展示例的链接，请参见[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。 +有关提供商特定的设置说明，以及仓库中已提交的扩展代码示例链接，请参见[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。
-| 客户端 | 安装 | 示例 | +| 客户端 | 安装 | 代码示例 | | --- | --- | --- | | `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) | | `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) | @@ -104,24 +104,24 @@ run_config = RunConfig(
-托管 sandbox 客户端会暴露提供商特定的挂载策略。请选择最适合你的存储提供商的后端和挂载策略： +托管沙盒客户端会提供特定于提供商的挂载策略。请选择最适合你的存储提供商的后端和挂载策略：
| 后端 | 挂载说明 | | --- | --- | -| Docker | 支持将 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` 和 `S3FilesMount` 与 `InContainerMountStrategy`、`DockerVolumeMountStrategy` 等本地策略配合使用。 | -| `ModalSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上通过 `ModalCloudBucketMountStrategy` 挂载 Modal cloud bucket。你可以使用内联凭证或命名的 Modal Secret。 | -| `CloudflareSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和使用 HMAC 认证的 `GCSMount` 上通过 `CloudflareBucketMountStrategy` 挂载 Cloudflare bucket。 | -| `BlaxelSandboxClient` | 支持在 `S3Mount`、`R2Mount` 和 `GCSMount` 上通过 `BlaxelCloudBucketMountStrategy` 挂载 cloud bucket。还支持来自 `agents.extensions.sandbox.blaxel` 的 `BlaxelDriveMount` 和 `BlaxelDriveMountStrategy`，用于持久化的 Blaxel Drive。 | -| `DaytonaSandboxClient` | 支持通过 `DaytonaCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 | -| `E2BSandboxClient` | 支持通过 `E2BCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 | -| `RunloopSandboxClient` | 支持通过 `RunloopCloudBucketMountStrategy` 挂载基于 rclone 的云存储；可与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 搭配使用。 | -| `VercelSandboxClient` | 当前未暴露托管专用的挂载策略。请改用清单文件、代码仓库或其他工作区输入方式。 | +| Docker | 支持将`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`和`S3FilesMount`与`InContainerMountStrategy`、`DockerVolumeMountStrategy`等本地策略配合使用。 | +| `ModalSandboxClient` | 支持在`S3Mount`、`R2Mount`和经过 HMAC 认证的`GCSMount`上使用`ModalCloudBucketMountStrategy`进行 Modal 云存储桶挂载。你可以使用内联凭据或命名的 Modal Secret。 | +| `CloudflareSandboxClient` | 支持在`S3Mount`、`R2Mount`和经过 HMAC 认证的`GCSMount`上使用`CloudflareBucketMountStrategy`进行 Cloudflare 存储桶挂载。 | +| `BlaxelSandboxClient` | 支持在`S3Mount`、`R2Mount`和`GCSMount`上使用`BlaxelCloudBucketMountStrategy`进行云存储桶挂载。还支持使用来自`agents.extensions.sandbox.blaxel`的`BlaxelDriveMount`和`BlaxelDriveMountStrategy`实现持久化 Blaxel Drives。 | +| `DaytonaSandboxClient` | 支持通过`DaytonaCloudBucketMountStrategy`进行由 rclone 支持的云存储挂载；可将其与`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`和`BoxMount`配合使用。 | +| `E2BSandboxClient` | 支持通过`E2BCloudBucketMountStrategy`进行由 rclone 支持的云存储挂载；可将其与`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`和`BoxMount`配合使用。 | +| `RunloopSandboxClient` | 支持通过`RunloopCloudBucketMountStrategy`进行由 rclone 支持的云存储挂载；可将其与`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`和`BoxMount`配合使用。 | +| `VercelSandboxClient` | 目前未暴露特定于托管环境的挂载策略。请改用清单文件、仓库或其他工作区输入。 |
-下表总结了每个后端可以直接挂载的远程存储条目。 +下表总结了每个后端可以直接挂载哪些远程存储条目。
@@ -138,4 +138,4 @@ run_config = RunConfig(
-如需更多可运行的示例，请浏览[examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)了解本地、编码、内存、任务转移和智能体组合模式，并浏览[examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)了解托管 sandbox 客户端。 \ No newline at end of file +如需更多可运行代码示例，请浏览[examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)，了解本地、代码编写、记忆、任务转移和智能体组合模式；并浏览[examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)，了解托管沙盒客户端。 \ No newline at end of file diff --git a/docs/zh/sandbox/guide.md b/docs/zh/sandbox/guide.md index 5526856af4..e9a2aeabcb 100644 --- a/docs/zh/sandbox/guide.md +++ b/docs/zh/sandbox/guide.md @@ -4,37 +4,37 @@ search: --- # 概念 -!!! warning "Beta 功能" +!!! warning "测试版功能" - 沙盒智能体目前处于 Beta 阶段。在正式可用之前，API 细节、默认值和受支持能力可能会发生变化，并且后续会提供更高级的功能。 + 沙盒智能体仍处于测试阶段。在正式可用之前，API细节、默认值和支持的能力可能会发生变化，后续也会逐步提供更高级的功能。 -现代智能体在能够操作文件系统中的真实文件时效果最佳。**沙盒智能体**可以使用专用工具和 shell 命令来搜索和操作大型文档集、编辑文件、生成产物以及运行命令。沙盒会为模型提供一个持久工作区，智能体可以在其中代表你执行工作。Agents SDK 中的沙盒智能体可帮助你轻松运行与沙盒环境配对的智能体，便于将正确的文件放到文件系统中，并编排沙盒，从而更容易大规模启动、停止和恢复任务。 +现代智能体在能够操作文件系统中的真实文件时效果最佳。**沙盒智能体**可以使用专用工具和 shell 命令来检索和操作大型文档集、编辑文件、生成工件并运行命令。沙盒为模型提供一个持久工作区，智能体可以使用它代表你完成工作。Agents SDK中的沙盒智能体可帮助你轻松运行与沙盒环境配对的智能体，便于将正确的文件放到文件系统中，并编排沙盒，从而轻松地大规模启动、停止和恢复任务。 -你可以围绕智能体所需的数据来定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及你提供的其他沙盒输入开始。 +你可以围绕智能体所需的数据定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及你提供的其他沙盒输入开始。
-![带计算能力的沙盒智能体运行框架](../assets/images/harness_with_compute.png) +![带计算环境的沙盒智能体运行框架](../assets/images/harness_with_compute.png)
-`SandboxAgent` 仍然是一个 `Agent`。它保留了常规智能体界面，例如 `instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍通过常规 `Runner` API 运行。变化的是执行边界： +`SandboxAgent`仍然是一个`Agent`。它保留了常规智能体接口，例如`instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍然通过常规`Runner` API运行。变化的是执行边界： -- `SandboxAgent` 定义智能体本身：常规智能体配置，加上沙盒专用默认值，如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、技能、记忆或压缩等能力。 -- `Manifest` 声明全新沙盒工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。 -- 沙盒会话是运行命令并发生文件变化的实时隔离环境。 -- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定本次运行如何获得该沙盒会话，例如直接注入一个会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建一个全新的沙盒会话。 -- 已保存的沙盒状态和快照可让后续运行重新连接到先前的工作，或从已保存内容为新的沙盒会话提供种子。 +- `SandboxAgent`定义智能体本身：常规智能体配置，以及沙盒特定默认值，例如`default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、技能、记忆或压缩等能力。 +- `Manifest`声明全新沙盒工作区所需的起始内容和布局，包括文件、仓库、挂载和环境。 +- 沙盒会话是命令运行和文件发生变化的活动隔离环境。 +- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]决定本次运行如何获得该沙盒会话，例如直接注入一个会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建全新的沙盒会话。 +- 已保存的沙盒状态和快照允许后续运行重新连接到先前的工作，或使用已保存内容为全新沙盒会话设定初始状态。 -`Manifest` 是全新会话的工作区契约，而不是每个实时沙盒的完整事实来源。一次运行的有效工作区也可能来自复用的沙盒会话、序列化的沙盒会话状态，或运行时选择的快照。 +`Manifest`是新会话工作区契约，而不是每个活动沙盒的完整事实来源。一次运行的有效工作区也可以来自重用的沙盒会话、序列化的沙盒会话状态，或运行时选择的快照。 -在本页中，“沙盒会话”指由沙盒客户端管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 对话式 [`Session`][agents.memory.session.Session] 接口。 +在本页中，“沙盒会话”指由沙盒客户端管理的活动执行环境。它不同于[会话](../sessions/index.md)中描述的 SDK 对话式[`Session`][agents.memory.session.Session]接口。 -外层运行时仍负责审批、追踪、任务转移和恢复簿记。沙盒会话负责命令、文件变更和环境隔离。这种分离是该模型的核心部分。 +外层运行时仍负责审批、追踪、任务转移和恢复记录。沙盒会话负责命令、文件变更和环境隔离。这种分工是该模型的核心部分。 -### 各部分的配合方式 +### 组件关系 -一次沙盒运行会将智能体定义与每次运行的沙盒配置结合起来。runner 会准备智能体，将其绑定到一个实时沙盒会话，并可保存状态以供后续运行使用。 +一次沙盒运行将智能体定义与每次运行的沙盒配置组合起来。运行器会准备智能体，将它绑定到活动沙盒会话，并可以保存状态供后续运行使用。 ```mermaid flowchart LR @@ -50,205 +50,205 @@ flowchart LR sandbox --> saved ``` -沙盒专用默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。 +沙盒特定默认值保留在`SandboxAgent`上。每次运行的沙盒会话选择保留在`SandboxRunConfig`中。 可以将生命周期看作三个阶段： -1. 使用 `SandboxAgent`、`Manifest` 和能力来定义智能体以及全新工作区契约。 -2. 通过向 `Runner` 提供会注入、恢复或创建沙盒会话的 `SandboxRunConfig` 来执行一次运行。 -3. 后续从 runner 管理的 `RunState`、显式沙盒 `session_state` 或已保存的工作区快照继续。 +1. 使用`SandboxAgent`、`Manifest`和能力定义智能体以及全新工作区契约。 +2. 通过向`Runner`提供一个会注入、恢复或创建沙盒会话的`SandboxRunConfig`来执行运行。 +3. 稍后从运行器管理的`RunState`、显式沙盒`session_state`或已保存的工作区快照继续。 -如果 shell 访问只是偶尔使用的一个工具，请从 [工具指南](../tools.md) 中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，再使用沙盒智能体。 +如果 shell 访问只是偶尔使用的一个工具，请从[工具指南](../tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，再使用沙盒智能体。 ## 使用场景 沙盒智能体非常适合以工作区为中心的工作流，例如： -- 编码和调试，例如为 GitHub 仓库中的问题报告编排自动修复并运行定向测试 -- 文档处理和编辑，例如从用户的财务文档中提取信息并创建填写完成的税表草稿 -- 基于文件的审阅或分析，例如在回答前检查入职材料包、生成的报告或产物包 -- 隔离的多智能体模式，例如为每个审阅者或编码子智能体提供自己的工作区 +- 编码和调试，例如在 GitHub 仓库中编排针对问题报告的自动修复，并运行定向测试 +- 文档处理和编辑，例如从用户的财务文档中提取信息，并创建已填写的税表草稿 +- 基于文件的审阅或分析，例如在回答前检查入职材料包、生成的报告或工件包 +- 隔离的多智能体模式，例如为每个审阅者或编码子智能体提供各自的工作区 - 多步骤工作区任务，例如在一次运行中修复 bug，稍后添加回归测试，或从快照或沙盒会话状态恢复 -如果你不需要访问文件或实时文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加托管 shell；如果工作区边界本身就是功能的一部分，请使用沙盒智能体。 +如果你不需要访问文件或活动文件系统，请继续使用`Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加托管 shell；如果工作区边界本身就是功能的一部分，请使用沙盒智能体。 ## 沙盒客户端选择 -本地开发请从 `UnixLocalSandboxClient` 开始。当你需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当你需要由提供商管理的执行环境时，切换到托管提供商。 +本地开发请从`UnixLocalSandboxClient`开始。当你需要容器隔离或镜像一致性时，改用`DockerSandboxClient`。当你需要由提供方管理的执行环境时，改用托管提供方。 -在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参阅 [沙盒客户端](clients.md)。 +大多数情况下，`SandboxAgent`定义保持不变，而沙盒客户端及其选项会在[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]中变化。有关本地、Docker、托管和远程挂载选项，请参阅[沙盒客户端](clients.md)。 -## 核心组成 +## 核心组成部分
-| 层级 | 主要 SDK 组件 | 回答的问题 | +| 层 | SDK 主要组件 | 解答的问题 | | --- | --- | --- | -| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行哪个智能体，以及它应从什么全新会话工作区契约开始？ | -| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和实时沙盒会话 | 本次运行如何获得实时沙盒会话，工作在哪里执行？ | -| 已保存沙盒状态 | `RunState` 沙盒载荷、`session_state` 和快照 | 该工作流如何重新连接到先前的沙盒工作，或从已保存内容为全新沙盒会话提供种子？ | +| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 要运行哪个智能体，以及它应从什么样的新会话工作区契约开始？ | +| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和活动沙盒会话 | 本次运行如何获得活动沙盒会话，工作在哪里执行？ | +| 已保存的沙盒状态 | `RunState`沙盒载荷、`session_state`和快照 | 此工作流如何重新连接到之前的沙盒工作，或使用已保存内容为全新沙盒会话设定初始状态？ |
-主要 SDK 组件与这些层级的对应关系如下： +主要 SDK 组件与这些层的对应关系如下：
-| 组件 | 拥有的内容 | 应提出的问题 | +| 组件 | 所负责内容 | 需要回答的问题 | | --- | --- | --- | -| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应随它一起传递？ | -| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新会话工作区文件和文件夹 | 运行开始时，文件系统上应有哪些文件和文件夹？ | -| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 沙盒原生行为 | 哪些工具、指令片段或运行时行为应附加到这个智能体？ | +| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 此智能体应该做什么，哪些默认设置应随它一起生效？ | +| [`Manifest`][agents.sandbox.manifest.Manifest] | 新会话工作区文件和文件夹 | 运行开始时，文件系统上应有哪些文件和文件夹？ | +| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 沙盒原生行为 | 哪些工具、指令片段或运行时行为应附加到此智能体？ | | [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 每次运行的沙盒客户端和沙盒会话来源 | 本次运行应注入、恢复还是创建沙盒会话？ | -| [`RunState`][agents.run_state.RunState] | Runner 管理的已保存沙盒状态 | 我是否正在恢复先前由 runner 管理的工作流，并自动继续携带其沙盒状态？ | -| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否想从已在 `RunState` 外部序列化的沙盒状态恢复？ | -| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新沙盒会话的已保存工作区内容 | 新的沙盒会话是否应从已保存文件和产物开始？ | +| [`RunState`][agents.run_state.RunState] | `Runner`管理的已保存沙盒状态 | 我是否正在恢复一个先前由运行器管理的工作流，并自动继续携带其沙盒状态？ | +| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否想从已经在`RunState`之外序列化的沙盒状态恢复？ | +| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新沙盒会话的已保存工作区内容 | 新沙盒会话是否应从已保存的文件和工件开始？ |
-一个实用的设计顺序是： +实用的设计顺序如下： -1. 使用 `Manifest` 定义全新会话工作区契约。 -2. 使用 `SandboxAgent` 定义智能体。 +1. 使用`Manifest`定义新会话工作区契约。 +2. 使用`SandboxAgent`定义智能体。 3. 添加内置或自定义能力。 -4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获得其沙盒会话。 +4. 在`RunConfig(sandbox=SandboxRunConfig(...))`中决定每次运行应如何获得其沙盒会话。 -## 沙盒运行的准备方式 +## 沙盒运行准备流程 -运行时，runner 会将该定义转换为具体的沙盒支持运行： +运行时，运行器会将该定义转换为具体的沙盒支持运行： -1. 它从 `SandboxRunConfig` 解析沙盒会话。 - 如果你传入 `session=...`，它会复用该实时沙盒会话。 - 否则，它使用 `client=...` 创建或恢复一个会话。 -2. 它确定本次运行的有效工作区输入。 - 如果运行注入或恢复沙盒会话，则该现有沙盒状态优先。 - 否则，runner 会从一次性的 manifest 覆盖或 `agent.default_manifest` 开始。 - 这就是为什么单独的 `Manifest` 并不能定义每次运行最终的实时工作区。 -3. 它让能力处理生成的 manifest。 - 能力可以通过这种方式在最终智能体准备完成之前添加文件、挂载或其他工作区范围的行为。 -4. 它按固定顺序构建最终 instructions： - SDK 的默认沙盒提示词，或你显式覆盖时的 `base_instructions`，然后是 `instructions`，然后是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。 -5. 它将能力工具绑定到实时沙盒会话，并通过常规 `Runner` API 运行准备好的智能体。 +1. 它会从`SandboxRunConfig`解析沙盒会话。 + 如果你传入`session=...`，它会重用该活动沙盒会话。 + 否则，它会使用`client=...`创建或恢复一个会话。 +2. 它会确定本次运行的有效工作区输入。 + 如果本次运行注入或恢复沙盒会话，则该现有沙盒状态优先生效。 + 否则，运行器会从一次性清单覆盖或`agent.default_manifest`开始。 + 这就是为什么仅靠`Manifest`并不能定义每次运行最终的活动工作区。 +3. 它会让能力处理生成的清单。 + 这就是能力如何在准备最终智能体之前添加文件、挂载或其他作用于工作区范围的行为。 +4. 它会按固定顺序构建最终指令： + SDK 的默认沙盒提示词；或者如果你显式覆盖了它，则使用`base_instructions`；然后是`instructions`；然后是能力指令片段；然后是任何远程挂载策略文本；最后是渲染后的文件系统树。 +5. 它会将能力工具绑定到活动沙盒会话，并通过常规`Runner` API运行准备好的智能体。 -沙盒化不会改变一个 turn 的含义。一个 turn 仍然是一个模型步骤，而不是单个 shell 命令或沙盒操作。沙盒侧操作与 turn 之间没有固定的 1:1 映射：有些工作可能停留在沙盒执行层内部，而其他操作会返回工具结果、审批或其他需要另一个模型步骤的状态。作为实用规则，只有当智能体运行时在沙盒工作发生后需要另一个模型响应时，才会消耗另一个 turn。 +沙盒化不会改变“回合”的含义。一个回合仍然是一次模型步骤，而不是单个 shell 命令或沙盒动作。沙盒侧操作与回合之间没有固定的 1:1 映射：有些工作可能停留在沙盒执行层内部，而其他动作会返回工具结果、审批或其他需要下一次模型步骤的状态。作为实用规则，只有当智能体运行时在沙盒工作发生后需要另一个模型响应时，才会消耗另一个回合。 -这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是需要重点考虑的主要沙盒专用选项。 +这些准备步骤说明了为什么在设计`SandboxAgent`时，`default_manifest`、`instructions`、`base_instructions`、`capabilities`和`run_as`是主要需要考虑的沙盒特定选项。 -## `SandboxAgent` 选项 +## `SandboxAgent`选项 -这些是在常规 `Agent` 字段之上的沙盒专用选项： +这些是在常规`Agent`字段之上的沙盒特定选项：
| 选项 | 最佳用途 | | --- | --- | -| `default_manifest` | runner 创建的全新沙盒会话的默认工作区。 | -| `instructions` | 附加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 | -| `base_instructions` | 替换 SDK 沙盒提示词的高级逃生舱。 | -| `capabilities` | 应随该智能体一起传递的沙盒原生工具和行为。 | -| `run_as` | 面向模型的沙盒工具（如 shell 命令、文件读取和补丁）的用户身份。 | +| `default_manifest` | 运行器创建的全新沙盒会话的默认工作区。 | +| `instructions` | 追加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 | +| `base_instructions` | 用于替换 SDK 沙盒提示词的高级兜底选项。 | +| `capabilities` | 应随此智能体一起生效的沙盒原生工具和行为。 | +| `run_as` | 面向模型的沙盒工具（例如 shell 命令、文件读取和补丁）的用户身份。 |
-沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择应属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体。 +沙盒客户端选择、沙盒会话重用、清单覆盖和快照选择属于[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体本身。 ### `default_manifest` -`default_manifest` 是 runner 为该智能体创建全新沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。可将它用于智能体通常应从中开始的文件、仓库、辅助材料、输出目录和挂载。 +`default_manifest`是运行器为此智能体创建全新沙盒会话时使用的默认[`Manifest`][agents.sandbox.manifest.Manifest]。可将它用于智能体通常应以哪些文件、仓库、辅助材料、输出目录和挂载作为起点。 -这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。 +这只是默认值。一次运行可以用`SandboxRunConfig(manifest=...)`覆盖它，而重用或恢复的沙盒会话会保留其现有工作区状态。 -### `instructions` 和 `base_instructions` +### `instructions`和`base_instructions` -将 `instructions` 用于应在不同提示词之间保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会附加在 SDK 的沙盒基础提示词之后，因此你会保留内置沙盒指导，并添加自己的角色、工作流和成功标准。 +将`instructions`用于应在不同提示词之间保持的简短规则。在`SandboxAgent`中，这些指令会追加在 SDK 的沙盒基础提示词之后，因此你可以保留内置沙盒指导，并添加自己的角色、工作流和成功标准。 -仅在你想替换 SDK 沙盒基础提示词时使用 `base_instructions`。大多数智能体不应设置它。 +只有当你想替换 SDK 沙盒基础提示词时，才使用`base_instructions`。大多数智能体不应设置它。
| 放在... | 用途 | 示例 | | --- | --- | --- | -| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后进行任务转移。”、“将最终文件写入 `output/`。” | -| `base_instructions` | SDK 沙盒基础提示词的完整替换。 | 自定义底层沙盒包装提示词。 | -| 用户提示词 | 本次运行的一次性请求。 | “总结这个工作区。” | -| manifest 中的工作区文件 | 更长的任务规范、仓库本地指令或有界参考材料。 | `repo/task.md`、文档包、示例材料包。 | +| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后交接。”、“将最终文件写入`output/`。” | +| `base_instructions` | 对 SDK 沙盒基础提示词的完整替代。 | 自定义低层沙盒包装提示词。 | +| 用户提示词 | 本次运行的一次性请求。 | “总结此工作区。” | +| 清单中的工作区文件 | 较长的任务规范、仓库本地指令或有边界的参考材料。 | `repo/task.md`、文档包、示例包。 |
-`instructions` 的良好用途包括： +`instructions`的良好用法包括： -- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态重要时让智能体保持在一个交互式进程中。 +- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态很重要时，让智能体保持在一个交互式进程中。 - [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) 禁止沙盒审阅者在检查后直接回答用户。 -- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填好的文件实际落在 `output/` 中。 -- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定精确的验证命令，并明确相对于工作区根目录的补丁路径。 +- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写好的文件实际落在`output/`中。 +- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定确切的验证命令，并明确相对于工作区根的补丁路径。 -避免将用户的一次性任务复制到 `instructions` 中，避免嵌入应属于 manifest 的长篇参考材料，避免重复内置能力已经注入的工具文档，也避免混入模型在运行时不需要的本地安装说明。 +避免将用户的一次性任务复制到`instructions`中，避免嵌入本应放在清单中的长篇参考材料，避免重复内置能力已经注入的工具文档，也避免混入模型在运行时不需要的本地安装说明。 -如果省略 `instructions`，SDK 仍会包含默认沙盒提示词。这对底层包装器已经足够，但大多数面向用户的智能体仍应提供显式 `instructions`。 +如果省略`instructions`，SDK 仍会包含默认沙盒提示词。对于低层包装器来说这已经足够，但大多数面向用户的智能体仍应提供显式`instructions`。 ### `capabilities` -能力会将沙盒原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区、追加沙盒专用指令、暴露绑定到实时沙盒会话的工具，并调整该智能体的模型行为或输入处理。 +能力会将沙盒原生行为附加到`SandboxAgent`。它们可以在运行开始前调整工作区，追加沙盒特定指令，暴露绑定到活动沙盒会话的工具，并为该智能体调整模型行为或输入处理。 内置能力包括：
-| 能力 | 何时添加 | 备注 | +| 能力 | 添加时机 | 备注 | | --- | --- | --- | -| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，当沙盒客户端支持 PTY 交互时还会添加 `write_stdin`。 | -| `Filesystem` | 智能体需要编辑文件或检查本地图像。 | 添加 `apply_patch` 和 `view_image`；补丁路径相对于工作区根目录。 | -| `Skills` | 你想在沙盒中进行技能发现和物化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你将技能索引并物化到沙盒中。 | -| `Memory` | 后续运行应读取或生成记忆产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 | -| `Compaction` | 长时间运行的流程需要在压缩项之后裁剪上下文。 | 调整模型采样和输入处理。 | +| `Shell` | 智能体需要 shell 访问。 | 添加`exec_command`；当沙盒客户端支持 PTY 交互时，还会添加`write_stdin`。 | +| `Filesystem` | 智能体需要编辑文件或检查本地图像。 | 添加`apply_patch`和`view_image`；补丁路径相对于工作区根。 | +| `Skills` | 你需要在沙盒中进行技能发现和物化。 | 优先使用它，而不是手动挂载`.agents`或`.agents/skills`；`Skills`会为你索引技能并将技能物化到沙盒中。 | +| `Memory` | 后续运行应读取或生成记忆工件。 | 需要`Shell`；实时更新还需要`Filesystem`。 | +| `Compaction` | 长时间运行的流程需要在压缩项之后进行上下文修剪。 | 调整模型采样和输入处理。 |
-默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍想保留的任何默认能力。 +默认情况下，`SandboxAgent.capabilities`使用`Capabilities.default()`，其中包括`Filesystem()`、`Shell()`和`Compaction()`。如果传入`capabilities=[...]`，该列表会替换默认值，因此请包含你仍然需要的任何默认能力。 对于技能，请根据你希望它们如何物化来选择来源： -- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大本地技能目录的良好默认值，因为模型可以先发现索引，并只加载所需内容。 -- `LocalDirLazySkillSource(source=LocalDir(src=...))` 从运行 SDK 进程的文件系统读取。请传入原始主机侧技能目录，而不是仅存在于沙盒镜像或工作区内的路径。 -- `Skills(from_=LocalDir(src=...))` 更适合你想预先暂存的小型本地包。 -- `Skills(from_=GitRepo(repo=..., ref=...))` 适合技能本身应来自某个仓库的情况。 +- `Skills(lazy_from=LocalDirLazySkillSource(...))`对于较大的本地技能目录是一个不错的默认选择，因为模型可以先发现索引，并且只加载它需要的内容。 +- `LocalDirLazySkillSource(source=LocalDir(src=...))`从 SDK 进程运行所在的文件系统读取。请传入原始宿主机侧技能目录，而不是仅存在于沙盒镜像或工作区内部的路径。 +- `Skills(from_=LocalDir(src=...))`更适合你希望预先暂存的小型本地包。 +- `Skills(from_=GitRepo(repo=..., ref=...))`适合技能本身应来自仓库的情况。 -`LocalDir.src` 是 SDK 主机上的源路径。`skills_path` 是沙盒工作区内的相对目标路径，在调用 `load_skill` 时技能会被暂存到那里。 +`LocalDir.src`是 SDK 宿主机上的源路径。`skills_path`是沙盒工作区内部的相对目标路径，调用`load_skill`时技能会被暂存到那里。 -如果你的技能已经以类似 `.agents/skills//SKILL.md` 的结构存在于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍使用 `Skills(...)` 暴露它们。除非你已有依赖不同沙盒内布局的工作区契约，否则请保留默认的 `skills_path=".agents"`。 +如果你的技能已经位于磁盘上类似`.agents/skills//SKILL.md`的位置，请将`LocalDir(...)`指向该源根目录，并仍然使用`Skills(...)`来暴露它们。除非你已有的工作区契约依赖沙盒内不同布局，否则请保留默认的`skills_path=".agents"`。 -在适用时优先使用内置能力。仅当你需要内置能力未覆盖的沙盒专用工具或指令界面时，才编写自定义能力。 +当内置能力适用时，请优先使用内置能力。只有当你需要内置能力未覆盖的沙盒特定工具或指令接口时，才编写自定义能力。 ## 概念 ### Manifest -[`Manifest`][agents.sandbox.manifest.Manifest] 描述全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。 +[`Manifest`][agents.sandbox.manifest.Manifest]描述全新沙盒会话的工作区。它可以设置工作区`root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。 -Manifest 条目路径是相对于工作区的。它们不能是绝对路径，也不能使用 `..` 逃逸工作区，这使工作区契约可在本地、Docker 和托管客户端之间移植。 +清单条目路径是相对于工作区的。它们不能是绝对路径，也不能使用`..`逃逸工作区，这使工作区契约能够在本地、Docker 和托管客户端之间保持可移植。 -将 manifest 条目用于智能体在工作开始前所需的材料： +将清单条目用于智能体开始工作前需要的材料：
-| Manifest 条目 | 用途 | +| 清单条目 | 用途 | | --- | --- | | `File`、`Dir` | 小型合成输入、辅助文件或输出目录。 | -| `LocalFile`、`LocalDir` | 应物化到沙盒中的主机文件或目录。 | +| `LocalFile`、`LocalDir` | 应物化到沙盒中的宿主机文件或目录。 | | `GitRepo` | 应拉取到工作区中的仓库。 | -| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` 等挂载 | 应显示在沙盒内的外部存储。 | +| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount`等挂载 | 应出现在沙盒内部的外部存储。 |
-`Dir` 会从合成子项创建沙盒工作区内的目录，或作为输出位置；它不会从主机文件系统读取。当已有主机目录应复制到沙盒工作区时，请使用 `LocalDir`。 +`Dir`会在沙盒工作区内部从合成子项创建目录，或作为输出位置创建目录；它不会从宿主机文件系统读取。若要将现有宿主机目录复制到沙盒工作区中，请使用`LocalDir`。 -`LocalFile.src` 和 `LocalDir.src` 默认相对于 SDK 进程工作目录解析。源必须保持在该基础目录之下，除非它由 `extra_path_grants` 覆盖。这使本地源物化保持在与沙盒 manifest 其余部分相同的主机路径信任边界内。 +默认情况下，`LocalFile.src`和`LocalDir.src`会相对于 SDK 进程工作目录解析。源必须保持在该基础目录之下，除非它由`extra_path_grants`覆盖。这会将本地源物化限制在与沙盒清单其余部分相同的宿主机路径信任边界内。 -挂载条目描述要暴露哪些存储；挂载策略描述沙盒后端如何附加该存储。有关挂载选项和提供商支持，请参阅 [沙盒客户端](clients.md#mounts-and-remote-storage)。 +挂载条目描述要暴露的存储；挂载策略描述沙盒后端如何附加该存储。有关挂载选项和提供方支持，请参阅[沙盒客户端](clients.md#mounts-and-remote-storage)。 -良好的 manifest 设计通常意味着保持工作区契约狭窄，将长任务配方放入工作区文件（如 `repo/task.md`），并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径相对于沙盒工作区根目录，而不是 shell 的 `workdir`。 +良好的清单设计通常意味着保持工作区契约狭窄，将较长的任务说明放在工作区文件中，例如`repo/task.md`，并在指令中使用相对工作区路径，例如`repo/task.md`或`output/report.md`。如果智能体使用`Filesystem`能力的`apply_patch`工具编辑文件，请记住补丁路径相对于沙盒工作区根，而不是 shell 的`workdir`。 -仅在智能体需要工作区外的具体绝对路径，或 manifest 需要复制 SDK 进程工作目录外的受信任本地源时，才使用 `extra_path_grants`。示例包括用于临时工具输出的 `/tmp`、用于只读运行时的 `/opt/toolchain`，或应物化到沙盒中的已生成技能目录。授权适用于本地源物化、SDK 文件 API，以及后端能够强制执行文件系统策略时的 shell 执行： +仅当智能体需要工作区外的具体绝对路径，或清单需要复制 SDK 进程工作目录外的可信本地源时，才使用`extra_path_grants`。示例包括用于临时工具输出的`/tmp`、用于只读运行时的`/opt/toolchain`，或应物化到沙盒中的已生成技能目录。授权适用于本地源物化、SDK 文件 API，以及后端可以强制执行文件系统策略时的 shell 执行： ```python from agents.sandbox import Manifest, SandboxPathGrant @@ -261,15 +261,15 @@ manifest = Manifest( ) ``` -将包含 `extra_path_grants` 的 manifest 视为受信任配置。不要从模型输出或其他不受信任载荷中加载授权，除非你的应用已经批准这些主机路径。 +请将包含`extra_path_grants`的清单视为可信配置。除非你的应用已经批准了这些宿主机路径，否则不要从模型输出或其他不可信载荷中加载授权。 -快照和 `persist_workspace()` 仍只包含工作区根目录。额外授权路径是运行时访问，不是持久工作区状态。 +快照和`persist_workspace()`仍然只包含工作区根。额外授权的路径是运行时访问，不是持久工作区状态。 -### 权限 +### Permissions -`Permissions` 控制 manifest 条目的文件系统权限。它关注的是沙盒物化的文件，而不是模型权限、审批策略或 API 凭证。 +`Permissions`控制清单条目的文件系统权限。它针对的是沙盒物化的文件，而不是模型权限、审批策略或 API 凭证。 -默认情况下，manifest 条目可由所有者读取/写入/执行，并可由组和其他用户读取/执行。当暂存文件应为私有、只读或可执行时，请覆盖此设置： +默认情况下，清单条目对所有者可读/写/执行，对组和其他用户可读/执行。当暂存文件应为私有、只读或可执行时，请覆盖此设置： ```python from agents.sandbox import FileMode, Permissions @@ -285,9 +285,9 @@ private_notes = File( ) ``` -`Permissions` 存储单独的所有者、组和其他用户位，以及该条目是否为目录。你可以直接构建它，使用 `Permissions.from_str(...)` 从模式字符串解析它，或使用 `Permissions.from_mode(...)` 从 OS 模式派生它。 +`Permissions`分别存储所有者、组和其他用户的位，以及该条目是否为目录。你可以直接构建它，使用`Permissions.from_str(...)`从模式字符串解析它，或使用`Permissions.from_mode(...)`从 OS 模式派生它。 -用户是可以执行工作的沙盒身份。当你希望该身份存在于沙盒中时，请将 `User` 添加到 manifest，然后在面向模型的沙盒工具（如 shell 命令、文件读取和补丁）应以该用户运行时设置 `SandboxAgent.run_as`。如果 `run_as` 指向的用户尚不在 manifest 中，runner 会为你将其添加到有效 manifest 中。 +用户是在沙盒中可以执行工作的身份。当你希望该身份存在于沙盒中时，请向清单添加`User`；然后，当面向模型的沙盒工具（例如 shell 命令、文件读取和补丁）应以该用户运行时，设置`SandboxAgent.run_as`。如果`run_as`指向一个尚未在清单中的用户，运行器会为你将其添加到有效清单中。 ```python from agents import Runner @@ -339,13 +339,13 @@ result = await Runner.run( ) ``` -如果还需要文件级共享规则，请将用户与 manifest 组和条目 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生操作；`Permissions` 控制沙盒物化工作区后，该用户可以读取、写入或执行哪些文件。 +如果你还需要文件级共享规则，请将用户与清单组和条目`group`元数据结合使用。`run_as`用户控制谁执行沙盒原生动作；`Permissions`控制沙盒物化工作区后，该用户可以读取、写入或执行哪些文件。 ### SnapshotSpec -`SnapshotSpec` 告诉全新沙盒会话应从哪里恢复已保存工作区内容，以及应将其持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。 +`SnapshotSpec`告诉全新沙盒会话应从哪里恢复已保存的工作区内容，并持久化回哪里。它是沙盒工作区的快照策略，而`session_state`是用于恢复特定沙盒后端的序列化连接状态。 -将 `LocalSnapshotSpec` 用于本地持久快照；当你的应用提供远程快照客户端时，使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会使用 no-op 快照作为回退；当高级调用方不想进行工作区快照持久化时，也可以显式使用它。 +使用`LocalSnapshotSpec`进行本地持久快照；当你的应用提供远程快照客户端时，使用`RemoteSnapshotSpec`。当本地快照设置不可用时，会使用无操作快照作为回退；高级调用方在不希望持久化工作区快照时，也可以显式使用无操作快照。 ```python from pathlib import Path @@ -362,13 +362,13 @@ run_config = RunConfig( ) ``` -当 runner 创建全新沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会先恢复已保存的工作区内容，然后运行继续。清理时，runner 拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。 +当运行器创建全新沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会在运行继续前恢复已保存的工作区内容。清理时，运行器拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。 -如果省略 `snapshot`，运行时会在可行时尝试使用默认本地快照位置。如果无法设置，则回退到 no-op 快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。 +如果省略`snapshot`，运行时会在可行时尝试使用默认本地快照位置。如果无法设置，它会回退到无操作快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。 ### 沙盒生命周期 -有两种生命周期模式：**SDK 拥有** 和 **开发者拥有**。 +生命周期有两种模式：**SDK 拥有**和**开发者拥有**。
@@ -396,7 +396,7 @@ sequenceDiagram
-当沙盒只需为一次运行存活时，请使用 SDK 拥有的生命周期。传入 `client`、可选 `manifest`、可选 `snapshot` 和客户端 `options`；runner 会创建或恢复沙盒、启动它、运行智能体、持久化由快照支持的工作区状态、关闭沙盒，并让客户端清理 runner 拥有的资源。 +当沙盒只需要为一次运行存在时，使用 SDK 拥有的生命周期。传入`client`、可选的`manifest`、可选的`snapshot`和客户端`options`；运行器会创建或恢复沙盒、启动它、运行智能体、持久化由快照支持的工作区状态、关闭沙盒，并让客户端清理运行器拥有的资源。 ```python result = await Runner.run( @@ -408,7 +408,7 @@ result = await Runner.run( ) ``` -当你想提前创建沙盒、在多次运行中复用一个实时沙盒、在运行后检查文件、对你自己创建的沙盒进行流式传输，或精确决定何时清理时，请使用开发者拥有的生命周期。传入 `session=...` 会告诉 runner 使用该实时沙盒，但不会替你关闭它。 +当你想预先创建沙盒、在多次运行之间重用同一个活动沙盒、在运行后检查文件、在自己创建的沙盒上进行流式传输，或精确决定何时清理时，使用开发者拥有的生命周期。传入`session=...`会告诉运行器使用该活动沙盒，但不会让运行器为你关闭它。 ```python sandbox = await client.create(manifest=agent.default_manifest) @@ -440,60 +440,60 @@ finally: await sandbox.aclose() ``` -`stop()` 只会持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它运行停止前 hooks，调用 `stop()`，关闭沙盒资源，并关闭会话范围的依赖项。 +`stop()`只会持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()`是完整的会话清理路径：它运行停止前 hooks、调用`stop()`、关闭沙盒资源，并关闭会话范围的依赖项。 -## `SandboxRunConfig` 选项 +## `SandboxRunConfig`选项 -[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，这些选项决定沙盒会话来自哪里，以及如何初始化全新会话。 +[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]保存每次运行的选项，这些选项决定沙盒会话来自哪里，以及全新会话应如何初始化。 ### 沙盒来源 -这些选项决定 runner 应复用、恢复还是创建沙盒会话： +这些选项决定运行器应重用、恢复还是创建沙盒会话：
| 选项 | 使用时机 | 备注 | | --- | --- | --- | -| `client` | 你希望 runner 为你创建、恢复并清理沙盒会话。 | 除非你提供实时沙盒 `session`，否则必需。 | -| `session` | 你已经自己创建了实时沙盒会话。 | 调用方拥有生命周期；runner 复用该实时沙盒会话。 | -| `session_state` | 你有序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；runner 从该显式状态恢复为拥有型会话。 | +| `client` | 你希望运行器为你创建、恢复并清理沙盒会话。 | 必需，除非你提供活动沙盒`session`。 | +| `session` | 你已经自己创建了活动沙盒会话。 | 调用方拥有生命周期；运行器会重用该活动沙盒会话。 | +| `session_state` | 你有序列化的沙盒会话状态，但没有活动沙盒会话对象。 | 需要`client`；运行器会以拥有会话的方式从该显式状态恢复。 |
-实践中，runner 会按以下顺序解析沙盒会话： +实际中，运行器会按以下顺序解析沙盒会话： -1. 如果你注入 `run_config.sandbox.session`，该实时沙盒会话会被直接复用。 -2. 否则，如果运行正在从 `RunState` 恢复，则恢复已存储的沙盒会话状态。 -3. 否则，如果你传入 `run_config.sandbox.session_state`，runner 会从该显式序列化沙盒会话状态恢复。 -4. 否则，runner 会创建一个全新的沙盒会话。对于该全新会话，如果提供了 `run_config.sandbox.manifest`，则使用它；否则使用 `agent.default_manifest`。 +1. 如果你注入`run_config.sandbox.session`，会直接重用该活动沙盒会话。 +2. 否则，如果本次运行是从`RunState`恢复，则恢复已存储的沙盒会话状态。 +3. 否则，如果你传入`run_config.sandbox.session_state`，运行器会从该显式序列化的沙盒会话状态恢复。 +4. 否则，运行器会创建全新沙盒会话。对于该全新会话，如果提供了`run_config.sandbox.manifest`，则使用它；否则使用`agent.default_manifest`。 -### 全新会话输入 +### 新会话输入 -这些选项只在 runner 创建全新沙盒会话时生效： +这些选项仅在运行器创建全新沙盒会话时才有意义：
| 选项 | 使用时机 | 备注 | | --- | --- | --- | -| `manifest` | 你想要一次性的全新会话工作区覆盖。 | 省略时回退到 `agent.default_manifest`。 | -| `snapshot` | 全新沙盒会话应从快照提供种子。 | 对类似恢复的流程或远程快照客户端很有用。 | -| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时和类似的客户端专用设置。 | +| `manifest` | 你想要一次性覆盖新会话工作区。 | 省略时回退到`agent.default_manifest`。 | +| `snapshot` | 全新沙盒会话应从快照设定初始状态。 | 对类似恢复的流程或远程快照客户端很有用。 | +| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时以及类似的客户端特定设置。 |
### 物化控制 -`concurrency_limits` 控制可并行运行的沙盒物化工作量。当大型 manifest 或本地目录复制需要更严格资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用对应限制。 +`concurrency_limits`控制可以并行运行多少沙盒物化工作。当大型清单或本地目录复制需要更严格的资源控制时，使用`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设置为`None`可禁用该特定限制。 -`archive_limits` 控制 SDK 侧归档解压资源检查。设置 `archive_limits=SandboxArchiveLimits()` 可启用 SDK 默认阈值；当归档需要更严格资源控制时，可传入显式值，如 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)`。保留 `archive_limits=None` 会保持无 SDK 归档资源限制的默认行为；或将单个字段设为 `None` 以仅禁用该限制。 +`archive_limits`控制归档提取的 SDK 侧资源检查。设置`archive_limits=SandboxArchiveLimits()`可启用 SDK 默认阈值；当归档需要更严格的资源控制时，也可以传入显式值，例如`SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)`。保留`archive_limits=None`可保持默认行为，即不设置 SDK 归档资源限制；或将单个字段设置为`None`，仅禁用该限制。 -有几个影响值得注意： +有几点影响值得注意： -- 全新会话：`manifest=` 和 `snapshot=` 仅在 runner 创建全新沙盒会话时适用。 -- 恢复与快照：`session_state=` 重新连接到先前序列化的沙盒状态，而 `snapshot=` 从已保存工作区内容为新的沙盒会话提供种子。 -- 客户端专用选项：`options=` 取决于沙盒客户端；Docker 和许多托管客户端都需要它。 -- 注入的实时会话：如果你传入正在运行的沙盒 `session`，由能力驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。 -- Runner API：`SandboxAgent` 执行仍使用常规 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。 +- 全新会话：`manifest=`和`snapshot=`仅在运行器创建全新沙盒会话时适用。 +- 恢复与快照：`session_state=`会重新连接到先前序列化的沙盒状态，而`snapshot=`会使用已保存的工作区内容为新沙盒会话设定初始状态。 +- 客户端特定选项：`options=`取决于沙盒客户端；Docker 和许多托管客户端都需要它。 +- 注入的活动会话：如果传入正在运行的沙盒`session`，能力驱动的清单更新可以添加兼容的非挂载条目。它们不能更改`manifest.root`、`manifest.environment`、`manifest.users`或`manifest.groups`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。 +- 运行器 API：`SandboxAgent`执行仍使用常规`Runner.run()`、`Runner.run_sync()`和`Runner.run_streamed()` API。 ## 完整示例：编码任务 @@ -576,19 +576,19 @@ if __name__ == "__main__": ) ``` -请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的仓库，因此该示例可以在 Unix 本地运行中确定性验证。你的真实任务仓库当然可以是 Python、JavaScript 或其他任何内容。 +请参阅[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的仓库，因此该示例可以在 Unix 本地运行中以确定性方式验证。你的真实任务仓库当然可以是 Python、JavaScript 或其他任何内容。 ## 常见模式 -从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，只改变沙盒客户端、沙盒会话来源或工作区来源。 +从上面的完整示例开始。在许多情况下，同一个`SandboxAgent`可以保持不变，而只改变沙盒客户端、沙盒会话来源或工作区来源。 -### 切换沙盒客户端 +### 沙盒客户端切换 -保持智能体定义不变，只更改运行配置。当你需要容器隔离或镜像一致性时使用 Docker；当你需要由提供商管理的执行环境时使用托管提供商。示例和提供商选项请参阅 [沙盒客户端](clients.md)。 +保持智能体定义不变，只更改运行配置。当你需要容器隔离或镜像一致性时使用 Docker；当你希望由提供方管理执行环境时使用托管提供方。有关示例和提供方选项，请参阅[沙盒客户端](clients.md)。 -### 覆盖工作区 +### 工作区覆盖 -保持智能体定义不变，只替换全新会话 manifest： +保持智能体定义不变，只替换新会话清单： ```python from agents.run import RunConfig @@ -608,11 +608,11 @@ run_config = RunConfig( ) ``` -当同一智能体角色需要针对不同仓库、材料包或任务包运行，而无需重新构建智能体时，请使用此模式。上面经过验证的编码示例展示了相同模式，只是使用 `default_manifest` 而不是一次性覆盖。 +当同一个智能体角色应针对不同仓库、材料包或任务包运行，而无需重建智能体时，使用此模式。上面经过验证的编码示例展示了相同模式，但使用的是`default_manifest`而不是一次性覆盖。 -### 注入沙盒会话 +### 沙盒会话注入 -当你需要显式生命周期控制、运行后检查或输出复制时，注入实时沙盒会话： +当你需要显式生命周期控制、运行后检查或输出复制时，注入活动沙盒会话： ```python from agents import Runner @@ -633,11 +633,11 @@ async with sandbox: ) ``` -当你想在运行后检查工作区，或对已启动的沙盒会话进行流式传输时，请使用此模式。请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。 +当你想在运行后检查工作区，或在已经启动的沙盒会话上进行流式传输时，使用此模式。请参阅[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)和[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。 ### 从会话状态恢复 -如果你已经在 `RunState` 外部序列化了沙盒状态，可让 runner 从该状态重新连接： +如果你已经在`RunState`之外序列化了沙盒状态，请让运行器从该状态重新连接： ```python from agents.run import RunConfig @@ -654,11 +654,11 @@ run_config = RunConfig( ) ``` -当沙盒状态存在于你自己的存储或作业系统中，并且你想让 `Runner` 直接从中恢复时，请使用此模式。序列化/反序列化流程请参阅 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。 +当沙盒状态位于你自己的存储或作业系统中，并且你希望`Runner`直接从中恢复时，使用此模式。有关序列化/反序列化流程，请参阅[examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。 ### 从快照开始 -从已保存文件和产物为新沙盒提供种子： +使用已保存的文件和工件为新沙盒设定初始状态： ```python from pathlib import Path @@ -675,11 +675,11 @@ run_config = RunConfig( ) ``` -当全新运行应从已保存工作区内容开始，而不仅仅是 `agent.default_manifest` 时，请使用此模式。本地快照流程请参阅 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)，远程快照客户端请参阅 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。 +当全新运行应从已保存的工作区内容开始，而不仅仅是从`agent.default_manifest`开始时，使用此模式。有关本地快照流程，请参阅[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)；有关远程快照客户端，请参阅[examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。 ### 从 Git 加载技能 -将本地技能来源替换为由仓库支持的来源： +将本地技能源替换为基于仓库的技能源： ```python from agents.sandbox.capabilities import Capabilities, Skills @@ -690,11 +690,11 @@ capabilities = Capabilities.default() + [ ] ``` -当技能包有自己的发布节奏，或应在多个沙盒之间共享时，请使用此模式。请参阅 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。 +当技能包有自己的发布节奏，或应在多个沙盒之间共享时，使用此模式。请参阅[examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。 -### 暴露为工具 +### 作为工具公开 -工具智能体可以拥有自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对于快速只读探索者智能体很有用：它可以检查父级正在使用的确切工作区，而无需付出创建、水合或快照另一个沙盒的成本。 +工具智能体可以拥有自己的沙盒边界，也可以重用父运行中的活动沙盒。重用对于快速只读的探索智能体很有用：它可以检查父智能体正在使用的确切工作区，而无需为创建、填充或快照另一个沙盒付出成本。 ```python from agents import Runner @@ -776,9 +776,9 @@ async with sandbox: ) ``` -这里父智能体以 `coordinator` 身份运行，探索者工具智能体在同一个实时沙盒会话中以 `explorer` 身份运行。`pricing_packet/` 条目可由 `other` 用户读取，因此探索者可以快速检查它们，但它没有写入位。`work/` 目录仅对协调者的用户/组可用，因此父级可以写入最终产物，而探索者保持只读。 +这里父智能体以`coordinator`身份运行，探索工具智能体以`explorer`身份在同一个活动沙盒会话内运行。`pricing_packet/`条目对`other`用户可读，因此探索者可以快速检查它们，但它没有写入位。`work/`目录仅对协调者的用户/组可用，因此父智能体可以写入最终工件，而探索者保持只读。 -当工具智能体需要真正隔离时，请为它提供自己的沙盒 `RunConfig`： +当工具智能体需要真正隔离时，请为它提供自己的沙盒`RunConfig`： ```python from docker import from_env as docker_from_env @@ -799,11 +799,11 @@ rollout_agent.as_tool( ) ``` -当工具智能体应自由变更、运行不受信任命令，或使用不同后端/镜像时，请使用单独的沙盒。请参阅 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 +当工具智能体应自由修改、运行不可信命令或使用不同后端/镜像时，使用单独的沙盒。请参阅[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 ### 与本地工具和 MCP 结合 -保留沙盒工作区，同时仍在同一个智能体上使用普通工具： +在保留沙盒工作区的同时，仍在同一个智能体上使用普通工具： ```python from agents.sandbox import SandboxAgent @@ -818,42 +818,42 @@ agent = SandboxAgent( ) ``` -当工作区检查只是智能体工作的一部分时，请使用此模式。请参阅 [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。 +当工作区检查只是智能体工作的一部分时，使用此模式。请参阅[examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。 ## 记忆 -当未来的沙盒智能体运行应从先前运行中学习时，请使用 `Memory` 能力。记忆与 SDK 的对话式 `Session` 记忆是分开的：它会将经验提炼为沙盒工作区内的文件，然后后续运行可以读取这些文件。 +当未来的沙盒智能体运行应从先前运行中学习时，使用`Memory`能力。记忆不同于 SDK 的对话式`Session`记忆：它会将经验提炼到沙盒工作区内的文件中，后续运行便可以读取这些文件。 -有关设置、读取/生成行为、多轮对话和布局隔离，请参阅 [智能体记忆](memory.md)。 +有关设置、读取/生成行为、多轮对话和布局隔离，请参阅[智能体记忆](memory.md)。 ## 组合模式 -当单智能体模式清晰后，下一个设计问题是在更大系统中沙盒边界应位于哪里。 +当单智能体模式清晰后，下一个设计问题是在更大系统中沙盒边界应位于何处。 沙盒智能体仍可与 SDK 的其余部分组合： -- [任务转移](../handoffs.md)：将文档密集型工作从非沙盒接收智能体移交给沙盒审阅者。 -- [Agents as tools](../tools.md#agents-as-tools)：将多个沙盒智能体暴露为工具，通常是在每个 `Agent.as_tool(...)` 调用中传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具拥有自己的沙盒边界。 -- [MCP](../mcp.md) 和常规工具调用：沙盒能力可以与 `mcp_servers` 和普通 Python 工具共存。 -- [运行智能体](../running_agents.md)：沙盒运行仍使用常规 `Runner` API。 +- [任务转移](../handoffs.md)：将文档密集型工作从非沙盒接收智能体转交给沙盒审阅者。 +- [Agents as tools](../tools.md#agents-as-tools)：将多个沙盒智能体公开为工具，通常是在每次`Agent.as_tool(...)`调用时传入`run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具都有自己的沙盒边界。 +- [MCP](../mcp.md)和普通工具调用：沙盒能力可以与`mcp_servers`和普通 Python 工具共存。 +- [智能体运行](../running_agents.md)：沙盒运行仍使用常规`Runner` API。 -两种模式尤其常见： +有两种模式尤其常见： - 非沙盒智能体仅在工作流中需要工作区隔离的部分任务转移给沙盒智能体 -- 编排器将多个沙盒智能体暴露为工具，通常为每个 `Agent.as_tool(...)` 调用配置单独的沙盒 `RunConfig`，以便每个工具拥有自己的隔离工作区 +- 编排器将多个沙盒智能体公开为工具，通常为每次`Agent.as_tool(...)`调用使用单独的沙盒`RunConfig`，以便每个工具都有自己的隔离工作区 -### Turn 和沙盒运行 +### 回合与沙盒运行 -分别解释任务转移和 agent-as-tool 调用会更容易理解。 +分别解释任务转移和智能体作为工具调用会更清晰。 -使用任务转移时，仍然只有一个顶层运行和一个顶层 turn 循环。活动智能体会改变，但运行不会变成嵌套。如果非沙盒接收智能体任务转移给沙盒审阅者，同一运行中的下一次模型调用会为沙盒智能体准备，而该沙盒智能体将成为执行下一 turn 的智能体。换句话说，任务转移会改变同一运行中下一个 turn 由哪个智能体拥有。请参阅 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。 +对于任务转移，仍然只有一个顶层运行和一个顶层回合循环。活动智能体会改变，但运行不会变成嵌套运行。如果非沙盒接收智能体任务转移给沙盒审阅者，同一次运行中的下一次模型调用会为沙盒智能体准备，该沙盒智能体也会成为执行下一回合的智能体。换言之，任务转移会改变同一次运行中由哪个智能体拥有下一回合。请参阅[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。 -使用 `Agent.as_tool(...)` 时，关系则不同。外层编排器使用一个外层 turn 来决定调用该工具，而该工具调用会为沙盒智能体启动一个嵌套运行。嵌套运行拥有自己的 turn 循环、`max_turns`、审批，并且通常拥有自己的沙盒 `RunConfig`。它可能在一个嵌套 turn 中完成，也可能需要多个。从外层编排器的角度看，所有这些工作仍位于一次工具调用之后，因此嵌套 turn 不会增加外层运行的 turn 计数器。请参阅 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 +对于`Agent.as_tool(...)`，关系则不同。外层编排器使用一个外层回合来决定调用该工具，而该工具调用会为沙盒智能体启动一个嵌套运行。嵌套运行拥有自己的回合循环、`max_turns`、审批，并且通常拥有自己的沙盒`RunConfig`。它可能在一个嵌套回合中完成，也可能需要多个回合。从外层编排器的角度看，所有这些工作仍然都位于一次工具调用之后，因此嵌套回合不会增加外层运行的回合计数器。请参阅[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。 -审批行为遵循相同的分离： +审批行为遵循同样的分工： -- 使用任务转移时，审批留在同一个顶层运行中，因为沙盒智能体现在是该运行中的活动智能体 -- 使用 `Agent.as_tool(...)` 时，在沙盒工具智能体内部引发的审批仍会浮现在外层运行上，但它们来自已存储的嵌套运行状态，并在外层运行恢复时恢复嵌套沙盒运行 +- 在任务转移中，审批保留在同一个顶层运行上，因为沙盒智能体现在是该运行中的活动智能体 +- 在`Agent.as_tool(...)`中，沙盒工具智能体内部发起的审批仍会呈现在外层运行上，但它们来自已存储的嵌套运行状态，并在外层运行恢复时恢复该嵌套沙盒运行 ## 延伸阅读 diff --git a/docs/zh/sandbox/memory.md b/docs/zh/sandbox/memory.md index 3e29fb5c26..8df63cd7a4 100644 --- a/docs/zh/sandbox/memory.md +++ b/docs/zh/sandbox/memory.md @@ -4,23 +4,23 @@ search: --- # 智能体记忆 -记忆让未来的 sandbox-agent 运行能够从先前的运行中学习。它独立于 SDK 的对话式[`Session`](../sessions/index.md)记忆，后者存储的是消息历史。记忆会将先前运行中的经验提炼为 sandbox 工作区中的文件。 +记忆让未来的沙盒智能体运行能够从先前运行中学习。它与 SDK 的对话式 [`Session`](../sessions/index.md) 记忆分开，后者用于存储消息历史。记忆会将先前运行中的经验提炼为沙盒工作区中的文件。 !!! warning "Beta 功能" - Sandbox 智能体目前处于 beta 阶段。预计在正式可用之前，API 的细节、默认值和支持的能力都会发生变化，并且功能也会随着时间推移变得更高级。 + 沙盒智能体处于 Beta 阶段。在正式可用之前，API、默认值和支持能力的细节可能会发生变化，并且随着时间推移会提供更高级的功能。 -记忆可以降低未来运行中的三类成本： +记忆可以为未来运行降低三类成本： -1. 智能体成本：如果智能体完成某个工作流花了很长时间，那么下一次运行应当需要更少的探索。这可以减少 token 使用量并缩短完成时间。 -2. 用户成本：如果用户纠正了智能体或表达了偏好，未来的运行可以记住这些反馈。这可以减少人工干预。 -3. 上下文成本：如果智能体之前完成过某项任务，而用户希望在该任务基础上继续推进，那么用户不需要去查找之前的线程，也不需要重新输入全部上下文。这会让任务描述更简短。 +1. 智能体成本：如果智能体花了很长时间才完成某个工作流，下一次运行应该需要更少探索。这可以减少 token 使用量和完成时间。 +2. 用户成本：如果用户纠正了智能体，或表达了偏好，未来运行可以记住这些反馈。这可以减少人工干预。 +3. 上下文成本：如果智能体之前完成过一项任务，而用户想在该任务基础上继续推进，用户就不需要找到之前的线程或重新输入全部上下文。这会让任务描述更短。 -参见[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)，查看一个完整的双次运行示例：修复一个 bug、生成记忆、恢复一个快照，并在后续验证器运行中使用该记忆。另请参见[examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)，查看一个包含独立记忆布局的多轮、多智能体示例。 +请参阅 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)，其中包含一个完整的两次运行代码示例：修复 bug、生成记忆、恢复快照，并在后续验证器运行中使用该记忆。请参阅 [examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)，了解一个多轮、多智能体示例，其中包含独立的记忆布局。 -## 启用记忆 +## 记忆启用 -将 `Memory()` 作为一种能力添加到 sandbox 智能体中。 +将 `Memory()` 作为一项能力添加到沙盒智能体。 ```python from pathlib import Path @@ -42,30 +42,30 @@ with tempfile.TemporaryDirectory(prefix="sandbox-memory-example-") as snapshot_d ) ``` -如果启用了读取，`Memory()` 需要 `Shell()`，这样智能体就可以在注入的摘要不足时读取和搜索记忆文件。当启用实时记忆更新时（默认启用），它还需要 `Filesystem()`，这样如果智能体发现记忆已过时，或者用户要求它更新记忆，它就可以更新 `memories/MEMORY.md`。 +如果启用了读取，`Memory()` 需要 `Shell()`，这样当注入的摘要不足够时，智能体就可以读取和搜索记忆文件。当启用实时记忆更新时（默认启用），它还需要 `Filesystem()`，这样如果智能体发现记忆已过时，或用户要求它更新记忆，智能体就可以更新 `memories/MEMORY.md`。 -默认情况下，记忆产物存储在 sandbox 工作区的 `memories/` 下。若要在后续运行中复用它们，请通过保持相同的实时 sandbox 会话，或从持久化的会话状态或快照中恢复，来保留并复用整个已配置的记忆目录；一个全新的空 sandbox 会以空记忆启动。 +默认情况下，记忆产物存储在沙盒工作区的 `memories/` 下。要在后续运行中复用它们，请通过保持同一个实时沙盒会话，或从持久化的会话状态或快照恢复，来保留并复用整个已配置的记忆目录；全新的空沙盒会从空记忆开始。 -`Memory()` 同时启用记忆读取和记忆生成。对于应当读取记忆但不应生成新记忆的智能体，请使用 `Memory(generate=None)`：例如内部智能体、子智能体、检查器，或一次性工具智能体，因为它们的运行不会增加太多有效信号。当某次运行应为后续生成记忆，但用户不希望该运行受现有记忆影响时，请使用 `Memory(read=None)`。 +`Memory()` 同时启用读取记忆和生成记忆。对于应该读取记忆但不应生成新记忆的智能体，请使用 `Memory(generate=None)`：例如，内部智能体、子智能体、检查器，或运行不会增加太多信号的一次性工具智能体。当运行应该为之后生成记忆，但用户不希望该运行受现有记忆影响时，请使用 `Memory(read=None)`。 -## 读取记忆 +## 记忆读取 -记忆读取采用渐进式披露。在一次运行开始时，SDK 会将一个简短摘要（`memory_summary.md`）注入到智能体的开发者提示词中，其中包含通常有用的提示、用户偏好以及可用记忆。这为智能体提供了足够的上下文，以判断先前工作是否可能相关。 +记忆读取采用渐进式披露。在运行开始时，SDK 会将一份小型摘要（`memory_summary.md`）注入到智能体的开发者提示词中，其中包含通常有用的提示、用户偏好和可用记忆。这会为智能体提供足够的上下文，以判断先前工作是否可能相关。 -当先前工作看起来相关时，智能体会在已配置的记忆索引（`memories_dir` 下的 `MEMORY.md`）中搜索与当前任务相关的关键词。只有当任务需要更多细节时，它才会打开已配置 `rollout_summaries/` 目录下对应的先前 rollout 摘要。 +当先前工作看起来相关时，智能体会在已配置的记忆索引（`memories_dir` 下的 `MEMORY.md`）中搜索当前任务的关键词。只有当任务需要更多细节时，它才会打开已配置的 `rollout_summaries/` 目录下对应的先前 rollout 摘要。 -记忆可能会过时。系统会指示智能体仅将记忆视为参考，并以当前环境为准。默认情况下，记忆读取启用了 `live_update`，因此如果智能体发现记忆已过时，它可以在同一次运行中更新已配置的 `MEMORY.md`。如果某次运行对延迟敏感，而你希望智能体读取记忆但不要在运行期间修改它，请禁用实时更新。 +记忆可能会过时。智能体会被指示仅将记忆作为指导，并信任当前环境。默认情况下，记忆读取启用 `live_update`，因此如果智能体发现记忆已过时，它可以在同一次运行中更新已配置的 `MEMORY.md`。当智能体应读取记忆但不应在运行期间修改记忆时，请禁用实时更新，例如该运行对延迟敏感时。 -## 生成记忆 +## 记忆生成 -一次运行结束后，sandbox 运行时会将该运行片段追加到一个对话文件中。累积的对话文件会在 sandbox 会话关闭时被处理。 +运行结束后，沙盒运行时会将该运行片段追加到一个对话文件中。累积的对话文件会在沙盒会话关闭时被处理。 -记忆生成包含两个阶段： +记忆生成分为两个阶段： -1. 阶段 1：对话提取。一个生成记忆的模型会处理一个累积的对话文件，并生成对话摘要。系统、开发者和推理内容会被省略。如果对话过长，它会被截断以适应上下文窗口，同时保留开头和结尾。它还会生成原始记忆提取：从对话中提炼出的紧凑笔记，供阶段 2 进行整合。 -2. 阶段 2：布局整合。一个整合智能体会读取某个记忆布局下的原始记忆，在需要更多证据时打开对话摘要，并将模式提取到 `MEMORY.md` 和 `memory_summary.md` 中。 +1. 阶段 1：对话提取。生成记忆的模型会处理一个累积的对话文件，并生成对话摘要。system、developer 和 reasoning 内容会被省略。如果对话过长，它会被截断以适配上下文窗口，同时保留开头和结尾。它还会生成原始记忆摘录：来自对话的紧凑笔记，供阶段 2 进行整合。 +2. 阶段 2：布局整合。整合智能体会读取某个记忆布局的原始记忆，在需要更多证据时打开对话摘要，并将模式提取到 `MEMORY.md` 和 `memory_summary.md` 中。 -默认工作区布局为： +默认工作区布局如下： ```text workspace/ @@ -97,13 +97,13 @@ memory = Memory( ) ``` -使用 `extra_prompt` 告诉记忆生成器，哪些信号对你的使用场景最重要，例如 GTM 智能体中的客户和公司细节。 +使用 `extra_prompt` 告诉记忆生成器哪些信号对你的用例最重要，例如 GTM 智能体所需的客户和公司详细信息。 -如果最近的原始记忆超过 `max_raw_memories_for_consolidation`（默认为 256），阶段 2 将只保留最新对话中的记忆并移除较旧的记忆。新旧判断基于对话最后一次更新时间。这个遗忘机制有助于让记忆反映最新的环境。 +如果最近的原始记忆超过 `max_raw_memories_for_consolidation`（默认为 256），阶段 2 只保留来自最新对话的记忆，并移除较旧的记忆。新近程度基于对话上次更新的时间。这种遗忘机制有助于让记忆反映最新环境。 ## 多轮对话 -对于多轮 sandbox 聊天，请将普通 SDK `Session` 与同一个实时 sandbox 会话一起使用： +对于多轮沙盒聊天，请将常规 SDK `Session` 与同一个实时沙盒会话一起使用： ```python from agents import Runner, SQLiteSession @@ -132,20 +132,20 @@ async with sandbox: ) ``` -两次运行都会追加到同一个记忆对话文件中，因为它们传入了同一个 SDK 对话会话（`session=conversation_session`），因此共享同一个 `session.session_id`。这与 sandbox（`sandbox`）不同，后者标识的是实时工作区，不会被用作记忆对话 ID。阶段 1 会在 sandbox 会话关闭时看到累积后的对话，因此它可以从整个交互中提取记忆，而不是从两个彼此孤立的轮次中提取。 +两次运行都会追加到同一个记忆对话文件，因为它们传入了同一个 SDK 对话会话（`session=conversation_session`），因此共享同一个 `session.session_id`。这不同于沙盒（`sandbox`），后者标识实时工作区，不会被用作记忆对话 ID。阶段 1 会在沙盒会话关闭时看到累积的对话，因此它可以从整个交流中提取记忆，而不是从两个孤立的轮次中提取。 -如果你希望多次 `Runner.run(...)` 调用成为同一个记忆对话，请在这些调用之间传递一个稳定标识符。当记忆将某次运行关联到某个对话时，会按以下顺序解析： +如果你希望多个 `Runner.run(...)` 调用成为同一个记忆对话，请在这些调用之间传入一个稳定标识符。当记忆将某次运行与一个对话关联时，它会按以下顺序解析： 1. `conversation_id`，当你将其传给 `Runner.run(...)` 时 2. `session.session_id`，当你传入 SDK `Session`（例如 `SQLiteSession`）时 -3. `RunConfig.group_id`，当以上两者都不存在时 -4. 每次运行生成的 ID，当不存在稳定标识符时 +3. `RunConfig.group_id`，当上述两者都不存在时 +4. 生成的每次运行 ID，当不存在稳定标识符时 -## 使用不同布局隔离不同智能体的记忆 +## 用于隔离不同智能体记忆的不同布局 -记忆隔离基于 `MemoryLayoutConfig`，而不是智能体名称。具有相同布局且相同记忆对话 ID 的智能体会共享同一个记忆对话和同一份整合后的记忆。布局不同的智能体则会保留各自独立的 rollout 文件、原始记忆、`MEMORY.md` 和 `memory_summary.md`，即使它们共享同一个 sandbox 工作区也是如此。 +记忆隔离基于 `MemoryLayoutConfig`，而不是智能体名称。具有相同布局和相同记忆对话 ID 的智能体会共享一个记忆对话和一份整合后的记忆。具有不同布局的智能体会保留独立的 rollout 文件、原始记忆、`MEMORY.md` 和 `memory_summary.md`，即使它们共享同一个沙盒工作区也是如此。 -当多个智能体共享一个 sandbox，但不应共享记忆时，请使用独立布局： +当多个智能体共享一个沙盒但不应共享记忆时，请使用独立布局： ```python from agents import SQLiteSession @@ -186,4 +186,4 @@ gtm_session = SQLiteSession("gtm-q2-pipeline-review") engineering_session = SQLiteSession("eng-invoice-test-fix") ``` -这样可以防止 GTM 分析被整合到工程 bug 修复记忆中，反之亦然。 \ No newline at end of file +这可以防止 GTM 分析被整合到工程缺陷修复记忆中，反之亦然。 \ No newline at end of file diff --git a/docs/zh/sandbox_agents.md b/docs/zh/sandbox_agents.md index a04242a820..227d3f8a2b 100644 --- a/docs/zh/sandbox_agents.md +++ b/docs/zh/sandbox_agents.md @@ -6,11 +6,11 @@ search: !!! warning "Beta 功能" - 沙盒智能体处于 beta 阶段。在正式发布前，API、默认值和支持能力的细节可能会变化，并且后续会逐步加入更多高级功能。 + 沙盒智能体仍处于 Beta 阶段。在正式发布前，API、默认设置和支持的能力细节可能会发生变化；未来也会逐步提供更高级的功能。 -当现代智能体能够在文件系统中的真实文件上操作时，效果最好。Agents SDK 中的**沙盒智能体**为模型提供了一个持久化工作区，使其可以搜索大型文档集、编辑文件、运行命令、生成产物，并从已保存的沙盒状态继续工作。 +现代智能体在能够操作文件系统中的真实文件时效果最佳。Agents SDK 中的**沙盒智能体**为模型提供了一个持久工作区，使其可以检索大型文档集、编辑文件、运行命令、生成产物，并从已保存的沙盒状态继续工作。 -SDK 为你提供了这套执行框架，无需你自行拼接文件暂存、文件系统工具、shell 访问、沙盒生命周期、快照以及特定提供商的胶水代码。你可以保留常规的 `Agent` 和 `Runner` 流程，然后为工作区添加 `Manifest`，为沙盒原生工具添加 capabilities，并用 `SandboxRunConfig` 指定工作运行的位置。 +SDK 为你提供了这一执行框架，而无需你自行串接文件暂存、文件系统工具、shell 访问、沙盒生命周期、快照以及特定提供商的粘合代码。你可以保留常规的 `Agent` 和 `Runner` 流程，然后为工作区添加 `Manifest`，为沙盒原生工具添加能力，并通过 `SandboxRunConfig` 指定工作运行的位置。 ## 前提条件 @@ -26,15 +26,15 @@ SDK 为你提供了这套执行框架，无需你自行拼接文件暂存、文 pip install openai-agents ``` -对于 Docker 支持的沙盒： +对于由 Docker 支持的沙盒： ```bash pip install "openai-agents[docker]" ``` -## 创建本地沙盒智能体 +## 本地沙盒智能体的创建 -此示例会将本地仓库暂存在 `repo/` 下，延迟加载本地 skills，并让 runner 为本次运行创建 Unix 本地沙盒会话。 +此示例会将本地 repo 暂存到 `repo/` 下，惰性加载本地技能，并让运行器为本次运行创建一个 Unix 本地沙盒会话。 ```python import asyncio @@ -94,24 +94,24 @@ if __name__ == "__main__": asyncio.run(main()) ``` -请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的仓库，因此可以在 Unix 本地运行中以确定性的方式验证该示例。 +参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的 repo，因此该示例可以在 Unix 本地运行中以确定性的方式验证。 ## 关键选择 -基本运行正常后，大多数人接下来会关注的选择包括： +在基本运行可用后，大多数人接下来会关注的选择包括： -- `default_manifest`：用于全新沙盒会话的文件、仓库、目录和挂载 -- `instructions`：应在各个提示中适用的简短工作流规则 -- `base_instructions`：用于替换 SDK 沙盒提示词的高级逃生舱 -- `capabilities`：沙盒原生工具，例如文件系统编辑/图像检查、shell、skills、memory 和 compaction +- `default_manifest`：用于新沙盒会话的文件、repo、目录和挂载 +- `instructions`：应跨提示词生效的简短工作流规则 +- `base_instructions`：用于替换 SDK 沙盒提示词的高级逃生口 +- `capabilities`：沙盒原生工具，例如文件系统编辑/图像检查、shell、技能、内存和压缩 - `run_as`：面向模型的工具所使用的沙盒用户身份 - `SandboxRunConfig.client`：沙盒后端 -- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到之前的工作 +- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到先前的工作 -## 后续内容 +## 后续方向 -- [概念](sandbox/guide.md)：了解 manifest、capabilities、权限、快照、运行配置和组合模式。 -- [沙盒客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供商和挂载策略。 -- [智能体记忆](sandbox/memory.md)：保留并复用此前沙盒运行中的经验。 +- [概念](sandbox/guide.md)：了解 manifest、能力、权限、快照、运行配置和组合模式。 +- [沙盒客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供商以及挂载策略。 +- [智能体内存](sandbox/memory.md)：保留并复用以往沙盒运行中的经验。 -如果 shell 访问只是偶尔使用的工具，请从[工具指南](tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。 \ No newline at end of file +如果 shell 访问只是偶尔使用的工具，请从[工具指南](tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，再选择沙盒智能体。 \ No newline at end of file diff --git a/docs/zh/sessions/advanced_sqlite_session.md b/docs/zh/sessions/advanced_sqlite_session.md index dbc7b6c97e..70c42a86f2 100644 --- a/docs/zh/sessions/advanced_sqlite_session.md +++ b/docs/zh/sessions/advanced_sqlite_session.md @@ -4,15 +4,15 @@ search: --- # 高级 SQLite 会话 -`AdvancedSQLiteSession` 是基础 `SQLiteSession` 的增强版本，提供高级对话管理能力，包括对话分支、详细用量分析和结构化对话查询。 +`AdvancedSQLiteSession` 是基础 `SQLiteSession` 的增强版本，提供高级对话管理能力，包括对话分支、详细的使用情况分析以及结构化对话查询。 ## 功能 -- **对话分支**：可从任意用户消息创建替代对话路径 -- **用量追踪**：按轮次提供详细的 token 用量分析，并包含完整 JSON 明细 -- **结构化查询**：可按轮次获取对话、工具使用统计等信息 +- **对话分支**：从任意用户消息创建替代对话路径 +- **使用情况追踪**：按轮次提供详细的 token 使用情况分析，并包含完整的 JSON 明细 +- **结构化查询**：按轮次获取对话、工具使用统计等 - **分支管理**：独立的分支切换与管理 -- **消息结构元数据**：追踪消息类型、工具使用情况和对话流 +- **消息结构元数据**：跟踪消息类型、工具使用情况和对话流程 ## 快速开始 @@ -84,16 +84,16 @@ session = AdvancedSQLiteSession( ### 参数 -- `session_id` (str)：会话的唯一标识符 -- `db_path` (str | Path)：SQLite 数据库文件路径。默认为 `:memory:`（内存存储） +- `session_id` (str)：对话会话的唯一标识符 +- `db_path` (str | Path)：SQLite 数据库文件路径。默认为 `:memory:`，用于内存存储 - `create_tables` (bool)：是否自动创建高级表。默认为 `False` -- `logger` (logging.Logger | None)：会话的自定义日志记录器。默认为模块日志记录器 +- `logger` (logging.Logger | None)：用于会话的自定义日志记录器。默认为模块日志记录器 -## 用量追踪 +## 使用情况追踪 -AdvancedSQLiteSession 通过按对话轮次存储 token 用量数据来提供详细的用量分析。**这完全依赖于在每次智能体运行后调用 `store_run_usage` 方法。** +AdvancedSQLiteSession 通过按对话轮次存储 token 使用情况数据，提供详细的使用情况分析。**这完全依赖于在每次智能体运行后调用 `store_run_usage` 方法。** -### 存储用量数据 +### 使用情况数据存储 ```python # After each agent run, store the usage data @@ -107,7 +107,7 @@ await session.store_run_usage(result) # - Detailed JSON token information (if available) ``` -### 获取用量统计 +### 使用情况统计检索 ```python # Get session-level usage (all branches) @@ -137,9 +137,9 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2) ## 对话分支 -AdvancedSQLiteSession 的核心功能之一是能够从任意用户消息创建对话分支，让你可以探索替代性的对话路径。 +AdvancedSQLiteSession 的关键功能之一是能够从任意用户消息创建对话分支，从而让你探索替代的对话路径。 -### 创建分支 +### 分支创建 ```python # Get available turns for branching @@ -217,7 +217,7 @@ await session.store_run_usage(result) ## 结构化查询 -AdvancedSQLiteSession 提供了多种方法来分析对话结构和内容。 +AdvancedSQLiteSession 提供了多种方法，用于分析对话结构和内容。 ### 对话分析 @@ -245,17 +245,17 @@ for turn in matching_turns: ### 消息结构 -会话会自动追踪消息结构，包括： +会话会自动跟踪消息结构，包括： -- 消息类型（user、assistant、tool_call 等） +- 消息类型（用户、assistant、tool_call 等） - 工具调用的工具名称 -- 轮次编号与序列编号 +- 轮次编号和序列号 - 分支关联 - 时间戳 ## 数据库架构 -AdvancedSQLiteSession 在基础 SQLite 架构上扩展了两个附加表： +AdvancedSQLiteSession 在基础 SQLite 架构之上扩展了两个额外的表： ### message_structure 表 @@ -298,7 +298,7 @@ CREATE TABLE turn_usage ( ## 完整示例 -查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，了解所有功能的完整演示。 +查看[完整示例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)，全面了解所有功能。 ## API 参考 diff --git a/docs/zh/sessions/encrypted_session.md b/docs/zh/sessions/encrypted_session.md index 048c27a861..210e34f1e1 100644 --- a/docs/zh/sessions/encrypted_session.md +++ b/docs/zh/sessions/encrypted_session.md @@ -4,24 +4,24 @@ search: --- # 加密会话 -`EncryptedSession`为任意会话实现提供透明加密，通过自动过期旧条目来保护对话数据。 +`EncryptedSession` 为任何会话实现提供透明加密，通过自动过期旧条目来保护对话数据。 -## 功能特性 +## 功能 -- **透明加密**：使用 Fernet 加密包装任意会话 -- **每会话密钥**：使用 HKDF 密钥派生为每个会话生成唯一加密密钥 -- **自动过期**：当 TTL 到期时，旧条目会被静默跳过 -- **即插即用替换**：可与任何现有会话实现配合使用 +- **透明加密**：使用 Fernet 加密包装任何会话 +- **每会话密钥**：使用 HKDF 密钥派生，为每个会话生成唯一加密 +- **自动过期**：TTL 过期时会静默跳过旧条目 +- **即插即用替代方案**：适用于任何现有会话实现 ## 安装 -加密会话需要 `encrypt` 扩展： +加密会话需要 `encrypt` extra： ```bash pip install openai-agents[encrypt] ``` -## 快速开始 +## 快速入门 ```python import asyncio @@ -79,9 +79,9 @@ session = EncryptedSession( ) ``` -### TTL（生存时间） +### TTL（存活时间） -设置加密条目保持有效的时长： +设置加密条目的有效时长： ```python # Items expire after 1 hour @@ -101,9 +101,9 @@ session = EncryptedSession( ) ``` -## 与不同会话类型配合使用 +## 与不同会话类型的搭配使用 -### 与 SQLite 会话配合使用 +### 与 SQLite 会话搭配使用 ```python from agents import SQLiteSession @@ -119,7 +119,7 @@ session = EncryptedSession( ) ``` -### 与 SQLAlchemy 会话配合使用 +### 与 SQLAlchemy 会话搭配使用 ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -140,30 +140,30 @@ session = EncryptedSession( !!! warning "高级会话功能" - 使用 `EncryptedSession` 与 `AdvancedSQLiteSession` 等高级会话实现时，请注意： + 将 `EncryptedSession` 与 `AdvancedSQLiteSession` 等高级会话实现一起使用时，请注意： - - 由于消息内容已加密，`find_turns_by_content()` 等方法将无法有效工作 - - 基于内容的搜索会在加密数据上执行，因此效果受限 + - 像 `find_turns_by_content()` 这样的方法无法有效工作，因为消息内容已加密 + - 基于内容的搜索会在加密数据上运行，因此效果受限 ## 密钥派生 -EncryptedSession 使用 HKDF（基于 HMAC 的密钥派生函数）为每个会话派生唯一加密密钥： +EncryptedSession 使用 HKDF（基于 HMAC 的密钥派生函数）为每个会话派生唯一的加密密钥： - **主密钥**：你提供的加密密钥 - **会话盐值**：会话 ID - **信息字符串**：`"agents.session-store.hkdf.v1"` - **输出**：32 字节 Fernet 密钥 -这可确保： +这可以确保： - 每个会话都有唯一的加密密钥 - 没有主密钥就无法派生密钥 -- 不同会话之间的数据无法相互解密 +- 不同会话之间的会话数据无法相互解密 ## 自动过期 -当条目超过 TTL 时，在检索期间会被自动跳过： +当条目超过 TTL 时，检索过程中会自动跳过它们： ```python # Items older than TTL are silently ignored diff --git a/docs/zh/sessions/index.md b/docs/zh/sessions/index.md index fb68240388..96f0d6e45b 100644 --- a/docs/zh/sessions/index.md +++ b/docs/zh/sessions/index.md @@ -4,11 +4,11 @@ search: --- # 会话 -Agents SDK 提供内置会话记忆，可在多次智能体运行之间自动维护对话历史，无需在轮次之间手动处理 `.to_input_list()`。 +Agents SDK 提供内置会话记忆，用于在多次智能体运行之间自动维护对话历史记录，从而无需在各轮之间手动处理 `.to_input_list()`。 -会话会存储特定会话的对话历史，使智能体无需显式手动管理记忆即可保持上下文。这对于构建聊天应用或多轮对话尤其有用，在这些场景中你希望智能体记住之前的交互。 +会话会存储特定会话的对话历史记录，使智能体能够维护上下文，而无需显式的手动记忆管理。这对于构建聊天应用或多轮对话尤其有用，因为你希望智能体记住之前的交互。 -当你希望 SDK 为你管理客户端侧记忆时，请使用会话。会话不能在同一次运行中与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 组合使用。如果你想使用 OpenAI 服务端托管的续接，请选择其中一种机制，而不是在其上叠加会话。 +当你希望 SDK 为你管理客户端侧记忆时，请使用会话。会话不能在同一次运行中与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 结合使用。如果你希望改用由 OpenAI 服务端管理的延续机制，请选择其中一种机制，而不是在其上叠加会话。 ## 快速开始 @@ -49,9 +49,9 @@ result = Runner.run_sync( print(result.final_output) # "Approximately 39 million" ``` -## 使用相同会话恢复中断的运行 +## 使用同一会话恢复中断的运行 -如果某次运行因等待批准而暂停，请使用相同的会话实例（或指向同一底层存储的另一个会话实例）恢复它，以便恢复后的轮次继续使用同一份已存储的对话历史。 +如果某次运行因等待批准而暂停，请使用同一个会话实例（或另一个指向同一后端存储的会话实例）来恢复它，以便恢复后的轮次继续使用同一份已存储的对话历史记录。 ```python result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session) @@ -67,27 +67,27 @@ if result.interruptions: 启用会话记忆后： -1. **每次运行前**：运行器会自动检索该会话的对话历史，并将其前置到输入项中。 -2. **每次运行后**：运行期间生成的所有新项（用户输入、助手回复、工具调用等）都会自动存储到会话中。 -3. **上下文保留**：使用同一会话的每次后续运行都会包含完整的对话历史，使智能体能够保持上下文。 +1. **每次运行之前**：运行器会自动检索该会话的对话历史记录，并将其前置到输入项中。 +2. **每次运行之后**：运行期间生成的所有新项（用户输入、助手响应、工具调用等）都会自动存储到会话中。 +3. **上下文保留**：同一会话的每次后续运行都会包含完整的对话历史记录，使智能体能够维护上下文。 -这消除了在运行之间手动调用 `.to_input_list()` 和管理对话状态的需要。 +这消除了手动调用 `.to_input_list()` 并在运行之间管理对话状态的需要。 ## 历史记录与新输入的合并控制 当你传入会话时，运行器通常会按如下方式准备模型输入： -1. 会话历史（从 `session.get_items(...)` 检索） +1. 会话历史记录（从 `session.get_items(...)` 检索） 2. 新轮次输入 -使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 在模型调用前自定义该合并步骤。回调会接收两个列表： +使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 在模型调用之前自定义该合并步骤。回调会接收两个列表： -- `history`：检索到的会话历史（已规范化为输入项格式） +- `history`：检索到的会话历史记录（已规范化为输入项格式） - `new_input`：当前轮次的新输入项 返回应发送给模型的最终输入项列表。 -回调接收的是两个列表的副本，因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入，但 SDK 仍然只持久化属于新轮次的项。因此，重新排序或过滤旧历史不会导致旧会话项被作为新的输入再次保存。 +回调接收的是这两个列表的副本，因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入，但 SDK 仍然只会持久化属于新轮次的项。因此，对旧历史记录重新排序或过滤，并不会导致旧会话项被再次作为新输入保存。 ```python from agents import Agent, RunConfig, Runner, SQLiteSession @@ -109,7 +109,7 @@ result = await Runner.run( ) ``` -当你需要自定义裁剪、重新排序或选择性纳入历史记录，同时不改变会话存储项的方式时，请使用此功能。如果你需要在模型调用前立即进行更靠后的最终处理，请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。 +当你需要自定义裁剪、重新排序或选择性纳入历史记录，同时不改变会话存储项的方式时，请使用此功能。如果你需要在模型调用前立即进行更靠后的最终处理步骤，请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。 ## 检索历史记录的限制 @@ -134,13 +134,13 @@ result = await Runner.run( ) ``` -如果你的会话实现暴露默认会话设置，`RunConfig.session_settings` 会覆盖该次运行中任何非 `None` 的值。这对于长对话很有用，你可以限制检索大小，而无需更改会话的默认行为。 +如果你的会话实现公开了默认会话设置，`RunConfig.session_settings` 会为该次运行覆盖任何非 `None` 的值。这对于长对话很有用：你可以在不改变会话默认行为的情况下限制检索大小。 ## 记忆操作 ### 基本操作 -会话支持多种用于管理对话历史的操作： +会话支持用于管理对话历史记录的多种操作： ```python from agents import SQLiteSession @@ -198,28 +198,28 @@ print(f"Agent: {result.final_output}") ## 内置会话实现 -SDK 为不同用例提供了多种会话实现： +SDK 为不同用例提供了多个会话实现： ### 内置会话实现的选择 -在阅读下面的详细示例之前，请使用此表选择一个起点。 +在阅读下方详细示例之前，使用此表选择一个起点。 -| 会话类型 | 最适合 | 备注 | +| 会话类型 | 适用场景 | 备注 | | --- | --- | --- | -| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量、基于文件或内存 | -| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 具有异步驱动支持的扩展后端 | -| `RedisSession` | 跨 worker/服务的共享记忆 | 适用于低延迟分布式部署 | +| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，可基于文件或内存 | +| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 支持异步驱动的扩展后端 | +| `RedisSession` | 跨多个工作进程/服务的共享记忆 | 适合低延迟分布式部署 | | `SQLAlchemySession` | 使用现有数据库的生产应用 | 适用于 SQLAlchemy 支持的数据库 | -| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo；用于排序的原子序列计数器 | -| `DaprSession` | 使用 Dapr sidecar 的云原生部署 | 支持多个状态存储以及 TTL 和一致性控制 | -| `OpenAIConversationsSession` | OpenAI 中的服务端托管存储 | 基于 OpenAI Conversations API 的历史记录 | -| `OpenAIResponsesCompactionSession` | 带自动压缩的长对话 | 围绕另一个会话后端的包装器 | -| `AdvancedSQLiteSession` | SQLite 加分支/分析 | 功能更丰富；请参阅专用页面 | +| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo；通过原子序列计数器保证顺序 | +| `DaprSession` | 带有 Dapr sidecar 的云原生部署 | 支持多种状态存储，以及 TTL 和一致性控制 | +| `OpenAIConversationsSession` | OpenAI 中由服务端管理的存储 | 基于 OpenAI Conversations API 的历史记录 | +| `OpenAIResponsesCompactionSession` | 带有自动压缩的长对话 | 另一个会话后端的包装器 | +| `AdvancedSQLiteSession` | SQLite 加分支/分析 | 功能集较重；请参阅专门页面 | | `EncryptedSession` | 基于另一个会话的加密 + TTL | 包装器；请先选择底层后端 | -某些实现有包含更多详细信息的专用页面；这些页面会在各自小节中以内联链接给出。 +一些实现有包含更多详细信息的专门页面；这些页面已在其小节中以内联链接形式给出。 -如果你正在为 ChatKit 实现 Python 服务，请使用 `chatkit.store.Store` 实现来持久化 ChatKit 的线程和项。诸如 `SQLAlchemySession` 的 Agents SDK 会话用于管理 SDK 侧的对话历史，但它们不能直接替代 ChatKit 的存储。请参阅 [`chatkit-python` 关于实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。 +如果你正在为 ChatKit 实现 Python 服务，请使用 `chatkit.store.Store` 实现来持久化 ChatKit 的线程和项。Agents SDK 会话（如 `SQLAlchemySession`）会管理 SDK 侧的对话历史记录，但它们不能直接替代 ChatKit 的 store。请参阅 [`chatkit-python` 关于实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。 ### OpenAI Conversations API 会话 @@ -259,7 +259,7 @@ print(result.final_output) # "California" ### OpenAI Responses 压缩会话 -使用 `OpenAIResponsesCompactionSession` 通过 Responses API（`responses.compact`）压缩已存储的对话历史。它包装底层会话，并可根据 `should_trigger_compaction` 在每个轮次后自动压缩。不要用它包装 `OpenAIConversationsSession`；这两个功能以不同方式管理历史记录。 +使用 `OpenAIResponsesCompactionSession` 通过 Responses API（`responses.compact`）压缩已存储的对话历史记录。它会包装一个底层会话，并可根据 `should_trigger_compaction` 在每轮之后自动压缩。不要用它包装 `OpenAIConversationsSession`；这两个功能以不同方式管理历史记录。 #### 典型用法（自动压缩） @@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session) print(result.final_output) ``` -默认情况下，一旦达到候选阈值，压缩会在每个轮次后运行。 +默认情况下，一旦达到候选阈值，压缩会在每轮之后运行。 -当你已经使用 Responses API 响应 ID 串联轮次时，`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 则会基于当前会话项重新构建压缩请求，这在响应链不可用，或你希望会话内容作为事实来源时很有用。默认的 `"auto"` 会选择最安全的可用选项。 +当你已经使用 Responses API 响应 ID 串联各轮时，`compaction_mode="previous_response_id"` 效果最好。`compaction_mode="input"` 则会基于当前会话项重建压缩请求，这在响应链不可用，或你希望以会话内容作为事实来源时很有用。默认的 `"auto"` 会选择可用的最安全选项。 -如果你的智能体使用 `ModelSettings(store=False)` 运行，Responses API 不会保留最后一次响应用于后续查找。在这种无状态设置中，默认的 `"auto"` 模式会回退为基于输入的压缩，而不是依赖 `previous_response_id`。完整示例请参阅 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。 +如果你的智能体使用 `ModelSettings(store=False)` 运行，Responses API 不会保留最后一个响应以供之后查找。在这种无状态设置中，默认的 `"auto"` 模式会退回到基于输入的压缩，而不是依赖 `previous_response_id`。有关完整示例，请参阅 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。 -#### 自动压缩可能阻塞流式传输 +#### 自动压缩对流式传输的阻塞 -压缩会清除并重写会话历史，因此 SDK 会等待压缩完成后才认为运行结束。在流式传输模式下，这意味着如果压缩较重，`run.stream_events()` 可能会在最后一个输出 token 之后继续保持打开数秒。 +压缩会清空并重写会话历史记录，因此 SDK 会等待压缩完成后才将该运行视为完成。在流式传输模式下，这意味着如果压缩开销较大，在最后一个输出 token 之后，`run.stream_events()` 可能仍会保持打开数秒。 -如果你需要低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲时间）自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。 +如果你希望低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲期间）自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。 ```python from agents import Agent, Runner, SQLiteSession @@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session) ### Redis 会话 -使用 `RedisSession` 在多个 worker 或服务之间共享会话记忆。 +使用 `RedisSession` 在多个工作进程或服务之间共享会话记忆。 ```bash pip install openai-agents[redis] @@ -369,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session) ### SQLAlchemy 会话 -使用任何 SQLAlchemy 支持的数据库实现生产就绪的 Agents SDK 会话持久化： +使用任何 SQLAlchemy 支持的数据库实现的生产就绪型 Agents SDK 会话持久化： ```python from agents.extensions.memory import SQLAlchemySession @@ -387,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db") session = SQLAlchemySession("user_123", engine=engine, create_tables=True) ``` -详细文档请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)。 +请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)了解详细文档。 ### Dapr 会话 -当你已经运行 Dapr sidecar，或希望会话存储能够在不同状态存储后端之间迁移且无需更改智能体代码时，请使用 `DaprSession`。 +当你已经运行 Dapr sidecar，或希望在不更改智能体代码的情况下，让会话存储能够在不同状态存储后端之间迁移时，请使用 `DaprSession`。 ```bash pip install openai-agents[dapr] @@ -414,16 +414,16 @@ async with DaprSession.from_address( 备注： -- `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果你的应用已经管理了一个客户端，请直接使用 `DaprSession(...)` 并传入 `dapr_client=...`。 -- 传入 `ttl=...`，可在底层状态存储支持 TTL 时让其自动过期旧会话数据。 -- 当你需要更强的写后读保证时，请传入 `consistency=DAPR_CONSISTENCY_STRONG`。 -- Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中，启动 Dapr 时除 `dapr_address` 使用的 gRPC 端口外，还应包含 `--dapr-http-port 3500`。 -- 完整设置演练（包括本地组件和故障排查）请参阅 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)。 +- `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果你的应用已经管理了一个客户端，请直接使用 `dapr_client=...` 构造 `DaprSession(...)`。 +- 当底层状态存储支持 TTL 时，传入 `ttl=...` 可让它自动使旧会话数据过期。 +- 当你需要更强的写后读保证时，传入 `consistency=DAPR_CONSISTENCY_STRONG`。 +- Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中，启动 Dapr 时除了 `dapr_address` 中使用的 gRPC 端口外，还应使用 `--dapr-http-port 3500`。 +- 请参阅 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)获取完整设置演练，包括本地组件和故障排查。 ### MongoDB 会话 -对于已经使用 MongoDB，或需要可水平扩展、多进程会话存储的应用，请使用 `MongoDBSession`。 +对于已使用 MongoDB 或需要可水平扩展的多进程会话存储的应用，请使用 `MongoDBSession`。 ```bash pip install openai-agents[mongodb] @@ -448,10 +448,10 @@ await session.close() 备注： -- `from_uri(...)` 会创建并拥有 `AsyncMongoClient`，并在 `session.close()` 时关闭它。如果你的应用已经管理客户端，请直接使用 `MongoDBSession(...)` 并传入 `client=...`；在这种情况下，`session.close()` 是空操作，生命周期由调用方管理。 -- 通过向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI（无需其他更改）连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)。 -- 使用两个集合，并且这两个名称都可以通过 `sessions_collection=`（默认 `agent_sessions`）和 `messages_collection=`（默认 `agent_messages`）配置。索引会在首次使用时自动创建。每条消息文档都带有一个单调递增的 `seq` 计数器，用于在并发写入者和进程之间保持顺序。 -- 在首次运行前，使用 `await session.ping()` 验证连接。 +- `from_uri(...)` 会创建并拥有 `AsyncMongoClient`，并在 `session.close()` 时关闭它。如果你的应用已经管理了一个客户端，请直接使用 `client=...` 构造 `MongoDBSession(...)`；在这种情况下，`session.close()` 不执行任何操作，生命周期由调用方管理。 +- 通过向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI，即可连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)，无需其他更改。 +- 会使用两个集合，且二者名称都可通过 `sessions_collection=`（默认 `agent_sessions`）和 `messages_collection=`（默认 `agent_messages`）配置。首次使用时会自动创建索引。每个消息文档都带有一个单调递增的 `seq` 计数器，可在并发写入者和进程之间保持顺序。 +- 在首次运行之前，使用 `await session.ping()` 验证连接性。 ### 高级 SQLite 会话 @@ -475,11 +475,11 @@ await session.store_run_usage(result) # Track token usage await session.create_branch_from_turn(2) # Branch from turn 2 ``` -详细文档请参阅[高级 SQLite 会话](advanced_sqlite_session.md)。 +请参阅 [高级 SQLite 会话](advanced_sqlite_session.md)了解详细文档。 ### 加密会话 -适用于任何会话实现的透明加密包装器： +用于任何会话实现的透明加密包装器： ```python from agents.extensions.memory import EncryptedSession, SQLAlchemySession @@ -502,17 +502,17 @@ session = EncryptedSession( result = await Runner.run(agent, "Hello", session=session) ``` -详细文档请参阅[加密会话](encrypted_session.md)。 +请参阅 [加密会话](encrypted_session.md)了解详细文档。 ### 其他会话类型 -还有一些其他内置选项。请参考 `examples/memory/` 以及 `extensions/memory/` 下的源代码。 +还有一些其他内置选项。请参阅 `examples/memory/` 以及 `extensions/memory/` 下的源代码。 -## 运维模式 +## 操作模式 ### 会话 ID 命名 -使用有意义的会话 ID，帮助你组织对话： +使用有意义的会话 ID 来帮助你组织对话： - 基于用户：`"user_12345"` - 基于线程：`"thread_abc123"` @@ -520,16 +520,16 @@ result = await Runner.run(agent, "Hello", session=session) ### 记忆持久化 -- 对临时对话使用内存 SQLite（`SQLiteSession("session_id")`） -- 对持久对话使用基于文件的 SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`） +- 使用内存 SQLite（`SQLiteSession("session_id")`）处理临时对话 +- 使用基于文件的 SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）处理持久对话 - 当你需要基于 `aiosqlite` 的实现时，使用异步 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`） -- 使用 Redis 后端会话（`RedisSession.from_url("session_id", url="redis://...")`）实现共享、低延迟的会话记忆 -- 对于使用 SQLAlchemy 支持的现有数据库的生产系统，使用 SQLAlchemy 驱动的会话（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`） -- 对于已经使用 MongoDB 或需要多进程、可水平扩展会话存储的应用，使用 MongoDB 会话（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`） -- 对于生产级云原生部署，使用 Dapr 状态存储会话（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`），支持 30+ 数据库后端，并内置遥测、追踪和数据隔离 -- 当你倾向于将历史记录存储在 OpenAI Conversations API 中时，使用 OpenAI 托管存储（`OpenAIConversationsSession()`） -- 使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任何会话包装透明加密和基于 TTL 的过期 -- 对于更高级的用例，可考虑为其他生产系统（例如 Django）实现自定义会话后端 +- 使用基于 Redis 的会话（`RedisSession.from_url("session_id", url="redis://...")`）实现共享的低延迟会话记忆 +- 对于使用 SQLAlchemy 支持的现有数据库的生产系统，使用基于 SQLAlchemy 的会话（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`） +- 对于已使用 MongoDB 或需要多进程、可水平扩展会话存储的应用，使用 MongoDB 会话（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`） +- 对于支持 30+ 数据库后端，并内置遥测、追踪和数据隔离的生产级云原生部署，使用 Dapr 状态存储会话（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`） +- 当你希望将历史记录存储在 OpenAI Conversations API 中时，使用 OpenAI 托管存储（`OpenAIConversationsSession()`） +- 使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任何会话包装透明加密和基于 TTL 的过期机制 +- 对于更高级的用例，可以考虑为其他生产系统（例如 Django）实现自定义会话后端 ### 多个会话 @@ -577,7 +577,7 @@ result2 = await Runner.run( ## 完整示例 -下面是一个展示会话记忆实际工作方式的完整示例： +下面是展示会话记忆实际效果的完整示例： ```python import asyncio @@ -641,7 +641,7 @@ if __name__ == "__main__": ## 自定义会话实现 -你可以创建一个遵循 [`Session`][agents.memory.session.Session] 协议的类，来实现自己的会话记忆： +你可以创建一个遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自己的会话记忆： ```python from agents.memory.session import SessionABC @@ -686,13 +686,13 @@ result = await Runner.run( ## 社区会话实现 -社区已经开发了额外的会话实现： +社区已开发出其他会话实现： | 包 | 描述 | |---------|-------------| | [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 基于 Django ORM 的会话，适用于任何 Django 支持的数据库（PostgreSQL、MySQL、SQLite 等） | -如果你构建了会话实现，欢迎提交文档 PR 将其添加到这里！ +如果你构建了一个会话实现，欢迎提交文档 PR，将它添加到这里！ ## API 参考 @@ -703,9 +703,9 @@ result = await Runner.run( - [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 压缩包装器 - [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基础 SQLite 实现 - [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - 基于 `aiosqlite` 的异步 SQLite 实现 -- [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 后端会话实现 -- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 驱动的实现 -- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 后端会话实现 +- [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - 基于 Redis 的会话实现 +- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 基于 SQLAlchemy 的实现 +- [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - 基于 MongoDB 的会话实现 - [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状态存储实现 -- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 带分支和分析的增强型 SQLite -- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任何会话的加密包装器 \ No newline at end of file +- [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 支持分支和分析的增强型 SQLite +- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 用于任何会话的加密包装器 \ No newline at end of file diff --git a/docs/zh/sessions/sqlalchemy_session.md b/docs/zh/sessions/sqlalchemy_session.md index f6a41c0294..ee265529d8 100644 --- a/docs/zh/sessions/sqlalchemy_session.md +++ b/docs/zh/sessions/sqlalchemy_session.md @@ -4,11 +4,11 @@ search: --- # SQLAlchemy 会话 -`SQLAlchemySession` 使用 SQLAlchemy 提供可用于生产环境的会话实现，使你能够使用 SQLAlchemy 支持的任意数据库（PostgreSQL、MySQL、SQLite 等）进行会话存储。 +`SQLAlchemySession` 使用 SQLAlchemy 提供生产就绪的会话实现，使你可以使用 SQLAlchemy 支持的任何数据库（PostgreSQL、MySQL、SQLite 等）进行会话存储。 ## 安装 -SQLAlchemy 会话需要 `sqlalchemy` 扩展： +SQLAlchemy 会话需要 `sqlalchemy` 额外依赖： ```bash pip install openai-agents[sqlalchemy] @@ -44,7 +44,7 @@ if __name__ == "__main__": ### 使用现有引擎 -适用于已有 SQLAlchemy 引擎的应用程序： +适用于已有 SQLAlchemy 引擎的应用： ```python import asyncio @@ -73,6 +73,7 @@ if __name__ == "__main__": asyncio.run(main()) ``` + ## API 参考 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 主类 diff --git a/docs/zh/streaming.md b/docs/zh/streaming.md index ab3da2fa24..edf6989847 100644 --- a/docs/zh/streaming.md +++ b/docs/zh/streaming.md @@ -4,19 +4,19 @@ 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] 对象组成的异步流，这些对象将在下文介绍。 -持续消费 `result.stream_events()`，直到异步迭代器结束。只有当迭代器结束时，流式运行才算完成；在最后一个可见 token 到达后，会话持久化、审批记账或历史压缩等后处理仍可能完成。当循环退出时，`result.is_complete` 会反映最终运行状态。 +请持续消费 `result.stream_events()`，直到异步迭代器结束。只有当迭代器结束时，一次流式运行才算完成；会话持久化、审批记账或历史压缩等后处理可能会在最后一个可见 token 到达后才完成。当循环退出时，`result.is_complete` 会反映最终运行状态。 ## 原始响应事件 -[`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` 等）和数据。如果你希望在响应消息生成后立即将其流式传输给用户，这些事件会很有用。 -计算机工具原始事件会保留与存储结果相同的预览版与 GA 区分。预览版流程会流式传输带有一个 `action` 的 `computer_call` 项，而 `gpt-5.5` 可以流式传输带有批量 `actions[]` 的 `computer_call` 项。更高层级的 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 表层不会为此添加仅限计算机的特殊事件名称：这两种形态仍都会以 `tool_called` 呈现，截图结果则会作为包装了 `computer_call_output` 项的 `tool_output` 返回。 +计算机工具原始事件会保留与已存储结果相同的 Preview 与 GA 区分。Preview 流会流式传输带有一个 `action` 的 `computer_call` 项，而 `gpt-5.5` 可以流式传输带有批量 `actions[]` 的 `computer_call` 项。更高层级的 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 表面不会为此添加特殊的仅限计算机的事件名称：两种形态仍然都会以 `tool_called` 的形式呈现，截图结果则会以 `tool_output` 的形式返回，并包装一个 `computer_call_output` 项。 -例如，这会逐个 token 输出 LLM 生成的文本。 +例如，这将逐个 token 输出 LLM 生成的文本。 ```python import asyncio @@ -41,7 +41,7 @@ if __name__ == "__main__": ## 流式传输与审批 -流式传输与因工具审批而暂停的运行兼容。如果某个工具需要审批，`result.stream_events()` 会结束，并且待处理的审批会在 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 中暴露。使用 `result.to_state()` 将结果转换为 [`RunState`][agents.run_state.RunState]，批准或拒绝该中断，然后使用 `Runner.run_streamed(...)` 恢复运行。 +流式传输与会暂停以等待工具审批的运行兼容。如果某个工具需要审批，`result.stream_events()` 会结束，待处理的审批会通过 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 暴露。使用 `result.to_state()` 将结果转换为 [`RunState`][agents.run_state.RunState]，批准或拒绝该中断，然后使用 `Runner.run_streamed(...)` 恢复运行。 ```python result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.") @@ -57,21 +57,21 @@ if result.interruptions: pass ``` -如需完整的暂停/恢复演练，请参阅[人在环路指南](human_in_the_loop.md)。 +有关完整的暂停/恢复演练，请参阅 [human-in-the-loop 指南](human_in_the_loop.md)。 ## 当前轮次后的流式传输取消 -如果你需要在中途停止一次流式运行，请调用 [`result.cancel()`][agents.result.RunResultStreaming.cancel]。默认情况下，这会立即停止运行。若要让当前轮次在停止前干净地完成，请改为调用 `result.cancel(mode="after_turn")`。 +如果需要在中途停止一次流式运行，请调用 [`result.cancel()`][agents.result.RunResultStreaming.cancel]。默认情况下，这会立即停止运行。若要让当前轮次在停止前干净地完成，请改为调用 `result.cancel(mode="after_turn")`。 -在 `result.stream_events()` 结束之前，流式运行都不算完成。在最后一个可见 token 之后，SDK 可能仍在持久化会话项、最终确定审批状态或压缩历史。 +在 `result.stream_events()` 完成之前，流式运行并未完成。在最后一个可见 token 之后，SDK 可能仍在持久化会话项、最终确定审批状态或压缩历史。 -如果你正从 [`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] 手动继续，并且 `cancel(mode="after_turn")` 在工具轮次之后停止，请使用该规范化输入重新运行 `result.last_agent` 来继续这个未完成的轮次，而不是立即追加一个新的用户轮次。 -- 如果一次流式运行因工具审批而停止，不要将其视为新的轮次。请先完成对流的读取，检查 `result.interruptions`，然后改为从 `result.to_state()` 恢复。 -- 使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 自定义在下一次模型调用之前，如何合并检索到的会话历史与新的用户输入。如果你在那里重写了新轮次的项目，则该轮次会持久化重写后的版本。 +如果你正在从 [`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] 手动继续，并且 `cancel(mode="after_turn")` 在一次工具轮次后停止，请通过使用该规范化输入重新运行 `result.last_agent` 来继续那个未完成的轮次，而不是立即追加一个新的用户轮次。 +- 如果流式运行因工具审批而停止，不要将其视为一个新轮次。请先完全消费流，检查 `result.interruptions`，然后改为从 `result.to_state()` 恢复。 +- 使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 来自定义在下一次模型调用之前，如何合并检索到的会话历史与新的用户输入。如果你在那里重写新轮次项，那么被重写的版本就是该轮次会持久化的内容。 ## 运行项事件与智能体事件 -[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 是更高层级的事件。它们会在某个项完全生成后通知你。这使你能够在“消息已生成”“工具已运行”等层级推送进度更新，而不是针对每个 token 推送。同样，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如因任务转移而变化）向你提供更新。 +[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 是更高层级的事件。它们会在某个项完全生成后通知你。这使你可以按“消息已生成”“工具已运行”等级别向用户推送进度更新，而不是按每个 token 推送。类似地，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如由于任务转移）向你提供更新。 ### 运行项事件名称 @@ -89,11 +89,11 @@ if result.interruptions: - `mcp_approval_response` - `mcp_list_tools` -为保持向后兼容，`handoff_occured` 有意拼写错误。 +`handoff_occured` 为了向后兼容而有意拼写错误。 -使用托管工具搜索时，当模型发出工具搜索请求时会发出 `tool_search_called`，当 Responses API 返回已加载的子集时会发出 `tool_search_output_created`。 +当你使用托管工具搜索时，模型发出工具搜索请求时会发出 `tool_search_called`，Responses API 返回已加载的子集时会发出 `tool_search_output_created`。 -例如，这会忽略原始事件，并向用户流式传输更新。 +例如，这将忽略原始事件，并将更新流式传输给用户。 ```python import asyncio diff --git a/docs/zh/tools.md b/docs/zh/tools.md index 7e7cd2d9f3..1cd1d3b841 100644 --- a/docs/zh/tools.md +++ b/docs/zh/tools.md @@ -4,41 +4,41 @@ search: --- # 工具 -工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至使用计算机。SDK 支持五个目录： +工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至使用计算机。SDK 支持五类： -- 由 OpenAI 托管的工具：与模型一起在 OpenAI 服务上运行。 +- 由 OpenAI 托管的工具：在 OpenAI 服务上与模型一起运行。 - 本地/运行时执行工具：`ComputerTool` 和 `ApplyPatchTool` 始终在你的环境中运行，而 `ShellTool` 可以在本地或托管容器中运行。 -- Function Calling：将任意 Python 函数封装为工具。 -- Agents as tools：将智能体公开为可调用工具，无需完整任务转移。 -- 实验性：Codex 工具：通过工具调用运行作用域限定在工作区内的 Codex 任务。 +- Function calling：将任何 Python 函数包装为工具。 +- Agents as tools：将智能体暴露为可调用工具，而无需完整任务转移。 +- 实验性：Codex 工具：通过工具调用运行限定于工作区的 Codex 任务。 ## 工具类型选择 -将本页用作目录，然后跳转到与你控制的运行时匹配的部分。 +将本页作为目录，然后跳转到与你所控制的运行时相匹配的部分。 | 如果你想要... | 从这里开始 | | --- | --- | -| 使用 OpenAI 管理的工具（网络检索、文件检索、代码解释器、托管 MCP、图像生成） | [托管工具](#hosted-tools) | -| 通过工具搜索将大型工具表面推迟到运行时 | [托管工具搜索](#hosted-tool-search) | +| 使用由 OpenAI 管理的工具（网络检索、文件检索、code interpreter、托管 MCP、图像生成） | [托管工具](#hosted-tools) | +| 通过工具搜索将大型工具集合延迟到运行时加载 | [托管工具搜索](#hosted-tool-search) | | 在你自己的进程或环境中运行工具 | [本地运行时工具](#local-runtime-tools) | -| 将 Python 函数封装为工具 | [工具调用](#function-tools) | -| 让一个智能体在没有任务转移的情况下调用另一个智能体 | [Agents as tools](#agents-as-tools) | -| 从智能体运行作用域限定在工作区内的 Codex 任务 | [实验性：Codex 工具](#experimental-codex-tool) | +| 将 Python 函数包装为工具 | [工具调用](#function-tools) | +| 让一个智能体在不进行任务转移的情况下调用另一个智能体 | [Agents as tools](#agents-as-tools) | +| 从智能体运行限定于工作区的 Codex 任务 | [实验性：Codex 工具](#experimental-codex-tool) | ## 托管工具 使用 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 时，OpenAI 提供了一些内置工具： -- [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体搜索网络。 +- [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体进行网络检索。 - [`FileSearchTool`][agents.tool.FileSearchTool] 允许从你的 OpenAI 向量存储中检索信息。 - [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙盒环境中执行代码。 -- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务的工具公开给模型。 +- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务的工具暴露给模型。 - [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 根据提示词生成图像。 -- [`ToolSearchTool`][agents.tool.ToolSearchTool] 让模型按需加载延迟的工具、命名空间或托管 MCP 服务。 +- [`ToolSearchTool`][agents.tool.ToolSearchTool] 让模型按需加载延迟工具、命名空间或托管 MCP 服务。 高级托管搜索选项： -- 除了 `vector_store_ids` 和 `max_num_results`，`FileSearchTool` 还支持 `filters`、`ranking_options` 和 `include_search_results`。 +- 除了 `vector_store_ids` 和 `max_num_results` 之外，`FileSearchTool` 还支持 `filters`、`ranking_options` 和 `include_search_results`。 - `WebSearchTool` 支持 `filters`、`user_location` 和 `search_context_size`。 ```python @@ -62,9 +62,9 @@ async def main(): ### 托管工具搜索 -工具搜索让 OpenAI Responses 模型能够将大型工具表面推迟到运行时，因此模型只加载当前轮次所需的子集。当你有许多工具调用、命名空间组或托管 MCP 服务，并且希望减少工具 schema token、同时不预先暴露每个工具时，这会很有用。 +工具搜索让 OpenAI Responses 模型可以将大型工具集合延迟到运行时加载，因此模型只会加载当前轮次所需的子集。当你有许多工具调用、命名空间组或托管 MCP 服务，并且希望减少工具 schema token，而不是预先暴露每个工具时，这会很有用。 -当你构建智能体时候选工具已经已知，请从托管工具搜索开始。如果你的应用需要动态决定加载什么，Responses API 也支持客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。 +当候选工具在你构建智能体时已经已知，请从托管工具搜索开始。如果你的应用需要动态决定要加载什么，Responses API 也支持由客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。 ```python from typing import Annotated @@ -106,26 +106,26 @@ result = await Runner.run(agent, "Look up customer_42 and list their open orders print(result.final_output) ``` -需要了解的事项： - -- 托管工具搜索仅适用于 OpenAI Responses 模型。当前 Python SDK 支持取决于 `openai>=2.25.0`。 -- 在智能体上配置延迟加载表面时，恰好添加一个 `ToolSearchTool()`。 -- 可搜索表面包括 `@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])`，以及 `HostedMCPTool(tool_config={..., "defer_loading": True})`。 -- 延迟加载的工具调用必须与 `ToolSearchTool()` 配对。仅命名空间的设置也可以使用 `ToolSearchTool()`，以便让模型按需加载正确的组。 -- `tool_namespace()` 将 `FunctionTool` 实例分组到共享的命名空间名称和描述下。当你有许多相关工具（例如 `crm`、`billing` 或 `shipping`）时，这通常最合适。 -- OpenAI 的官方最佳实践指南是[尽可能使用命名空间](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)。 -- 尽可能优先使用命名空间或托管 MCP 服务，而不是许多单独延迟的函数。它们通常能为模型提供更好的高层搜索表面，并带来更好的 token 节省。 -- 命名空间可以混合立即可用和延迟的工具。没有 `defer_loading=True` 的工具仍可立即调用，而同一命名空间中的延迟工具会通过工具搜索加载。 -- 根据经验法则，每个命名空间应保持相当小，最好少于 10 个函数。 -- 具名 `tool_choice` 不能指向裸命名空间名称或仅延迟的工具。优先使用 `auto`、`required`，或真实的顶层可调用工具名称。 -- `ToolSearchTool(execution="client")` 用于手动 Responses 编排。如果模型发出客户端执行的 `tool_search_call`，标准 `Runner` 会抛出异常，而不是替你执行它。 -- 工具搜索活动会出现在 [`RunResult.new_items`](results.md#new-items) 中，并以专用条目和事件类型出现在 [`RunItemStreamEvent`](streaming.md#run-item-event-names) 中。 -- 请参阅 `examples/tools/tool_search.py`，其中包含覆盖命名空间加载和顶层延迟工具的完整可运行示例。 +注意事项： + +- 托管工具搜索仅适用于 OpenAI Responses 模型。当前 Python SDK 支持依赖于 `openai>=2.25.0`。 +- 当你在智能体上配置延迟加载范围时，需要且只能添加一个 `ToolSearchTool()`。 +- 可搜索范围包括 `@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])` 和 `HostedMCPTool(tool_config={..., "defer_loading": True})`。 +- 延迟加载的工具调用必须与 `ToolSearchTool()` 配对。仅命名空间的设置也可以使用 `ToolSearchTool()`，让模型按需加载正确的分组。 +- `tool_namespace()` 会将 `FunctionTool` 实例归入共享的命名空间名称和描述下。当你有许多相关工具时（例如 `crm`、`billing` 或 `shipping`），这通常是最合适的选择。 +- OpenAI 官方最佳实践指南是[尽可能使用命名空间](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)。 +- 在可行时，优先使用命名空间或托管 MCP 服务，而不是许多单独延迟加载的函数。它们通常能为模型提供更好的高层搜索界面，并带来更好的 token 节省效果。 +- 命名空间可以混合使用立即可用工具和延迟工具。没有 `defer_loading=True` 的工具仍可立即调用，而同一命名空间中的延迟工具会通过工具搜索加载。 +- 经验法则是，让每个命名空间保持相对较小，理想情况下少于 10 个函数。 +- 命名的 `tool_choice` 不能指向裸命名空间名称或仅延迟加载的工具。优先使用 `auto`、`required`，或真正的顶层可调用工具名称。 +- `ToolSearchTool(execution="client")` 用于手动编排 Responses。如果模型发出由客户端执行的 `tool_search_call`，标准 `Runner` 会抛出异常，而不会替你执行它。 +- 工具搜索活动会出现在 [`RunResult.new_items`](results.md#new-items) 中，也会以专用条目和事件类型出现在 [`RunItemStreamEvent`](streaming.md#run-item-event-names) 中。 +- 参见 `examples/tools/tool_search.py`，其中包含覆盖命名空间加载和顶层延迟工具的完整可运行代码示例。 - 官方平台指南：[工具搜索](https://developers.openai.com/api/docs/guides/tools-tool-search)。 -### 托管容器 shell + 技能 +### 托管容器 Shell + 技能 -`ShellTool` 还支持 OpenAI 托管的容器执行。当你希望模型在受管容器中运行 shell 命令，而不是在你的本地运行时中运行时，请使用此模式。 +`ShellTool` 还支持由 OpenAI 托管的容器执行。当你希望模型在托管容器中运行 shell 命令，而不是在本地运行时中运行时，请使用此模式。 ```python from agents import Agent, Runner, ShellTool, ShellToolSkillReference @@ -160,21 +160,21 @@ print(result.final_output) 若要在后续运行中复用现有容器，请设置 `environment={"type": "container_reference", "container_id": "cntr_..."}`。 -需要了解的事项： +注意事项： - 托管 shell 可通过 Responses API shell 工具使用。 -- `container_auto` 会为请求预置一个容器；`container_reference` 会复用现有容器。 -- `container_auto` 还可以包含 `file_ids` 和 `memory_limit`。 +- `container_auto` 会为请求配置一个容器；`container_reference` 会复用现有容器。 +- `container_auto` 也可以包含 `file_ids` 和 `memory_limit`。 - `environment.skills` 接受技能引用和内联技能包。 - 使用托管环境时，不要在 `ShellTool` 上设置 `executor`、`needs_approval` 或 `on_approval`。 - `network_policy` 支持 `disabled` 和 `allowlist` 模式。 -- 在 allowlist 模式下，`network_policy.domain_secrets` 可以按名称注入域作用域的密钥。 -- 请参阅 `examples/tools/container_shell_skill_reference.py` 和 `examples/tools/container_shell_inline_skill.py`，了解完整示例。 -- OpenAI 平台指南：[Shell](https://platform.openai.com/docs/guides/tools-shell) 和 [Skills](https://platform.openai.com/docs/guides/tools-skills)。 +- 在 allowlist 模式下，`network_policy.domain_secrets` 可以按名称注入限定于域的密钥。 +- 参见 `examples/tools/container_shell_skill_reference.py` 和 `examples/tools/container_shell_inline_skill.py` 获取完整示例。 +- OpenAI 平台指南：[Shell](https://platform.openai.com/docs/guides/tools-shell) 和 [技能](https://platform.openai.com/docs/guides/tools-skills)。 ## 本地运行时工具 -本地运行时工具在模型响应本身之外执行。模型仍会决定何时调用它们，但实际工作由你的应用或配置的执行环境完成。 +本地运行时工具在模型响应本身之外执行。模型仍然决定何时调用它们，但实际工作由你的应用或已配置的执行环境完成。 `ComputerTool` 和 `ApplyPatchTool` 始终需要你提供本地实现。`ShellTool` 跨越两种模式：当你希望托管执行时，使用上面的托管容器配置；当你希望命令在自己的进程中运行时，使用下面的本地运行时配置。 @@ -183,27 +183,27 @@ print(result.final_output) - [`ComputerTool`][agents.tool.ComputerTool]：实现 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 接口，以启用 GUI/浏览器自动化。 - [`ShellTool`][agents.tool.ShellTool]：用于本地执行和托管容器执行的最新 shell 工具。 - [`LocalShellTool`][agents.tool.LocalShellTool]：旧版本地 shell 集成。 -- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]：实现 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] 以在本地应用 diff。 +- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]：实现 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]，以在本地应用差异。 - 本地 shell 技能可通过 `ShellTool(environment={"type": "local", "skills": [...]})` 使用。 -### ComputerTool 与 Responses 计算机工具 +### ComputerTool 和 Responses 计算机工具 -`ComputerTool` 仍然是一个本地 harness：你提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 会将该 harness 映射到 OpenAI Responses API 的计算机表面。 +`ComputerTool` 仍然是一个本地执行框架：你提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 会将该执行框架映射到 OpenAI Responses API 的计算机接口上。 -对于显式的 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 请求，SDK 发送 GA 内置工具载荷 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型保留预览载荷 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI 的[计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)中描述的平台迁移一致： +对于显式的 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 请求，SDK 会发送 GA 内置工具载荷 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型会保留预览载荷 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI 的[计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)中描述的平台迁移一致： - 模型：`computer-use-preview` -> `gpt-5.5` - 工具选择器：`computer_use_preview` -> `computer` -- 计算机调用形态：每个 `computer_call` 一个 `action` -> `computer_call` 上的批量 `actions[]` -- 截断：预览路径上需要 `ModelSettings(truncation="auto")` -> GA 路径上不需要 +- 计算机调用形态：每个 `computer_call` 一个 `action` -> `computer_call` 上批处理的 `actions[]` +- 截断：预览路径需要 `ModelSettings(truncation="auto")` -> GA 路径不需要 -SDK 会根据实际 Responses 请求上的有效模型选择该线缆形态。如果你使用提示模板，并且由于提示自身拥有模型而请求省略了 `model`，SDK 会保持预览兼容的计算机载荷，除非你显式保留 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 +SDK 会根据实际 Responses 请求中的有效模型选择该传输格式。如果你使用提示词模板，并且由于模型由提示词拥有而使请求省略 `model`，SDK 会保留兼容预览版的计算机载荷，除非你要么显式保留 `model="gpt-5.5"`，要么通过 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。 -当存在 [`ComputerTool`][agents.tool.ComputerTool] 时，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 都会被接受，并规范化为与有效请求模型匹配的内置选择器。没有 `ComputerTool` 时，这些字符串仍像普通函数名一样工作。 +当存在 [`ComputerTool`][agents.tool.ComputerTool] 时，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 都会被接受，并会规范化为与有效请求模型匹配的内置选择器。如果没有 `ComputerTool`，这些字符串仍会像普通函数名称一样工作。 -当 `ComputerTool` 由 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂提供支持时，这一区别很重要。GA `computer` 载荷在序列化时不需要 `environment` 或尺寸，因此未解析的工厂也没问题。预览兼容的序列化仍需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 能发送 `environment`、`display_width` 和 `display_height`。 +当 `ComputerTool` 由 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂支持时，这一区别很重要。GA `computer` 载荷在序列化时不需要 `environment` 或尺寸，因此未解析的工厂也没问题。兼容预览版的序列化仍然需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 能发送 `environment`、`display_width` 和 `display_height`。 -运行时，两条路径仍使用相同的本地 harness。预览响应会发出带有单个 `action` 的 `computer_call` 条目；`gpt-5.5` 可以发出批量 `actions[]`，SDK 会按顺序执行它们，然后生成一个 `computer_call_output` 截图条目。请参阅 `examples/tools/computer_use.py`，了解基于 Playwright 的可运行 harness。 +在运行时，两条路径仍使用相同的本地执行框架。预览版响应会发出带有单个 `action` 的 `computer_call` 条目；`gpt-5.5` 可以发出批处理的 `actions[]`，SDK 会按顺序执行它们，然后生成一个 `computer_call_output` 截图条目。参见 `examples/tools/computer_use.py`，其中包含一个基于 Playwright 的可运行执行框架。 ```python from agents import Agent, ApplyPatchTool, ShellTool @@ -247,16 +247,16 @@ agent = Agent( ## 工具调用 -你可以将任意 Python 函数用作工具。Agents SDK 会自动设置该工具： +你可以将任何 Python 函数用作工具。Agents SDK 会自动设置该工具： - 工具名称将是 Python 函数的名称（或者你可以提供一个名称） -- 工具描述将来自函数的 docstring（或者你可以提供描述） +- 工具描述将来自该函数的 docstring（或者你可以提供一个描述） - 函数输入的 schema 会根据函数参数自动创建 -- 除非禁用，否则每个输入的描述都来自函数的 docstring +- 除非禁用，否则每个输入的描述会来自该函数的 docstring 我们使用 Python 的 `inspect` 模块提取函数签名，并结合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，使用 `pydantic` 创建 schema。 -当你使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏工具调用，直到 `ToolSearchTool()` 加载它。你也可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关工具调用进行分组。请参阅[托管工具搜索](#hosted-tool-search)，了解完整设置和约束。 +使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏一个函数工具，直到 `ToolSearchTool()` 加载它。你也可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关工具调用进行分组。完整设置和约束请参见[托管工具搜索](#hosted-tool-search)。 ```python import json @@ -308,9 +308,9 @@ for tool in agent.tools: ``` -1. 你可以将任意 Python 类型用作函数参数，函数可以是同步或异步的。 -2. 如果存在 docstring，会用于捕获描述和参数描述 -3. 函数可以选择接收 `context`（必须是第一个参数）。你还可以设置覆盖项，例如工具名称、描述、使用哪种 docstring 风格等。 +1. 你可以使用任何 Python 类型作为函数参数，并且函数可以是同步或异步的。 +2. 如果存在 docstring，则会用它来捕获描述和参数描述 +3. 函数可以选择接受 `context`（必须是第一个参数）。你也可以设置覆盖项，例如工具名称、描述、要使用的 docstring 风格等。 4. 你可以将装饰后的函数传入工具列表。 ??? note "展开查看输出" @@ -385,11 +385,11 @@ for tool in agent.tools: ### 从工具调用返回图像或文件 -除了返回文本输出，你还可以将一个或多个图像或文件作为工具调用的输出返回。为此，你可以返回以下任意内容： +除了返回文本输出之外，你还可以返回一个或多个图像或文件作为工具调用的输出。为此，你可以返回以下任意内容： - 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]） - 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]） -- 文本：字符串或可字符串化对象，或者 [`ToolOutputText`][agents.tool.ToolOutputText]（或 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） +- 文本：字符串或可转为字符串的对象，或者 [`ToolOutputText`][agents.tool.ToolOutputText]（或 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]） ### 自定义工具调用 @@ -398,7 +398,7 @@ for tool in agent.tools: - `name` - `description` - `params_json_schema`，即参数的 JSON schema -- `on_invoke_tool`，这是一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和以 JSON 字符串形式传入的参数，并返回工具输出（例如文本、结构化工具输出对象，或输出列表）。 +- `on_invoke_tool`，这是一个异步函数，它接收 [`ToolContext`][agents.tool_context.ToolContext] 和作为 JSON 字符串的参数，并返回工具输出（例如文本、结构化工具输出对象，或输出列表）。 ```python from typing import Any @@ -431,18 +431,18 @@ tool = FunctionTool( ) ``` -### 自动参数与 docstring 解析 +### 参数和 docstring 自动解析 -如前所述，我们会自动解析函数签名以提取工具的 schema，并解析 docstring 以提取工具及各个参数的描述。相关说明： +如前所述，我们会自动解析函数签名以提取工具的 schema，并解析 docstring 以提取工具描述和各个参数的描述。相关说明如下： -1. 签名解析通过 `inspect` 模块完成。我们使用类型注解来理解参数类型，并动态构建一个 Pydantic 模型来表示整体 schema。它支持大多数类型，包括 Python primitives、Pydantic 模型、TypedDict 等。 -2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这是尽力而为；你也可以在调用 `function_tool` 时显式设置。你还可以通过将 `use_docstring_info` 设置为 `False` 来禁用 docstring 解析。 +1. 签名解析通过 `inspect` 模块完成。我们使用类型注解来理解参数类型，并动态构建 Pydantic 模型来表示整体 schema。它支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。 +2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式为 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这是尽力而为的，你也可以在调用 `function_tool` 时显式设置它。你还可以通过将 `use_docstring_info` 设置为 `False` 来禁用 docstring 解析。 -用于 schema 提取的代码位于 [`agents.function_schema`][]。 +schema 提取代码位于 [`agents.function_schema`][]。 ### 使用 Pydantic Field 约束和描述参数 -你可以使用 Pydantic 的 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) 为工具参数添加约束（例如数字的最小/最大值、字符串的长度或模式）和描述。与 Pydantic 中一样，两种形式都受支持：基于默认值的形式（`arg: int = Field(..., ge=1)`）和 `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）。生成的 JSON schema 和验证都会包含这些约束。 +你可以使用 Pydantic 的 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) 为工具参数添加约束（例如数字的最小值/最大值、字符串的长度或模式）和描述。与 Pydantic 中一样，支持两种形式：基于默认值的形式（`arg: int = Field(..., ge=1)`）和 `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）。生成的 JSON schema 和验证会包含这些约束。 ```python from typing import Annotated @@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr ### 工具调用超时 -你可以使用 `@function_tool(timeout=...)` 为异步工具调用设置每次调用的超时时间。 +你可以使用 `@function_tool(timeout=...)` 为异步工具调用设置每次调用的超时。 ```python import asyncio @@ -484,11 +484,11 @@ agent = Agent( 达到超时时，默认行为是 `timeout_behavior="error_as_result"`，它会发送一条模型可见的超时消息（例如 `Tool 'slow_lookup' timed out after 2 seconds.`）。 -你可以控制超时处理： +你可以控制超时处理方式： -- `timeout_behavior="error_as_result"`（默认）：向模型返回超时消息，以便模型恢复。 +- `timeout_behavior="error_as_result"`（默认）：向模型返回超时消息，使其能够恢复。 - `timeout_behavior="raise_exception"`：抛出 [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] 并使运行失败。 -- `timeout_error_function=...`：使用 `error_as_result` 时自定义超时消息。 +- `timeout_error_function=...`：在使用 `error_as_result` 时自定义超时消息。 ```python import asyncio @@ -511,15 +511,15 @@ except ToolTimeoutError as e: !!! note - 仅异步 `@function_tool` 处理程序支持超时配置。 + 超时配置仅支持异步 `@function_tool` 处理程序。 ### 工具调用中的错误处理 -通过 `@function_tool` 创建工具调用时，你可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。 +通过 `@function_tool` 创建函数工具时，你可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。 -- 默认情况下（即你不传入任何内容），它会运行 `default_tool_error_function`，告知 LLM 发生了错误。 -- 如果你传入自己的错误函数，它会改为运行该函数，并将响应发送给 LLM。 -- 如果你显式传入 `None`，则任何工具调用错误都会重新抛出，由你处理。这可能是模型生成无效 JSON 时的 `ModelBehaviorError`，或你的代码崩溃时的 `UserError` 等。 +- 默认情况下（即如果你没有传入任何内容），它会运行 `default_tool_error_function`，告诉 LLM 发生了错误。 +- 如果你传入自己的错误函数，则会改为运行该函数，并将响应发送给 LLM。 +- 如果你显式传入 `None`，则任何工具调用错误都会重新抛出，由你处理。这可能是模型生成了无效 JSON 导致的 `ModelBehaviorError`，也可能是你的代码崩溃导致的 `UserError` 等。 ```python from agents import function_tool, RunContextWrapper @@ -546,7 +546,7 @@ def get_user_profile(user_id: str) -> str: ## Agents as tools -在某些工作流中，你可能希望由一个中央智能体编排一组专门智能体，而不是移交控制权。你可以通过将智能体建模为工具来实现这一点。 +在某些工作流中，你可能希望由一个中央智能体编排一组专业智能体，而不是移交控制权。你可以通过将智能体建模为工具来实现这一点。 ```python from agents import Agent, Runner @@ -587,7 +587,7 @@ async def main(): ### 工具智能体自定义 -`agent.as_tool` 函数是一个便捷方法，便于将智能体转换为工具。它支持常见运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它还支持通过 `parameters`、`input_builder` 和 `include_input_schema` 实现结构化输入。对于高级编排（例如条件重试、回退行为或链接多个智能体调用），请在工具实现中直接使用 `Runner.run`： +`agent.as_tool` 函数是一个便捷方法，可以轻松地将智能体转换为工具。它支持常见运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它还支持通过 `parameters`、`input_builder` 和 `include_input_schema` 实现结构化输入。对于高级编排（例如条件重试、回退行为，或串联多个智能体调用），请在你的工具实现中直接使用 `Runner.run`： ```python @function_tool @@ -608,12 +608,12 @@ async def run_my_agent() -> str: ### 工具智能体的结构化输入 -默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）来公开结构化 schema。 +默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）来暴露结构化 schema。 其他选项： -- `include_input_schema=True` 会在生成的嵌套输入中包含完整的 JSON Schema。 -- `input_builder=...` 让你完全自定义结构化工具参数如何变成嵌套智能体输入。 +- `include_input_schema=True` 会在生成的嵌套输入中包含完整 JSON Schema。 +- `input_builder=...` 让你完全自定义结构化工具参数如何转换为嵌套智能体输入。 - `RunContextWrapper.tool_input` 包含嵌套运行上下文中的已解析结构化载荷。 ```python @@ -634,15 +634,15 @@ translator_tool = translator_agent.as_tool( ) ``` -请参阅 `examples/agent_patterns/agents_as_tools_structured.py`，了解完整可运行示例。 +参见 `examples/agent_patterns/agents_as_tools_structured.py` 获取完整可运行代码示例。 ### 工具智能体的审批门禁 -`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理条目会出现在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复。请参阅[人机协同指南](human_in_the_loop.md)，了解完整的暂停/恢复模式。 +`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理条目会出现在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复。完整的暂停/恢复模式请参见[人在回路指南](human_in_the_loop.md)。 ### 自定义输出提取 -在某些情况下，你可能希望在将工具智能体的输出返回给中央智能体之前修改它。如果你想要： +在某些情况下，你可能希望在将工具智能体的输出返回给中央智能体之前对其进行修改。如果你想要执行以下操作，这可能很有用： - 从子智能体的聊天历史中提取特定信息片段（例如 JSON 载荷）。 - 转换或重新格式化智能体的最终答案（例如将 Markdown 转换为纯文本或 CSV）。 @@ -669,8 +669,8 @@ json_tool = data_agent.as_tool( 在自定义提取器内部，嵌套的 [`RunResult`][agents.result.RunResult] 还会暴露 [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]，当你在后处理嵌套结果时 -需要外层工具名称、调用 ID 或原始参数，这很有用。 -请参阅[结果指南](results.md#agent-as-tool-metadata)。 +需要外层工具名称、调用 ID 或原始参数，这会很有用。 +参见[结果指南](results.md#agent-as-tool-metadata)。 ### 嵌套智能体运行的流式传输 @@ -694,15 +694,15 @@ billing_agent_tool = billing_agent.as_tool( 预期行为： -- 事件类型与 `StreamEvent["type"]` 相对应：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 -- 提供 `on_stream` 会自动以流式传输模式运行嵌套智能体，并在返回最终输出前消耗完该流。 -- 处理程序可以是同步或异步的；每个事件会按到达顺序交付。 -- 当工具通过模型工具调用被调用时，`tool_call` 存在；直接调用时它可能为 `None`。 -- 请参阅 `examples/agent_patterns/agents_as_tools_streaming.py`，了解完整可运行示例。 +- 事件类型与 `StreamEvent["type"]` 保持一致：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。 +- 提供 `on_stream` 会自动以流式传输模式运行嵌套智能体，并在返回最终输出之前耗尽该流。 +- 处理程序可以是同步或异步的；每个事件都会按到达顺序传递。 +- 当工具通过模型工具调用被调用时，会存在 `tool_call`；直接调用可能会使其为 `None`。 +- 参见 `examples/agent_patterns/agents_as_tools_streaming.py` 获取完整可运行示例。 -### 条件性工具启用 +### 条件式工具启用 -你可以使用 `is_enabled` 参数在运行时有条件地启用或禁用智能体工具。这使你能够根据上下文、用户偏好或运行时条件，动态筛选哪些工具可供 LLM 使用。 +你可以使用 `is_enabled` 参数在运行时有条件地启用或禁用智能体工具。这允许你根据上下文、用户偏好或运行时条件，动态过滤哪些工具可供 LLM 使用。 ```python import asyncio @@ -760,21 +760,21 @@ asyncio.run(main()) `is_enabled` 参数接受： - **布尔值**：`True`（始终启用）或 `False`（始终禁用） -- **可调用函数**：接收 `(context, agent)` 并返回布尔值的函数 +- **可调用函数**：接受 `(context, agent)` 并返回布尔值的函数 - **异步函数**：用于复杂条件逻辑的异步函数 -禁用的工具在运行时会对 LLM 完全隐藏，因此这适用于： +禁用的工具在运行时会对 LLM 完全隐藏，因此这对以下场景很有用： - 基于用户权限的功能门控 -- 环境特定的工具可用性（dev 与 prod） +- 特定环境的工具可用性（dev vs prod） - 对不同工具配置进行 A/B 测试 -- 基于运行时状态的动态工具筛选 +- 基于运行时状态的动态工具过滤 ## 实验性：Codex 工具 -`codex_tool` 封装了 Codex CLI，使智能体能够在工具调用期间运行作用域限定在工作区内的任务（shell、文件编辑、MCP 工具）。此表面处于实验阶段，可能会发生变化。 +`codex_tool` 包装了 Codex CLI，使智能体可以在工具调用期间运行限定于工作区的任务（shell、文件编辑、MCP 工具）。这个接口是实验性的，可能会发生变化。 -当你希望主智能体将有界的工作区任务委派给 Codex，且不离开当前运行时，请使用它。默认情况下，工具名称是 `codex`。如果你设置自定义名称，它必须是 `codex` 或以 `codex_` 开头。当智能体包含多个 Codex 工具时，每个工具都必须使用唯一名称。 +当你希望主智能体在不离开当前运行的情况下，将有边界的工作区任务委派给 Codex 时，请使用它。默认情况下，工具名称为 `codex`。如果你设置自定义名称，它必须是 `codex` 或以 `codex_` 开头。当一个智能体包含多个 Codex 工具时，每个工具都必须使用唯一名称。 ```python from agents import Agent @@ -805,31 +805,31 @@ agent = Agent( 从以下选项组开始： -- 执行表面：`sandbox_mode` 和 `working_directory` 定义 Codex 可以在哪里操作。将它们配对使用；当工作目录不在 Git 仓库中时，设置 `skip_git_repo_check=True`。 +- 执行范围：`sandbox_mode` 和 `working_directory` 定义 Codex 可以在哪里操作。将它们配套设置；当工作目录不在 Git 仓库中时，设置 `skip_git_repo_check=True`。 - 线程默认值：`default_thread_options=ThreadOptions(...)` 配置模型、推理强度、审批策略、附加目录、网络访问和网络检索模式。优先使用 `web_search_mode`，而不是旧版 `web_search_enabled`。 -- 轮次默认值：`default_turn_options=TurnOptions(...)` 配置每轮行为，例如 `idle_timeout_seconds` 和可选取消 `signal`。 -- 工具 I/O：工具调用必须至少包含一个 `inputs` 条目，其形式为 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。`output_schema` 让你要求 Codex 返回结构化响应。 +- 轮次默认值：`default_turn_options=TurnOptions(...)` 配置每轮行为，例如 `idle_timeout_seconds` 和可选的取消 `signal`。 +- 工具 I/O：工具调用必须至少包含一个 `inputs` 条目，其形式为 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。`output_schema` 允许你要求结构化 Codex 响应。 线程复用和持久化是独立控制项： -- `persist_session=True` 会对同一工具实例的重复调用复用一个 Codex 线程。 -- `use_run_context_thread_id=True` 会在共享同一可变上下文对象的多次运行之间，在运行上下文中存储并复用线程 ID。 -- 线程 ID 优先级为：每次调用的 `thread_id`，然后是运行上下文线程 ID（如果启用），然后是配置的 `thread_id` 选项。 -- 对于 `name="codex"`，默认运行上下文键是 `codex_thread_id`；对于 `name="codex_"`，则是 `codex_thread_id_`。可用 `run_context_thread_id_key` 覆盖它。 +- `persist_session=True` 会为对同一工具实例的重复调用复用一个 Codex 线程。 +- `use_run_context_thread_id=True` 会在运行上下文中存储并复用线程 ID，适用于共享同一可变上下文对象的跨运行场景。 +- 线程 ID 优先级为：每次调用的 `thread_id`，然后是运行上下文线程 ID（如果启用），然后是已配置的 `thread_id` 选项。 +- 默认运行上下文键为：当 `name="codex"` 时是 `codex_thread_id`，当 `name="codex_"` 时是 `codex_thread_id_`。可使用 `run_context_thread_id_key` 覆盖它。 运行时配置： - 认证：设置 `CODEX_API_KEY`（首选）或 `OPENAI_API_KEY`，或传入 `codex_options={"api_key": "..."}`。 - 运行时：`codex_options.base_url` 会覆盖 CLI base URL。 -- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则，SDK 会先从 `PATH` 解析 `codex`，然后回退到捆绑的 vendor 二进制文件。 -- 环境：`codex_options.env` 完全控制子进程环境。提供该项时，子进程不会继承 `os.environ`。 +- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则 SDK 会先从 `PATH` 解析 `codex`，然后回退到捆绑的 vendor 二进制文件。 +- 环境：`codex_options.env` 完全控制子进程环境。提供该选项时，子进程不会继承 `os.environ`。 - 流限制：`codex_options.codex_subprocess_stream_limit_bytes`（或 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）控制 stdout/stderr 读取器限制。有效范围为 `65536` 到 `67108864`；默认值为 `8388608`。 - 流式传输：`on_stream` 接收线程/轮次生命周期事件和条目事件（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list` 和 `error` 条目更新）。 -- 输出：结果包含 `response`、`usage` 和 `thread_id`；usage 会添加到 `RunContextWrapper.usage`。 +- 输出：结果包括 `response`、`usage` 和 `thread_id`；usage 会添加到 `RunContextWrapper.usage`。 参考： - [Codex 工具 API 参考](ref/extensions/experimental/codex/codex_tool.md) - [ThreadOptions 参考](ref/extensions/experimental/codex/thread_options.md) - [TurnOptions 参考](ref/extensions/experimental/codex/turn_options.md) -- 请参阅 `examples/tools/codex.py` 和 `examples/tools/codex_same_thread.py`，了解完整可运行示例。 \ No newline at end of file +- 参见 `examples/tools/codex.py` 和 `examples/tools/codex_same_thread.py` 获取完整可运行示例。 \ No newline at end of file diff --git a/docs/zh/tracing.md b/docs/zh/tracing.md index aeab01af41..0b8d3321e0 100644 --- a/docs/zh/tracing.md +++ b/docs/zh/tracing.md @@ -4,61 +4,60 @@ 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. 你可以在代码中使用 [`set_tracing_disabled(True)`][agents.set_tracing_disabled] 全局禁用追踪 - 3. 你可以通过将 [`agents.run.RunConfig.tracing_disabled`][] 设置为 `True` 来为单次运行禁用追踪 + 3. 你可以通过将 [`agents.run.RunConfig.tracing_disabled`][] 设置为 `True`，为单次运行禁用追踪 -***对于在 Zero Data Retention (ZDR) 策略下使用 OpenAI API 的组织，追踪不可用。*** +***对于使用OpenAI的API且遵循零数据保留（ZDR）政策的组织，追踪不可用。*** -## Traces 和 spans +## 追踪和Span -- **Traces** 表示“工作流”的单个端到端操作。它们由 Span 组成。Traces 具有以下属性： +- **追踪（Traces）**表示一次“工作流”的端到端操作。它们由Span组成。追踪具有以下属性： - `workflow_name`：这是逻辑工作流或应用。例如“代码生成”或“客户服务”。 - - `trace_id`：Trace 的唯一 ID。如果你未传入，则会自动生成。格式必须为 `trace_<32_alphanumeric>`。 - - `group_id`：可选的分组 ID，用于关联同一会话中的多个 trace。例如，你可以使用聊天线程 ID。 - - `disabled`：如果为 True，则不会记录该 trace。 - - `metadata`：trace 的可选元数据。 -- **Spans** 表示具有开始时间和结束时间的操作。Span 具有： + - `trace_id`：追踪的唯一ID。如果未传入，会自动生成。格式必须为 `trace_<32_alphanumeric>`。 + - `group_id`：可选的组ID，用于关联来自同一对话的多个追踪。例如，你可以使用聊天线程ID。 + - `disabled`：如果为 True，则不会记录该追踪。 + - `metadata`：追踪的可选元数据。 +- **Span**表示具有开始和结束时间的操作。Span具有： - `started_at` 和 `ended_at` 时间戳。 - - `trace_id`，表示它们所属的 trace - - `parent_id`，指向该 Span 的父 Span（如果有） - - `span_data`，即有关该 Span 的信息。例如，`AgentSpanData` 包含有关 Agent 的信息，`GenerationSpanData` 包含有关 LLM 生成的信息，等等。 + - `trace_id`，表示它们所属的追踪 + - `parent_id`，指向此Span的父Span（如果有） + - `span_data`，即有关该Span的信息。例如，`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()` 中 +- LLM生成会包装在 `generation_span()` 中 +- 每个函数工具调用都会包装在 `function_span()` 中 - 安全防护措施会包装在 `guardrail_span()` 中 - 任务转移会包装在 `handoff_span()` 中 - 音频输入（语音转文本）会包装在 `transcription_span()` 中 - 音频输出（文本转语音）会包装在 `speech_span()` 中 -- 相关的音频 span 可能会作为 `speech_group_span()` 的子项 +- 相关音频Span可能会以 `speech_group_span()` 为父级 -默认情况下，trace 名称为“Agent workflow”。如果你使用 `trace`，可以设置该名称；也可以使用 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 +默认情况下，追踪名为“Agent workflow”。如果使用 `trace`，你可以设置此名称；也可以使用 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 -此外，你还可以设置[自定义追踪处理器](#custom-tracing-processors)，将 trace 推送到其他目标位置（作为替代目标或次级目标）。 +此外，你可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪推送到其他目标位置（作为替代目标或辅助目标）。 -## 长时间运行的 worker 与即时导出 +## 长时间运行的工作进程与即时导出 -默认的 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 会在后台每隔几秒导出一次 traces， -或者当内存队列达到其大小触发阈值时更快导出， +默认的 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 会每隔几秒在后台导出追踪， +或者在内存队列达到其大小触发阈值时更早导出， 并且还会在进程退出时执行最终刷新。在 Celery、 -RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的 worker 中，这意味着 traces 通常会自动导出， -无需额外代码，但它们可能不会在每个作业 -完成后立即出现在 Traces 仪表板中。 +RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的工作进程中，这意味着追踪通常会自动导出， +无需任何额外代码，但它们可能不会在每个作业完成后立即出现在 Traces 仪表板中。 -如果你需要在一个工作单元结束时立即投递的保证，请在 -trace 上下文退出后调用 [`flush_traces()`][agents.tracing.flush_traces]。 +如果你需要在一个工作单元结束时获得即时交付保证，请在追踪上下文退出后调用 +[`flush_traces()`][agents.tracing.flush_traces]。 ```python from agents import Runner, flush_traces, trace @@ -95,14 +94,13 @@ async def run(prompt: str, background_tasks: BackgroundTasks): return {"status": "queued"} ``` -[`flush_traces()`][agents.tracing.flush_traces] 会阻塞，直到当前缓冲的 traces 和 spans -被导出，因此请在 `trace()` 关闭后调用它，以避免刷新尚未完全构建的 trace。若默认的 -导出延迟可以接受，则可以跳过 -此调用。 +[`flush_traces()`][agents.tracing.flush_traces] 会阻塞，直到当前缓冲的追踪和Span +导出完成，因此请在 `trace()` 关闭后调用它，以避免刷新尚未完全构建的追踪。如果默认导出延迟可以接受， +则可以跳过此调用。 -## 更高层级的 traces +## 更高层级的追踪 -有时，你可能希望多次调用 `run()` 属于同一个 trace。你可以通过将整个代码包装在 `trace()` 中来实现。 +有时，你可能希望对 `run()` 的多次调用成为单个追踪的一部分。你可以通过将整个代码包装在 `trace()` 中来实现。 ```python from agents import Agent, Runner, trace @@ -117,49 +115,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 因为这两次对 `Runner.run` 的调用被包装在 `with trace()` 中，所以这些单独的运行将成为整体 trace 的一部分，而不是创建两个 trace。 +1. 因为对 `Runner.run` 的两次调用都包装在 `with trace()` 中，所以各个运行会成为整体追踪的一部分，而不是创建两个追踪。 -## 创建 traces +## 追踪的创建 -你可以使用 [`trace()`][agents.tracing.trace] 函数创建 trace。Trace 需要被启动和结束。你有两种方式： +你可以使用 [`trace()`][agents.tracing.trace] 函数创建追踪。追踪需要启动和结束。你有两个选项可以做到这一点： -1. **推荐**：将 trace 用作上下文管理器，即 `with trace(...) as my_trace`。这样会在正确的时间自动启动和结束 trace。 +1. **推荐**：将追踪用作上下文管理器，即 `with trace(...) as my_trace`。这会在正确的时间自动启动和结束追踪。 2. 你也可以手动调用 [`trace.start()`][agents.tracing.Trace.start] 和 [`trace.finish()`][agents.tracing.Trace.finish]。 -当前 trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。这意味着它能够自动适配并发。如果你手动启动/结束 trace，则需要向 `start()`/`finish()` 传递 `mark_as_current` 和 `reset_current` 以更新当前 trace。 +当前追踪通过 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行记录。这意味着它可以自动适配并发场景。如果你手动启动/结束追踪，需要向 `start()`/`finish()` 传入 `mark_as_current` 和 `reset_current`，以更新当前追踪。 -## 创建 spans +## Span的创建 -你可以使用各种 [`*_span()`][agents.tracing.create] 方法创建 span。通常，你不需要手动创建 span。也提供了 [`custom_span()`][agents.tracing.custom_span] 函数，用于跟踪自定义 span 信息。 +你可以使用各种 [`*_span()`][agents.tracing.create] 方法来创建Span。一般来说，你不需要手动创建Span。可以使用 [`custom_span()`][agents.tracing.custom_span] 函数来记录自定义Span信息。 -Span 会自动归属于当前 trace，并嵌套在最近的当前 span 之下，而这个当前 span 是通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪的。 +Span会自动成为当前追踪的一部分，并嵌套在最近的当前Span下；最近的当前Span通过 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行记录。 ## 敏感数据 -某些 span 可能会捕获潜在的敏感数据。 +某些Span可能会捕获潜在敏感数据。 -`generation_span()` 会存储 LLM 生成的输入/输出，而 `function_span()` 会存储函数调用的输入/输出。这些内容可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用对这些数据的捕获。 +`generation_span()` 会存储LLM生成的输入/输出，`function_span()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用对此类数据的捕获。 -同样，音频 span 默认会包含输入和输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 来禁用对这些音频数据的捕获。 +同样，默认情况下，音频Span包含输入和输出音频的 base64 编码PCM数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 来禁用对此音频数据的捕获。 -默认情况下，`trace_include_sensitive_data` 为 `True`。你也可以在不修改代码的情况下，通过在运行应用前将 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 环境变量导出为 `true/1` 或 `false/0` 来设置默认值。 +默认情况下，`trace_include_sensitive_data` 为 `True`。你可以在运行应用之前导出 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 环境变量并将其设为 `true/1` 或 `false/0`，从而无需代码即可设置默认值。 -## 自定义追踪处理器 +## 自定义追踪进程 追踪的高层架构如下： -- 初始化时，我们会创建一个全局的 [`TraceProvider`][agents.tracing.setup.TraceProvider]，它负责创建 traces。 -- 我们会为 `TraceProvider` 配置一个 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，它会将 traces/spans 分批发送给 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者再将 spans 和 traces 分批导出到 OpenAI 后端。 +- 初始化时，我们会创建一个全局 [`TraceProvider`][agents.tracing.setup.TraceProvider]，它负责创建追踪。 +- 我们使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 配置 `TraceProvider`，后者会将追踪/Span批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]；该导出器会将Span和追踪批量导出到OpenAI后端。 -若要自定义这一默认设置，将 traces 发送到替代或附加后端，或修改导出器行为，你有两个选项： +若要自定义此默认设置，将追踪发送到替代或额外后端，或修改导出器行为，你有两个选项： -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外的**追踪处理器，它会在 traces 和 spans 就绪时接收它们。这样你就可以在将 traces 发送到 OpenAI 后端之外，执行自己的处理。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪处理器**替换**默认处理器。这意味着 traces 不会发送到 OpenAI 后端，除非你包含一个会执行该操作的 `TracingProcessor`。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外**的追踪进程，它会在追踪和Span就绪时接收它们。这样除了将追踪发送到OpenAI后端外，你还可以执行自己的处理。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着，除非你包含一个会执行此操作的 `TracingProcessor`，否则追踪不会发送到OpenAI后端。 -## 非 OpenAI 模型的追踪 +## 非OpenAI模型的追踪 -你可以将 OpenAI API key 与非 OpenAI 模型一起使用，从而在无需禁用追踪的情况下，于 OpenAI Traces 仪表板中启用免费追踪。有关适配器选择和设置注意事项，请参阅 Models 指南中的[第三方适配器](models/index.md#third-party-adapters)部分。 +你可以将OpenAI API密钥与非OpenAI模型一起使用，以在OpenAI Traces 仪表板中启用免费追踪，而无需禁用追踪。有关适配器选择和设置注意事项，请参阅模型指南中的[第三方适配器](models/index.md#third-party-adapters)部分。 ```python import os @@ -180,7 +178,7 @@ agent = Agent( ) ``` -如果你只需要为单次运行使用不同的追踪 key，请通过 `RunConfig` 传递，而不是更改全局导出器。 +如果你只需要为单次运行使用不同的追踪密钥，请通过 `RunConfig` 传入，而不是更改全局导出器。 ```python from agents import Runner, RunConfig @@ -192,15 +190,15 @@ await Runner.run( ) ``` -## 附加说明 -- 在 Openai Traces 仪表板查看免费 traces。 +## 其他说明 +- 在Openai Traces 仪表板查看免费追踪。 ## 生态系统集成 -以下社区和供应商集成支持 OpenAI Agents SDK 的追踪接口。 +以下社区和供应商集成支持OpenAI Agents SDK的追踪接口。 -### 外部追踪处理器列表 +### 外部追踪进程列表 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) diff --git a/docs/zh/usage.md b/docs/zh/usage.md index 743098f221..734db884e2 100644 --- a/docs/zh/usage.md +++ b/docs/zh/usage.md @@ -2,24 +2,24 @@ search: exclude: true --- -# 用法 +# 用量 -Agents SDK 会自动追踪每次运行的 token 使用情况。你可以从运行上下文中访问这些数据，并用它来监控成本、执行限制或记录分析数据。 +Agents SDK 会自动跟踪每次运行的 token 用量。你可以从运行上下文中访问它，并用它来监控成本、执行限制或记录分析数据。 -## 追踪内容 +## 跟踪内容 - **requests**: 发起的 LLM API 调用次数 - **input_tokens**: 发送的输入 token 总数 - **output_tokens**: 接收的输出 token 总数 - **total_tokens**: 输入 + 输出 -- **request_usage_entries**: 按请求划分的使用明细列表 +- **request_usage_entries**: 按请求列出的用量明细列表 - **details**: - `input_tokens_details.cached_tokens` - `output_tokens_details.reasoning_tokens` -## 从一次运行中访问使用情况 +## 运行中的用量访问 -在 `Runner.run(...)` 之后，可通过 `result.context_wrapper.usage` 访问使用情况。 +在 `Runner.run(...)` 之后，通过 `result.context_wrapper.usage` 访问用量。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -31,20 +31,20 @@ print("Output tokens:", usage.output_tokens) print("Total tokens:", usage.total_tokens) ``` -使用量会汇总该次运行期间所有模型调用（包括工具调用和任务转移）。 +用量会汇总运行期间的所有模型调用（包括工具调用和任务转移）。 -### 在第三方适配器中启用使用情况追踪 +### 第三方适配器中的用量启用 -不同第三方适配器和提供方后端的使用情况上报方式有所不同。如果你依赖由适配器支持的模型并且需要准确的 `result.context_wrapper.usage` 值： +不同第三方适配器和提供方后端的用量报告方式各不相同。如果你依赖适配器支持的模型，并且需要准确的 `result.context_wrapper.usage` 值： -- 使用 `AnyLLMModel` 时，如果上游提供方返回了使用数据，则会自动透传。对于流式 Chat Completions 后端，在发出 usage 分块前，你可能需要设置 `ModelSettings(include_usage=True)`。 -- 使用 `LitellmModel` 时，某些提供方后端默认不会上报使用数据，因此通常需要 `ModelSettings(include_usage=True)`。 +- 使用 `AnyLLMModel` 时，只要上游提供方返回用量，用量就会自动传递。对于流式传输的 Chat Completions 后端，你可能需要在发出用量块之前设置 `ModelSettings(include_usage=True)`。 +- 使用 `LitellmModel` 时，某些提供方后端默认不报告用量，因此通常需要 `ModelSettings(include_usage=True)`。 -请查看 Models 指南中[第三方适配器](models/index.md#third-party-adapters)章节的适配器说明，并验证你计划部署的具体提供方后端。 +请查看 Models 指南中[第三方适配器](models/index.md#third-party-adapters)部分的适配器特定说明，并验证你计划部署的具体提供方后端。 -## 按请求追踪使用情况 +## 按请求的用量跟踪 -SDK 会自动在 `request_usage_entries` 中追踪每个 API 请求的使用情况，这对精细化成本计算和上下文窗口消耗监控很有帮助。 +SDK 会在 `request_usage_entries` 中自动跟踪每个 API 请求的用量，这对详细成本计算和上下文窗口消耗监控很有用。 ```python result = await Runner.run(agent, "What's the weather in Tokyo?") @@ -53,9 +53,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries): print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out") ``` -## 在会话中访问使用情况 +## 会话中的用量访问 -当你使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该次运行对应的使用数据。会话会维护对话历史以提供上下文，但每次运行的使用数据彼此独立。 +使用 `Session`（例如 `SQLiteSession`）时，每次调用 `Runner.run(...)` 都会返回该特定运行的用量。会话会维护对话历史作为上下文，但每次运行的用量都是独立的。 ```python session = SQLiteSession("my_conversation") @@ -67,11 +67,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session) print(second.context_wrapper.usage.total_tokens) # Usage for second run ``` -请注意，尽管会话会在多次运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的使用指标只代表该次执行。在会话中，先前消息可能会在每次运行时作为输入再次传入，这会影响后续轮次的输入 token 计数。 +请注意，虽然会话会在运行之间保留对话上下文，但每次 `Runner.run()` 调用返回的用量指标仅代表该次特定执行。在会话中，先前的消息可能会作为输入重新提供给每次运行，这会影响后续轮次中的输入 token 数量。 -## 在 hooks 中使用使用情况 +## 钩子中的用量使用 -如果你使用 `RunHooks`，传递给每个 hook 的 `context` 对象都包含 `usage`。这使你可以在关键生命周期节点记录使用情况。 +如果你使用 `RunHooks`，传递给每个钩子的 `context` 对象会包含 `usage`。这使你可以在关键生命周期时刻记录用量。 ```python class MyHooks(RunHooks): @@ -82,9 +82,9 @@ class MyHooks(RunHooks): ## API 参考 -详细 API 文档请参见： +有关详细的 API 文档，请参阅： -- [`Usage`][agents.usage.Usage] - 使用情况追踪数据结构 -- [`RequestUsage`][agents.usage.RequestUsage] - 按请求划分的使用详情 -- [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问使用情况 -- [`RunHooks`][agents.run.RunHooks] - 挂接到使用情况追踪生命周期 \ No newline at end of file +- [`Usage`][agents.usage.Usage] - 用量跟踪数据结构 +- [`RequestUsage`][agents.usage.RequestUsage] - 按请求的用量详情 +- [`RunContextWrapper`][agents.run.RunContextWrapper] - 从运行上下文访问用量 +- [`RunHooks`][agents.run.RunHooks] - 接入用量跟踪生命周期 \ No newline at end of file diff --git a/docs/zh/visualization.md b/docs/zh/visualization.md index b67fb5a529..9526b30640 100644 --- a/docs/zh/visualization.md +++ b/docs/zh/visualization.md @@ -4,7 +4,7 @@ search: --- # 智能体可视化 -智能体可视化允许你使用 **Graphviz** 生成智能体及其关系的结构化图形表示。这有助于理解智能体、工具调用和任务转移在应用中的交互方式。 +智能体可视化允许你使用**Graphviz**生成智能体及其关系的结构化图形表示。这有助于理解智能体、工具和任务转移在应用程序中的交互方式。 ## 安装 @@ -14,16 +14,16 @@ search: pip install "openai-agents[viz]" ``` -## 生成图 +## 图形生成 你可以使用 `draw_graph` 函数生成智能体可视化。该函数会创建一个有向图，其中： -- **智能体** 以黄色方框表示。 -- **MCP 服务** 以灰色方框表示。 -- **工具调用** 以绿色椭圆表示。 -- **任务转移** 是从一个智能体指向另一个智能体的有向边。 +- **智能体**表示为黄色方框。 +- **MCP 服务**表示为灰色方框。 +- **工具**表示为绿色椭圆。 +- **任务转移**表示为从一个智能体指向另一个智能体的有向边。 -### 使用示例 +### 示例用法 ```python import os @@ -67,43 +67,43 @@ triage_agent = Agent( draw_graph(triage_agent) ``` -![Agent Graph](../assets/images/graph.png) +![智能体图](../assets/images/graph.png) -这会生成一张图，直观展示**分诊智能体**及其与子智能体和工具的连接关系。 +这会生成一个图形，用于直观展示**分流智能体**的结构，以及它与子智能体和工具之间的连接。 -## 理解可视化 +## 可视化理解 生成的图包括： -- 一个 **起始节点**（`__start__`），表示入口点。 +- 一个**起始节点**（`__start__`），表示入口点。 - 以黄色填充的**矩形**表示的智能体。 - 以绿色填充的**椭圆**表示的工具。 - 以灰色填充的**矩形**表示的 MCP 服务。 - 表示交互的有向边： - - 智能体到智能体任务转移使用**实线箭头**。 - - 工具调用使用**点线箭头**。 - - MCP 服务调用使用**虚线箭头**。 -- 一个 **结束节点**（`__end__`），表示执行终止的位置。 + - **实线箭头**表示智能体之间的任务转移。 + - **点线箭头**表示工具调用。 + - **虚线箭头**表示 MCP 服务调用。 +- 一个**结束节点**（`__end__`），表示执行终止的位置。 -**注意：** MCP 服务会在较新版本的 -`agents` 包中渲染（已在 **v0.2.8** 验证）。如果你在可视化中看不到 MCP 方框， +**注意：** MCP 服务会在近期版本的 +`agents` 包中渲染（已在 **v0.2.8** 中验证）。如果你在可视化中没有看到 MCP 方框， 请升级到最新版本。 -## 自定义图 +## 图形自定义 -### 显示图 -默认情况下，`draw_graph` 会以内联方式显示图。若要在单独窗口中显示图，请写入以下内容： +### 图形显示 +默认情况下，`draw_graph` 会以内联方式显示图形。若要在单独窗口中显示图形，请编写如下代码： ```python draw_graph(triage_agent).view() ``` -### 保存图 -默认情况下，`draw_graph` 会以内联方式显示图。若要将其保存为文件，请指定文件名： +### 图形保存 +默认情况下，`draw_graph` 会以内联方式显示图形。若要将其保存为文件，请指定文件名： ```python draw_graph(triage_agent, filename="agent_graph") ``` -这会在工作目录中生成 `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 5da6db6700..22cc9ea790 100644 --- a/docs/zh/voice/pipeline.md +++ b/docs/zh/voice/pipeline.md @@ -4,7 +4,7 @@ search: --- # 管道与工作流 -[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个类，可让你轻松将智能体工作流转换为语音应用。你传入一个要运行的工作流，管道会负责转录输入音频、检测音频何时结束、在适当的时机调用你的工作流，并将工作流输出重新转换为音频。 +[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] 是一个类，可让你轻松将智能体工作流转换为语音应用。你传入要运行的工作流，管道会负责转录输入音频、检测音频何时结束、在合适的时间调用你的工作流，并将工作流输出转换回音频。 ```mermaid graph LR @@ -34,29 +34,29 @@ graph LR ## 管道配置 -创建管道时，你可以设置以下内容： +创建管道时，你可以设置以下几项： -1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]，即每次转录出新音频时运行的代码。 +1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]，也就是每次有新音频被转录时运行的代码。 2. 所使用的 [`speech-to-text`][agents.voice.model.STTModel] 和 [`text-to-speech`][agents.voice.model.TTSModel] 模型 -3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]，用于配置以下内容： +3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]，可让你配置以下内容： - 模型提供方，可将模型名称映射到模型 - 追踪，包括是否禁用追踪、是否上传音频文件、工作流名称、追踪 ID 等 - - TTS 和 STT 模型上的设置，例如所使用的提示词、语言和数据类型。 + - TTS 和 STT 模型的设置，例如所使用的提示词、语言和数据类型。 ## 管道运行 -你可以通过 [`run()`][agents.voice.pipeline.VoicePipeline.run] 方法运行管道，该方法支持传入两种形式的音频输入： +你可以通过 [`run()`][agents.voice.pipeline.VoicePipeline.run] 方法运行管道，该方法允许你以两种形式传入音频输入： -1. 当你拥有完整的音频转录内容，并且只想基于它生成结果时，使用 [`AudioInput`][agents.voice.input.AudioInput]。这适用于不需要检测说话者何时说完的场景；例如，你有预录音频，或者在按键说话应用中，用户何时说完是明确的。 -2. 当你可能需要检测用户何时说完时，使用 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]。它允许你在检测到音频分块时持续推送这些分块，语音管道会通过称为“活动检测”的过程，在适当的时机自动运行智能体工作流。 +1. [`AudioInput`][agents.voice.input.AudioInput] 用于你已有完整音频转录，并且只想为其生成结果的场景。当你不需要检测说话者何时说完时，这会很有用；例如，在已有预录音频的情况下，或在按住说话的应用中，用户何时说完是明确的。 +2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 用于你可能需要检测用户何时说完的场景。它允许你在检测到音频片段时将其推送进去，语音管道会通过一个名为“活动检测”的过程，在合适的时间自动运行智能体工作流。 ## 结果 -语音管道运行的结果是一个 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]。这是一个允许你在事件发生时进行流式传输的对象。存在几种 [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent]，包括： +语音管道运行的结果是 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]。这是一个对象，可让你在事件发生时以流式方式获取它们。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] 有几种类型，包括： -1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]，其中包含一段音频分块。 -2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]，用于通知你诸如轮次开始或结束之类的生命周期事件。 -3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]，即错误事件。 +1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]，其中包含一段音频。 +2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]，它会通知你生命周期事件，例如一个轮次开始或结束。 +3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]，这是一个错误事件。 ```python @@ -74,6 +74,6 @@ async for event in result.stream(): ## 最佳实践 -### 中断 +### 中断处理 -Agents SDK 当前不为 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 提供任何内置的中断处理。相反，对于每个检测到的轮次，它都会触发一次单独的工作流运行。如果你希望在应用内部处理中断，可以监听 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 事件。`turn_started` 表示新的轮次已被转录并开始处理。`turn_ended` 会在某个轮次的所有音频都被分发后触发。你可以利用这些事件，在模型开始一个轮次时将说话者的麦克风静音，并在你刷新完该轮次的所有相关音频后取消静音。 \ No newline at end of file +Agents SDK 目前没有为 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] 提供任何内置的中断处理。相反，对于每个检测到的轮次，它都会触发一次单独的工作流运行。如果你想在应用内部处理中断，可以监听 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 事件。`turn_started` 表示一个新的轮次已被转录并且处理即将开始。`turn_ended` 会在相应轮次的所有音频都已分发后触发。你可以使用这些事件，在模型开始一个轮次时将说话者的麦克风静音，并在该轮次的所有相关音频都已发送完毕后取消静音。 \ No newline at end of file diff --git a/docs/zh/voice/quickstart.md b/docs/zh/voice/quickstart.md index b4c9023d68..3264ad9080 100644 --- a/docs/zh/voice/quickstart.md +++ b/docs/zh/voice/quickstart.md @@ -4,9 +4,9 @@ search: --- # 快速入门 -## 先决条件 +## 前提条件 -请确保你已按照 Agents SDK 的基础[快速入门说明](../quickstart.md)完成设置，并配置好虚拟环境。然后，安装 SDK 中可选的语音依赖项： +请确保你已按照 Agents SDK 的基础[快速入门说明](../quickstart.md)完成设置，并设置好虚拟环境。然后，从 SDK 安装可选的语音依赖项： ```bash pip install 'openai-agents[voice]' @@ -14,10 +14,10 @@ pip install 'openai-agents[voice]' ## 概念 -需要了解的主要概念是 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]，它是一个 3 步流程： +需要了解的主要概念是 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]，它是一个三步流程： 1. 运行语音转文本模型，将音频转换为文本。 -2. 运行你的代码（通常是一个智能体工作流）以生成结果。 +2. 运行你的代码（通常是一个智能体式工作流）以生成结果。 3. 运行文本转语音模型，将结果文本转换回音频。 ```mermaid @@ -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 af634e7d26..5fddd2e9d1 100644 --- a/docs/zh/voice/tracing.md +++ b/docs/zh/voice/tracing.md @@ -4,15 +4,15 @@ search: --- # 追踪 -就像[智能体如何被追踪](../tracing.md)一样，语音管道也会被自动追踪。 +就像[智能体会被追踪](../tracing.md)一样，语音管线也会被自动追踪。 -你可以阅读上面的追踪文档以了解基础追踪信息，但你还可以通过 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] 额外配置管道的追踪。 +你可以阅读上面的追踪文档以了解基本的追踪信息；此外，你还可以通过[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]配置管线的追踪。 与追踪相关的关键字段包括： -- [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]：控制是否禁用追踪。默认启用追踪。 -- [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]：控制追踪中是否包含潜在敏感数据，例如音频转写文本。这仅适用于语音管道，而不适用于你的 Workflow 内部发生的任何内容。 -- [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]：控制追踪中是否包含音频数据。 +- [`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.trace_metadata]：要随追踪一并包含的附加元数据。 \ No newline at end of file +- [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]：追踪的`group_id`，可用于关联多个追踪。 +- [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.trace_metadata]：要包含在追踪中的额外元数据。 \ No newline at end of file diff --git a/uv.lock b/uv.lock index a6900a6701..e52cdb6636 100644 --- a/uv.lock +++ b/uv.lock @@ -9,8 +9,7 @@ resolution-markers = [ ] [options] -exclude-newer = "2026-05-04T22:31:23.151060131Z" -exclude-newer-span = "P7D" +exclude-newer = "2026-05-05T23:48:07Z" [[package]] name = "aiofiles"