diff --git a/docs/ja/examples.md b/docs/ja/examples.md
index 4d6bdb4ac5..dbe84067a5 100644
--- a/docs/ja/examples.md
+++ b/docs/ja/examples.md
@@ -4,99 +4,99 @@ search:
---
# コード例
-[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装をご確認ください。examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。
+[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装を確認できます。examples は、異なるパターンと機能を示す複数のカテゴリーに整理されています。
## カテゴリー
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
- このカテゴリーのコード例では、一般的なエージェント設計パターンを示しています。たとえば次のとおりです。
+ このカテゴリーのコード例では、一般的なエージェント設計パターンを示しています。例:
- 決定論的ワークフロー
- Agents as tools
- エージェントの並列実行
- 条件付きツール使用
- - 入出力ガードレール
+ - 入力/出力ガードレール
- 審判としての LLM
- ルーティング
- ストリーミングガードレール
- 承認フロー向けのカスタム拒否メッセージ (`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 、 open-weight モデル)
- エージェントライフサイクル管理
- 動的システムプロンプト
- ストリーミング出力 (テキスト、項目、関数呼び出し引数)
- - ターン間で共有セッションヘルパーを使用する Responses websocket transport (`examples/basic/stream_ws.py`)
+ - ターン間で共有セッションヘルパーを使う Responses websocket トランスポート (`examples/basic/stream_ws.py`)
- プロンプトテンプレート
- - ファイル処理 (ローカルおよびリモート、画像および PDF)
+ - ファイル処理 (ローカル/リモート、画像/PDF)
- 使用状況トラッキング
- - Runner 管理の再試行設定 (`examples/basic/retry.py`)
- - LiteLLM を使用した Runner 管理の再試行 (`examples/basic/retry_litellm.py`)
+ - Runner 管理のリトライ設定 (`examples/basic/retry.py`)
+ - サードパーティアダプターを介した Runner 管理のリトライ (`examples/basic/retry_litellm.py`)
- 非 strict な出力型
- - 以前のレスポンス ID の使用
+ - 前回レスポンス ID の使用
- **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
航空会社向けのカスタマーサービスシステムのコード例です。
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
- 金融データ分析向けに、エージェントとツールを使った構造化リサーチワークフローを示す金融リサーチエージェントです。
+ 金融データ分析のためのエージェントとツールを使った構造化リサーチワークフローを示す、金融リサーチエージェントです。
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
- メッセージフィルタリングを使ったエージェントハンドオフの実践的なコード例をご覧ください。
+ メッセージフィルタリングを伴うエージェントハンドオフの実践的なコード例をご覧ください。
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
- ホストされた MCP (Model context protocol) コネクタと承認の使い方を示すコード例です。
+ hosted MCP (Model Context Protocol) コネクターと承認の使い方を示すコード例です。
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
- MCP (Model context protocol) を使ってエージェントを構築する方法を学べます。内容は次のとおりです。
+ MCP (Model Context Protocol) を使ってエージェントを構築する方法を学べます。内容:
- ファイルシステムのコード例
- Git のコード例
- MCP プロンプトサーバーのコード例
- SSE (Server-Sent Events) のコード例
- - ストリーム可能な HTTP のコード例
+ - ストリーミング可能な HTTP のコード例
- **[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`)
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
- カスタムプロバイダーや LiteLLM 統合を含め、 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 のアタッチフローを使う Twilio SIP 統合
+ - Realtime Calls API attach フローを使用した Twilio SIP 統合
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
reasoning content と structured outputs の扱い方を示すコード例です。
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
- 複雑なマルチエージェントのリサーチワークフローを示す、シンプルなディープリサーチクローンです。
+ 複雑なマルチエージェントのディープリサーチワークフローを示す、シンプルなディープリサーチクローンです。
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
- 次のような OpenAI がホストするツールと実験的な Codex ツール機能の実装方法を学べます。
+ OpenAI がホストするツールと、次のような実験的な Codex ツール機能の実装方法を学べます。
- Web 検索 とフィルター付き Web 検索
- ファイル検索
- Code Interpreter
- - インラインスキル付きホストコンテナーシェル (`examples/tools/container_shell_inline_skill.py`)
- - スキル参照付きホストコンテナーシェル (`examples/tools/container_shell_skill_reference.py`)
- - ローカルスキル付きローカルシェル (`examples/tools/local_shell_skill.py`)
+ - インラインスキル付き hosted container shell (`examples/tools/container_shell_inline_skill.py`)
+ - スキル参照付き hosted container shell (`examples/tools/container_shell_skill_reference.py`)
+ - ローカルスキル付きローカル shell (`examples/tools/local_shell_skill.py`)
- 名前空間と遅延ツールを使ったツール検索 (`examples/tools/tool_search.py`)
- コンピュータ操作
- 画像生成
@@ -104,4 +104,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/ja/models/index.md b/docs/ja/models/index.md
index f221dbd95c..4e8a239deb 100644
--- a/docs/ja/models/index.md
+++ b/docs/ja/models/index.md
@@ -4,42 +4,42 @@ search:
---
# モデル
-Agents SDK には、OpenAI モデルをすぐに使える形で 2 つの方式でサポートしています。
+Agents SDK には、 OpenAI モデル向けの即時利用可能なサポートが 2 つの形で用意されています。
-- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使って OpenAI API を呼び出します。
-- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使って OpenAI API を呼び出します。
+- **推奨**: [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出します。
+- [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出します。
## モデル設定の選択
-ご利用の構成に合う最もシンプルな経路から始めてください。
+まずは、構成に合う最もシンプルな方法から始めてください。
-| 目的 | 推奨経路 | 詳細 |
+| 次のことをしたい場合 | 推奨パス | 詳細 |
| --- | --- | --- |
-| OpenAI モデルのみを使う | デフォルトの OpenAI provider と Responses モデル経路を使う | [OpenAI モデル](#openai-models) |
-| websocket 転送で OpenAI Responses API を使う | Responses モデル経路を維持し、websocket 転送を有効化する | [Responses WebSocket 転送](#responses-websocket-transport) |
-| 1 つの non-OpenAI provider を使う | 組み込みの provider 統合ポイントから始める | [non-OpenAI モデル](#non-openai-models) |
-| エージェント間でモデルや provider を混在させる | 実行単位またはエージェント単位で provider を選び、機能差を確認する | [1 つのワークフロー内でのモデル混在](#mixing-models-in-one-workflow) および [provider 間でのモデル混在](#mixing-models-across-providers) |
-| OpenAI Responses の高度なリクエスト設定を調整する | OpenAI Responses 経路で `ModelSettings` を使う | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) |
-| non-OpenAI Chat Completions provider に LiteLLM を使う | LiteLLM を beta のフォールバックとして扱う | [LiteLLM](#litellm) |
+| 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) |
## OpenAI モデル
-ほとんどの OpenAI 専用アプリでは、デフォルトの OpenAI provider と文字列のモデル名を使い、Responses モデル経路を維持する方法を推奨します。
+ほとんどの OpenAI 専用アプリでは、既定の OpenAI プロバイダーで文字列のモデル名を使い、 Responses モデルパスを使い続けるのが推奨です。
-`Agent` 初期化時にモデルを指定しない場合は、デフォルトモデルが使われます。現在のデフォルトは互換性と低遅延のため [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) です。利用可能であれば、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) をエージェントに設定することを推奨します。
+`Agent` 初期化時にモデルを指定しない場合は、既定モデルが使われます。現在の既定は互換性と低レイテンシのため [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) です。利用可能な場合は、明示的な `model_settings` を維持したまま、より高品質な [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) にエージェントを設定することを推奨します。
-[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような他モデルに切り替えるには、エージェントを設定する方法が 2 つあります。
+[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような他モデルへ切り替えるには、エージェントの設定方法が 2 つあります。
-### デフォルトモデル
+### 既定モデル
-まず、カスタムモデルを設定しないすべてのエージェントで特定モデルを一貫して使いたい場合は、エージェント実行前に `OPENAI_DEFAULT_MODEL` 環境変数を設定します。
+1 つ目として、カスタムモデルを設定しないすべてのエージェントで特定モデルを一貫して使いたい場合は、エージェント実行前に環境変数 `OPENAI_DEFAULT_MODEL` を設定します。
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.4
python3 my_awesome_agent.py
```
-次に、`RunConfig` で実行ごとのデフォルトモデルを設定できます。エージェントにモデルを設定しなければ、この実行のモデルが使われます。
+2 つ目として、 `RunConfig` で実行単位の既定モデルを設定できます。エージェントにモデルを設定しなければ、この実行のモデルが使われます。
```python
from agents import Agent, RunConfig, Runner
@@ -58,7 +58,7 @@ result = await Runner.run(
#### GPT-5 モデル
-この方法で [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) のような GPT-5 モデルを使う場合、SDK はデフォルトの `ModelSettings` を適用します。多くのユースケースで最適に動く設定が使われます。デフォルトモデルの推論 effort を調整するには、独自の `ModelSettings` を渡します。
+この方法で [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) などの GPT-5 モデルを使う場合、 SDK は既定の `ModelSettings` を適用します。これは多くのユースケースで最適に動く設定です。既定モデルの推論 effort を調整するには、独自の `ModelSettings` を渡してください。
```python
from openai.types.shared import Reasoning
@@ -74,21 +74,21 @@ my_agent = Agent(
)
```
-低遅延のためには、`gpt-5.4` で `reasoning.effort="none"` を使うことを推奨します。gpt-4.1 ファミリー（ mini / nano を含む）も、対話型エージェントアプリ構築において有力な選択肢です。
+低レイテンシには、 `gpt-5.4` で `reasoning.effort="none"` を使うことを推奨します。 gpt-4.1 ファミリー（ mini と nano を含む）も、対話型エージェントアプリ構築において引き続き有力な選択肢です。
#### ComputerTool モデル選択
-エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.4` リクエストでは GA の組み込み `computer` ツールを使い、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードを維持します。
+エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、 SDK が送信するコンピュータツール payload が決まります。明示的な `gpt-5.4` リクエストでは GA の組み込み `computer` ツールを使い、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` payload を維持します。
-主な例外は prompt 管理型呼び出しです。prompt テンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK は prompt がどのモデルに固定されているかを推測しないため、preview 互換の computer ペイロードをデフォルトで使います。このフローで GA 経路を維持するには、リクエストで `model="gpt-5.4"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制してください。
+主な例外はプロンプト管理呼び出しです。プロンプトテンプレートがモデルを保持し、 SDK がリクエストから `model` を省略する場合、 SDK はプロンプトが固定するモデルを推測しないため、 preview 互換のコンピュータ payload を既定で使います。このフローで GA パスを維持するには、リクエストで `model="gpt-5.4"` を明示するか、 `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` が登録されていない場合、これらの文字列は通常の関数名として動作し続けます。
-preview 互換リクエストでは `environment` と表示寸法を先にシリアライズする必要があるため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使う prompt 管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細は [Tools](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。
+preview 互換リクエストでは、 `environment` と表示寸法を先にシリアライズする必要があるため、 [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使うプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細は [Tools](../tools.md#computertool-and-the-responses-computer-tool) を参照してください。
-#### non-GPT-5 モデル
+#### 非 GPT-5 モデル
-カスタム `model_settings` なしで non–GPT-5 モデル名を渡すと、SDK は任意モデル互換の汎用 `ModelSettings` に戻ります。
+カスタム `model_settings` なしで非 GPT-5 モデル名を渡すと、 SDK は任意モデル互換の汎用 `ModelSettings` に戻ります。
### Responses 専用ツール検索機能
@@ -96,13 +96,13 @@ preview 互換リクエストでは `environment` と表示寸法を先にシリ
- [`ToolSearchTool`][agents.tool.ToolSearchTool]
- [`tool_namespace()`][agents.tool.tool_namespace]
-- `@function_tool(defer_loading=True)` と、その他の遅延読み込み Responses ツール面
+- `@function_tool(defer_loading=True)` と、その他の遅延読み込み Responses ツールサーフェス
-これらの機能は Chat Completions モデルおよび non-Responses バックエンドでは拒否されます。遅延読み込みツールを使う場合は、エージェントに `ToolSearchTool()` を追加し、素の namespace 名や遅延専用関数名を強制する代わりに、`auto` または `required` の tool choice でモデルにツールを読み込ませてください。設定詳細と現時点の制約は [Tools](../tools.md#hosted-tool-search) を参照してください。
+これらの機能は Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使う場合は、エージェントに `ToolSearchTool()` を追加し、 namespace 名や遅延専用関数名を強制する代わりに、 `auto` または `required` の tool choice でモデルにツールを読み込ませてください。設定詳細と現在の制約は [Tools](../tools.md#hosted-tool-search) を参照してください。
-### Responses WebSocket 転送
+### 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 provider で解決される OpenAI Responses モデル（ `"gpt-5.4"` のような文字列モデル名を含む）に影響します。
+これは、既定の OpenAI プロバイダーで解決される OpenAI Responses モデル（ `"gpt-5.4"` のような文字列モデル名を含む）に影響します。
-転送方式の選択は、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 が転送選択を制御します。
+トランスポート選択は、 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 / 実行レベル設定
+#### プロバイダーまたは実行レベル設定
-websocket 転送は provider 単位または実行単位でも設定できます。
+websocket トランスポートはプロバイダー単位または実行単位でも設定できます。
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -137,16 +137,16 @@ result = await Runner.run(
)
```
-#### `MultiProvider` による高度なルーティング
+#### `MultiProvider` を使った高度なルーティング
-接頭辞ベースのモデルルーティングが必要な場合（例: 1 回の実行で `openai/...` と `litellm/...` のモデル名を混在させる）、[`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 provider のエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。
-- 未知の接頭辞はそのまま渡されず、`UserError` を発生させます。
+- `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、 `openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。
+- 不明なプレフィックスはそのまま渡されず、 `UserError` を発生させます。
-OpenAI 互換エンドポイントで、名前空間付きモデル ID の文字列をそのまま期待する場合は、明示的に pass-through 動作を有効化してください。websocket 有効構成では、`MultiProvider` 側でも `openai_use_responses_websocket=True` を維持してください。
+OpenAI 互換エンドポイントが名前空間付きモデル ID の文字列そのものを期待する場合は、明示的にパススルー動作を有効化してください。 websocket 有効構成では、 `MultiProvider` 側でも `openai_use_responses_websocket=True` を維持してください。
```python
from agents import Agent, MultiProvider, RunConfig, Runner
@@ -172,52 +172,52 @@ 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] でも利用できます。
-カスタムの OpenAI 互換エンドポイントや proxy を使う場合、websocket 転送には互換 websocket `/responses` エンドポイントも必要です。このような構成では `websocket_base_url` の明示設定が必要になることがあります。
+カスタム OpenAI 互換エンドポイントまたはプロキシを使う場合、 websocket トランスポートには互換 websocket `/responses` エンドポイントも必要です。その構成では `websocket_base_url` を明示設定する必要がある場合があります。
-#### 注記
+#### 注意事項
-- これは websocket 転送上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や、Responses websocket `/responses` エンドポイントをサポートしない non-OpenAI provider には適用されません。
+- これは websocket トランスポート上の Responses API であり、 [Realtime API](../realtime/guide.md) ではありません。 Chat Completions や、 Responses websocket `/responses` エンドポイントをサポートしない非 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) を参照してください。
+- 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) を参照してください。
-## non-OpenAI モデル
+## 非 OpenAI モデル
-non-OpenAI provider が必要な場合は、まず SDK の組み込み provider 統合ポイントから始めてください。多くの構成では LiteLLM 追加なしで十分です。各パターンの例は [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/) にあります。
-### non-OpenAI provider 統合方法
+### 非 OpenAI プロバイダー統合方法
| アプローチ | 使用する場面 | スコープ |
| --- | --- | --- |
-| [`set_default_openai_client`][agents.set_default_openai_client] | 1 つの OpenAI 互換エンドポイントを、ほとんどまたはすべてのエージェントのデフォルトにしたい | グローバルデフォルト |
-| [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタム provider を単一実行に適用したい | 実行単位 |
-| [`Agent.model`][agents.agent.Agent.model] | エージェントごとに異なる provider または具体的モデルオブジェクトが必要 | エージェント単位 |
-| LiteLLM (beta) | LiteLLM 固有の provider カバレッジやルーティングが必要 | [LiteLLM](#litellm) を参照 |
+| [`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) を参照 |
-これらの組み込み経路で他の 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` レベルです。これにより「この実行の全エージェントでカスタム model 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 key がない場合は、`set_tracing_disabled()` でトレーシングを無効化するか、[別のトレーシングプロセッサー](../tracing.md) を設定することを推奨します。
+`platform.openai.com` の API キーがない場合は、 `set_tracing_disabled()` でトレーシングを無効化するか、 [別のトレーシングプロセッサー](../tracing.md) の設定を推奨します。
!!! note
- これらの例では、Chat Completions API / model を使っています。多くの LLM provider がまだ Responses API をサポートしていないためです。LLM provider が対応している場合は Responses の利用を推奨します。
+ これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、 Chat Completions API / モデルを使用しています。お使いの LLM プロバイダーが対応している場合は、 Responses の使用を推奨します。
-## 1 つのワークフロー内でのモデル混在
+## 1 つのワークフローでのモデル混在
-単一ワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小さく高速なモデルを使い、複雑なタスクには大きく高性能なモデルを使う、といった構成です。[`Agent`][agents.Agent] を設定する際、次のいずれかで特定モデルを選択できます。
+1 つのワークフロー内で、エージェントごとに異なるモデルを使いたい場合があります。たとえば、トリアージには小さく高速なモデルを使い、複雑なタスクにはより大規模で高機能なモデルを使えます。[`Agent`][agents.Agent] を設定する際、特定モデルは次のいずれかで選択できます。
1. モデル名を渡す。
-2. 任意のモデル名 + その名前を Model インスタンスにマップできる [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。
-3. [`Model`][agents.models.interface.Model] 実装を直接渡す。
+2. 任意のモデル名 + その名前を Model インスタンスにマップ可能な [`ModelProvider`][agents.models.interface.ModelProvider] を渡す。
+3. [`Model`][agents.models.interface.Model] 実装を直接提供する。
!!! note
- SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方をサポートしていますが、2 つは対応機能・ツール集合が異なるため、ワークフローごとに単一のモデル形状を使うことを推奨します。モデル形状を混在させる必要がある場合は、利用する機能が両方で使えることを確認してください。
+ SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形をサポートしますが、 2 つは対応機能とツールが異なるため、ワークフローごとに 1 つのモデル形に統一することを推奨します。ワークフローでモデル形の混在が必要な場合は、使用するすべての機能が両方で利用可能であることを確認してください。
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -253,7 +253,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
@@ -268,19 +268,19 @@ english_agent = Agent(
## 高度な OpenAI Responses 設定
-OpenAI Responses 経路でより細かな制御が必要な場合は、`ModelSettings` から始めてください。
+OpenAI Responses パスでより細かな制御が必要な場合は、まず `ModelSettings` を使用してください。
### 一般的な高度 `ModelSettings` オプション
-OpenAI Responses API 利用時は、いくつかのリクエストフィールドに直接対応する `ModelSettings` フィールドがすでにあるため、それらに `extra_args` は不要です。
+OpenAI Responses API 使用時は、いくつかのリクエストフィールドに対応する `ModelSettings` フィールドが既にあるため、それらには `extra_args` は不要です。
-- `parallel_tool_calls`: 同一ターンでの複数 tool call を許可 / 禁止します。
-- `truncation`: `"auto"` を設定すると、コンテキスト超過時に失敗せず、Responses API が最も古い会話項目を削除します。
-- `store`: 生成レスポンスを後続取得のためサーバー側に保存するかを制御します。レスポンス ID に依存するフォローアップワークフローや、`store=False` 時にローカル入力へフォールバックが必要なセッション圧縮フローで重要です。
-- `prompt_cache_retention`: たとえば `"24h"` のように、キャッシュされた prompt 接頭辞をより長く保持します。
-- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードを要求します。
-- `top_logprobs`: 出力テキストの上位 token logprobs を要求します。SDK は `message.output_text.logprobs` も自動追加します。
-- `retry`: モデル呼び出しに対する runner 管理 retry 設定を有効化します。[Runner 管理リトライ](#runner-managed-retries) を参照してください。
+- `parallel_tool_calls`: 同一ターンでの複数ツール呼び出しを許可または禁止します。
+- `truncation`: コンテキストあふれ時に失敗する代わりに、 Responses API に最古の会話項目を削除させるには `"auto"` を設定します。
+- `store`: 生成された応答を後で取得できるようサーバー側に保存するかを制御します。これは、 response ID に依存するフォローアップワークフローや、 `store=False` 時にローカル入力へフォールバックが必要なセッション圧縮フローで重要です。
+- `prompt_cache_retention`: たとえば `"24h"` のように、キャッシュされたプロンプト接頭辞をより長く保持します。
+- `response_include`: `web_search_call.action.sources` 、 `file_search_call.results` 、 `reasoning.encrypted_content` など、より豊富な応答 payload を要求します。
+- `top_logprobs`: 出力テキストの上位トークン logprobs を要求します。 SDK は `message.output_text.logprobs` も自動追加します。
+- `retry`: モデル呼び出しにランナー管理リトライ設定を有効化します。[ランナー管理リトライ](#runner-managed-retries) を参照してください。
```python
from agents import Agent, ModelSettings
@@ -299,13 +299,13 @@ research_agent = Agent(
)
```
-`store=False` を設定すると、Responses API はそのレスポンスを後続のサーバー側取得に利用できる状態で保持しません。これは stateless または zero-data-retention 風フローで有用ですが、通常レスポンス ID を再利用する機能は、代わりにローカル管理状態へ依存する必要があります。たとえば [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていない場合、デフォルト `"auto"` 圧縮経路を入力ベース圧縮へ切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。
+`store=False` を設定すると、 Responses API はその応答を後でサーバー側取得可能な状態に保持しません。これはステートレスまたはゼロデータ保持スタイルのフローで有用ですが、通常 response ID を再利用する機能は、代わりにローカル管理状態に依存する必要があります。たとえば、 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後の応答が保存されていない場合、既定の `"auto"` 圧縮パスを入力ベース圧縮に切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions) を参照してください。
### `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` で渡せます。
+また OpenAI の Responses API 使用時には、[その他の任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user` 、 `service_tier` など）があります。トップレベルにない場合、これらも `extra_args` で渡せます。
```python
from agents import Agent, ModelSettings
@@ -321,9 +321,9 @@ english_agent = Agent(
)
```
-## Runner 管理リトライ
+## ランナー管理リトライ
-リトライは実行時限定で、明示的な opt-in です。`ModelSettings(retry=...)` を設定し、かつ retry policy が再試行を選択しない限り、SDK は一般的なモデルリクエストをリトライしません。
+リトライは実行時専用で、明示的に有効化する必要があります。 SDK は `ModelSettings(retry=...)` を設定し、かつリトライポリシーがリトライを選択した場合を除き、一般的なモデルリクエストをリトライしません。
```python
from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
@@ -357,79 +357,79 @@ agent = Agent(
| フィールド | 型 | 注記 |
| --- | --- | --- |
-| `max_retries` | `int | None` | 初回リクエスト後に許可される再試行回数です。 |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | policy が明示的 delay を返さずに再試行するときのデフォルト遅延戦略です。 |
-| `policy` | `RetryPolicy | None` | 再試行するかを決めるコールバックです。このフィールドは実行時限定でシリアライズされません。 |
+| `max_retries` | `int | None` | 初回リクエスト後に許可されるリトライ試行回数。 |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示遅延を返さずにリトライする場合の既定遅延戦略。 |
+| `policy` | `RetryPolicy | None` | リトライ可否を判断するコールバック。このフィールドは実行時専用でシリアライズされません。 |
-retry policy は [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。内容は以下です。
+リトライポリシーは、 [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。内容は次のとおりです。
-- `attempt` と `max_retries`（試行回数に応じた判断に使用）。
-- `stream`（streamed / non-streamed で分岐可能）。
-- `error`（raw 検査用）。
-- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの `normalized` 情報。
-- 下位モデルアダプターが retry ガイダンスを提供できる場合の `provider_advice`。
+- `attempt` と `max_retries` （試行回数を考慮した判断用）
+- `stream` （ストリーミング / 非ストリーミング分岐用）
+- `error` （raw 検査用）
+- `normalized` 情報（ `status_code` 、 `retry_after` 、 `error_code` 、 `is_network_error` 、 `is_timeout` 、 `is_abort` など）
+- 基盤モデルアダプターがリトライ指針を提供できる場合の `provider_advice`
-policy は次のいずれかを返せます。
+ポリシーは次のいずれかを返せます。
-- 単純な再試行判定としての `True` / `False`。
-- delay 上書きや診断理由付与を行いたい場合の [`RetryDecision`][agents.retry.RetryDecision]。
+- 単純なリトライ判断として `True` / `False`
+- 遅延上書きや診断理由付与をしたい場合の [`RetryDecision`][agents.retry.RetryDecision]
SDK は `retry_policies` に既製ヘルパーを提供しています。
-| ヘルパー | 振る舞い |
+| ヘルパー | 動作 |
| --- | --- |
-| `retry_policies.never()` | 常に opt-out します。 |
-| `retry_policies.provider_suggested()` | 利用可能な場合、provider の retry 推奨に従います。 |
-| `retry_policies.network_error()` | 一時的な転送 / timeout 障害に一致します。 |
-| `retry_policies.http_status([...])` | 選択した HTTP status code に一致します。 |
-| `retry_policies.retry_after()` | retry-after ヒントがある場合のみ、その delay で再試行します。 |
-| `retry_policies.any(...)` | ネスト policy のいずれかが opt-in したとき再試行します。 |
-| `retry_policies.all(...)` | ネスト policy のすべてが opt-in したときのみ再試行します。 |
+| `retry_policies.never()` | 常に無効化します。 |
+| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーのリトライ助言に従います。 |
+| `retry_policies.network_error()` | 一時的なトランスポート / タイムアウト失敗に一致します。 |
+| `retry_policies.http_status([...])` | 指定した HTTP ステータスコードに一致します。 |
+| `retry_policies.retry_after()` | retry-after ヒントがある場合のみ、その遅延でリトライします。 |
+| `retry_policies.any(...)` | ネストしたポリシーのいずれかが有効化したらリトライします。 |
+| `retry_policies.all(...)` | ネストしたポリシーのすべてが有効化した場合のみリトライします。 |
-policy を組み合わせる場合、`provider_suggested()` は最も安全な最初の構成要素です。provider が判別可能な場合、provider veto と replay-safety 承認を保持できるためです。
+ポリシーを組み合わせる場合、 `provider_suggested()` は最も安全な最初の構成要素です。プロバイダーが判別可能な場合、プロバイダー側の拒否や再実行安全性承認を維持できるためです。
##### 安全境界
-次の障害は自動再試行されません。
+一部の失敗は自動リトライされません。
-- Abort エラー。
-- provider アドバイスが replay unsafe と判定したリクエスト。
-- 出力がすでに始まっており replay が unsafe になる streamed 実行。
+- 中断エラー。
+- プロバイダー助言で再実行が unsafe とされたリクエスト。
+- 出力開始後で再実行が unsafe になるストリーミング実行。
-`previous_response_id` または `conversation_id` を使う状態付きフォローアップリクエストも、より保守的に扱われます。これらのリクエストでは `network_error()` や `http_status([500])` のような非 provider 判定だけでは不十分です。retry policy には通常 `retry_policies.provider_suggested()` を通じた provider の replay-safe 承認を含める必要があります。
+`previous_response_id` または `conversation_id` を使う状態保持フォローアップリクエストも、より保守的に扱われます。これらでは `network_error()` や `http_status([500])` のような非プロバイダー述語だけでは不十分です。リトライポリシーには通常 `retry_policies.provider_suggested()` を通じた、プロバイダー由来の replay-safe 承認を含める必要があります。
-##### Runner とエージェントのマージ挙動
+##### ランナーとエージェントのマージ動作
-`retry` は runner レベルとエージェントレベルの `ModelSettings` 間で deep-merge されます。
+`retry` はランナーレベルとエージェントレベルの `ModelSettings` 間でディープマージされます。
-- エージェントは `retry.max_retries` のみを上書きしつつ、runner の `policy` を継承できます。
-- エージェントは `retry.backoff` の一部のみを上書きし、他の backoff フィールドは runner から維持できます。
-- `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) と [`examples/basic/retry_litellm.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) と [adapter-backed retry example](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py) を参照してください。
-## non-OpenAI provider のトラブルシューティング
+## 非 OpenAI プロバイダーのトラブルシューティング
### トレーシングクライアントエラー 401
-トレーシング関連エラーが出る場合、トレースが OpenAI サーバーへアップロードされる一方で OpenAI API key がないことが原因です。解決方法は 3 つあります。
+トレーシング関連エラーが出る場合、トレースは OpenAI サーバーへアップロードされる一方で OpenAI API キーがないことが原因です。解決策は 3 つあります。
1. トレーシングを完全に無効化する: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。
-2. トレーシング用 OpenAI key を設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API key はトレースアップロード専用で、[platform.openai.com](https://platform.openai.com/) 由来である必要があります。
-3. non-OpenAI トレースプロセッサーを使う。[tracing docs](../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 docs](../tracing.md#custom-tracing-processors) を参照してください。
### Responses API サポート
-SDK はデフォルトで Responses API を使いますが、多くの他 LLM provider はまだ対応していません。その結果 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/) にあります。
+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 サポート
-一部の model provider は [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが出る場合があります。
+一部のモデルプロバイダーは [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。この場合、次のようなエラーになることがあります。
```
@@ -437,24 +437,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
-これは一部 model provider 側の制約です。JSON 出力はサポートしていても、出力に使う `json_schema` の指定を許可しません。この問題の修正に取り組んでいますが、JSON schema 出力をサポートする provider の利用を推奨します。そうでない場合、アプリは不正な JSON によって頻繁に壊れる可能性があります。
+これは一部モデルプロバイダーの制約です。 JSON 出力はサポートしていても、出力に使用する `json_schema` の指定を許可していません。現在修正に取り組んでいますが、 JSON schema 出力をサポートするプロバイダーの利用を推奨します。そうでない場合、不正な JSON によりアプリが頻繁に壊れる可能性があります。
-## provider 間でのモデル混在
+## プロバイダー間でのモデル混在
-model provider 間の機能差を把握していないとエラーになる可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしますが、多くの他 provider はこれらをサポートしません。次の制約に注意してください。
+モデルプロバイダー間の機能差を把握しておく必要があります。そうしないとエラーになる可能性があります。たとえば OpenAI は structured outputs、マルチモーダル入力、ホスト型ファイル検索と Web 検索をサポートしますが、多くの他プロバイダーはこれらをサポートしません。次の制約に注意してください。
-- 未対応 provider に、未対応の `tools` を送らない
-- テキスト専用モデル呼び出し前に、マルチモーダル入力を除外する
-- structured JSON 出力非対応 provider は、ときどき不正な JSON を生成する点に注意する
+- 非対応プロバイダーへ、対応していない `tools` を送らない
+- テキスト専用モデル呼び出し前にマルチモーダル入力を除外する
+- structured JSON 出力非対応プロバイダーは無効 JSON を時々生成する可能性があることを理解する
-## LiteLLM
+## サードパーティーアダプター
-LiteLLM サポートは、non-OpenAI provider を Agents SDK ワークフローへ取り込む必要があるケース向けに、best-effort の beta として提供されています。
+SDK の組み込みプロバイダー統合ポイントで不足する場合のみ、サードパーティーアダプターを選択してください。この SDK で OpenAI モデルのみを使用する場合、 Any-LLM や LiteLLM ではなく組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] パスを優先してください。サードパーティーアダプターは、 OpenAI モデルと非 OpenAI プロバイダーを組み合わせる必要がある場合、または組み込みパスで提供されないアダプター管理のプロバイダー対応 / ルーティングが必要な場合向けです。アダプターは SDK と上流モデルプロバイダーの間に別の互換レイヤーを追加するため、機能サポートやリクエスト意味論はプロバイダーごとに異なります。 SDK には現在、 Any-LLM と LiteLLM がベストエフォートのベータ統合として含まれています。
-この SDK で OpenAI モデルを使う場合は、LiteLLM ではなく組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 経路を推奨します。
+### Any-LLM
-OpenAI モデルと non-OpenAI provider を組み合わせる必要があり、とくに Chat Completions 互換 API 経由で使う場合、LiteLLM は beta オプションとして利用できますが、すべての構成で最適とは限りません。
+Any-LLM サポートは、 Any-LLM 管理のプロバイダー対応またはルーティングが必要な場合向けに、ベストエフォートのベータとして含まれています。
-non-OpenAI provider で 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] を直接インスタンス化できます。
+上流プロバイダーパスに応じて、 Any-LLM は Responses API、 Chat Completions 互換 API、またはプロバイダー固有互換レイヤーを使う場合があります。
-LiteLLM のレスポンスで SDK の usage metrics を埋めたい場合は、`ModelSettings(include_usage=True)` を渡してください。
\ No newline at end of file
+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 バックエンドでは usage チャンク出力前に `ModelSettings(include_usage=True)` が必要な場合があります。structured outputs、ツール呼び出し、 usage レポート、 Responses 固有動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
+
+### 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 usage メトリクスを埋めません。 usage レポートが必要な場合は `ModelSettings(include_usage=True)` を渡し、 structured outputs、ツール呼び出し、 usage レポート、またはアダプター固有ルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
\ No newline at end of file
diff --git a/docs/ja/models/litellm.md b/docs/ja/models/litellm.md
index ff56dcc7ae..c1437b4455 100644
--- a/docs/ja/models/litellm.md
+++ b/docs/ja/models/litellm.md
@@ -5,9 +5,9 @@ search:
# LiteLLM
-このページは [Models の LiteLLM セクション](index.md#litellm)に移動しました。
+このページは [Models の Third-party adapters セクション](index.md#third-party-adapters)に移動しました。
自動的にリダイレクトされない場合は、上記のリンクを使用してください。
\ No newline at end of file
diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md
index f5bdbe3968..84930611a5 100644
--- a/docs/ja/tracing.md
+++ b/docs/ja/tracing.md
@@ -4,31 +4,31 @@ 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] を使って、コード内でグローバルにトレーシングを無効化できます
+ 2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード上でグローバルにトレーシングを無効化できます
3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行でトレーシングを無効化できます
***OpenAI の API を使用し、Zero Data Retention ( ZDR ) ポリシーの下で運用している組織では、トレーシングは利用できません。***
-## トレースとスパン
+## Traces と spans
-- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります。
- - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「Code generation」や「Customer service」です。
+- **Traces** は 1 つの「ワークフロー」のエンドツーエンドの単一操作を表します。これは Span で構成されます。Traces には次のプロパティがあります。
+ - `workflow_name`: 論理的なワークフローまたはアプリです。例: 「Code generation」や「Customer service」。
- `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。
- - `group_id`: 同じ会話からの複数のトレースを関連付けるための任意のグループ ID です。たとえば、チャットスレッド ID を使用できます。
- - `disabled`: True の場合、トレースは記録されません。
+ - `group_id`: 任意のグループ ID で、同じ会話内の複数のトレースを関連付けます。たとえば、チャットスレッド ID を使用できます。
+ - `disabled`: True の場合、そのトレースは記録されません。
- `metadata`: トレースの任意のメタデータです。
-- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。
+- **Spans** は開始時刻と終了時刻を持つ操作を表します。Spans には次が含まれます。
- `started_at` と `ended_at` のタイムスタンプ。
- - `trace_id`: 属するトレースを表します
- - `parent_id`: このスパンの親スパン（存在する場合）を指します
- - `span_data`: スパンに関する情報です。たとえば `AgentSpanData` にはエージェントの情報、`GenerationSpanData` には LLM 生成の情報などが含まれます。
+ - `trace_id`（所属するトレースを表します）
+ - `parent_id`（この Span の親 Span を指します。存在する場合）
+ - `span_data`（ Span に関する情報）。たとえば、`AgentSpanData` は Agent の情報、`GenerationSpanData` は LLM 生成の情報を含みます。
## デフォルトトレーシング
@@ -42,15 +42,15 @@ Agents SDK には組み込みのトレーシングが含まれており、エー
- ハンドオフは `handoff_span()` でラップされます
- 音声入力（ speech-to-text ）は `transcription_span()` でラップされます
- 音声出力（ text-to-speech ）は `speech_span()` でラップされます
-- 関連する音声スパンは `speech_group_span()` の子になる場合があります
+- 関連する音声 Span は `speech_group_span()` の配下になる場合があります
-デフォルトで、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前や他のプロパティを設定することもできます。
+デフォルトで、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。
-さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へプッシュできます（置き換えまたは二次送信先として）。
+さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先にプッシュできます（置き換えまたは副次的な送信先として）。
## 上位レベルトレース
-場合によっては、`run()` への複数回の呼び出しを 1 つのトレースに含めたいことがあります。これを行うには、コード全体を `trace()` でラップします。
+場合によっては、`run()` の複数回呼び出しを 1 つのトレースの一部にしたいことがあります。これは、コード全体を `trace()` でラップすることで実現できます。
```python
from agents import Agent, Runner, trace
@@ -65,60 +65,60 @@ async def main():
print(f"Rating: {second_result.final_output}")
```
-1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。
+1. `Runner.run` の 2 回の呼び出しは `with 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 作成
-さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数が利用できます。
+さまざまな [`*_span()`][agents.tracing.create] メソッドを使って Span を作成できます。一般に、Span を手動で作成する必要はありません。カスタム Span 情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。
-スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。
+Span は自動的に現在のトレースの一部となり、最も近い現在の Span の配下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。
-## 機密データ
+## 機微データ
-一部のスパンは、機密性のある可能性があるデータを取得する場合があります。
+一部の Span では、機微データが含まれる可能性があります。
-`generation_span()` は LLM 生成の入力 / 出力を保存し、`function_span()` は関数呼び出しの入力 / 出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの取得を無効化できます。
+`generation_span()` は LLM 生成の入出力を保存し、`function_span()` は関数呼び出しの入出力を保存します。これらには機微データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの収集を無効化できます。
-同様に、音声スパンにはデフォルトで入力 / 出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。
+同様に、Audio 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` として export します。
+デフォルトでは、`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`][agents.tracing.setup.TraceProvider] を作成します。
+- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。これはトレース / Span をバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、さらに Span とトレースを 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] を使うと、準備できたトレースと Span を受け取る**追加の**トレースプロセッサーを追加できます。これにより、OpenAI バックエンドへの送信に加えて独自の処理を行えます。
+2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使うと、デフォルトプロセッサーを独自のトレースプロセッサーで**置き換え**できます。これは、`TracingProcessor` を含めない限り、トレースが OpenAI バックエンドへ送信されないことを意味します。
## 非 OpenAI モデルでのトレーシング
-OpenAI API キーを非 OpenAI モデルと共に使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料トレーシングを有効化できます。
+トレーシングを無効化しなくても、OpenAI 以外のモデルで OpenAI API キーを使用して OpenAI Traces ダッシュボードで無料トレーシングを有効化できます。アダプター選択とセットアップ時の注意点については、Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションを参照してください。
```python
import os
from agents import set_tracing_export_api_key, Agent, Runner
-from agents.extensions.models.litellm_model import LitellmModel
+from agents.extensions.models.any_llm_model import AnyLLMModel
tracing_api_key = os.environ["OPENAI_API_KEY"]
set_tracing_export_api_key(tracing_api_key)
-model = LitellmModel(
- model="your-model-name",
+model = AnyLLMModel(
+ model="your-provider/your-model-name",
api_key="your-api-key",
)
@@ -128,7 +128,7 @@ agent = Agent(
)
```
-単一の実行でのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。
+単一の実行にのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。
```python
from agents import Runner, RunConfig
@@ -140,13 +140,13 @@ await Runner.run(
)
```
-## 追加の注意事項
-- Openai Traces ダッシュボードで無料トレースを確認します。
+## 追加メモ
+- Openai Traces ダッシュボードで無料トレースを表示します。
-## エコシステム連携
+## エコシステム統合
-次のコミュニティおよびベンダー連携は、OpenAI Agents SDK のトレーシングサーフェスをサポートしています。
+以下のコミュニティおよびベンダーの統合は、OpenAI Agents SDK のトレーシング機能をサポートしています。
### 外部トレーシングプロセッサー一覧
diff --git a/docs/ja/usage.md b/docs/ja/usage.md
index 1c1e1d5328..28cccd5512 100644
--- a/docs/ja/usage.md
+++ b/docs/ja/usage.md
@@ -4,22 +4,22 @@ search:
---
# 使用方法
-Agents SDK は、実行ごとのトークン使用量を自動的に追跡します。実行コンテキストからアクセスでき、コスト監視、制限の適用、分析記録に利用できます。
+Agents SDK は、すべての実行についてトークン使用量を自動的に追跡します。実行コンテキストからこれにアクセスし、コストの監視、制限の適用、または分析の記録に使用できます。
## 追跡対象
- **requests**: 実行された LLM API 呼び出し回数
-- **input_tokens**: 送信された入力トークン総数
-- **output_tokens**: 受信した出力トークン総数
+- **input_tokens**: 送信された入力トークンの合計
+- **output_tokens**: 受信した出力トークンの合計
- **total_tokens**: 入力 + 出力
- **request_usage_entries**: リクエストごとの使用量内訳の一覧
- **details**:
- `input_tokens_details.cached_tokens`
- `output_tokens_details.reasoning_tokens`
-## 実行からの使用量へのアクセス
+## 実行からの使用量アクセス
-`Runner.run(...)` の後、`result.context_wrapper.usage` で使用量にアクセスします。
+`Runner.run(...)` の後、`result.context_wrapper.usage` 経由で使用量にアクセスします。
```python
result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -31,29 +31,20 @@ print("Output tokens:", usage.output_tokens)
print("Total tokens:", usage.total_tokens)
```
-使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）で集計されます。
+使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）にわたって集計されます。
-### LiteLLM モデルでの使用量の有効化
+### サードパーティアダプターでの使用量有効化
-LiteLLM プロバイダーは、デフォルトでは使用量メトリクスを報告しません。[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を使用している場合は、LiteLLM のレスポンスが `result.context_wrapper.usage` を埋めるよう、エージェントに `ModelSettings(include_usage=True)` を渡してください。設定手順とコード例については、Models ガイドの [LiteLLM note](models/index.md#litellm) を参照してください。
+使用量レポートは、サードパーティアダプターおよびプロバイダーバックエンドによって異なります。アダプター経由のモデルに依存し、正確な `result.context_wrapper.usage` の値が必要な場合:
-```python
-from agents import Agent, ModelSettings, Runner
-from agents.extensions.models.litellm_model import LitellmModel
-
-agent = Agent(
- name="Assistant",
- model=LitellmModel(model="your/model", api_key="..."),
- model_settings=ModelSettings(include_usage=True),
-)
+- `AnyLLMModel` では、上流プロバイダーが使用量を返すと自動的に伝播されます。ストリーミング Chat Completions バックエンドでは、使用量チャンクが出力される前に `ModelSettings(include_usage=True)` が必要な場合があります。
+- `LitellmModel` では、一部のプロバイダーバックエンドは既定で使用量をレポートしないため、`ModelSettings(include_usage=True)` が必要になることがよくあります。
-result = await Runner.run(agent, "What's the weather in Tokyo?")
-print(result.context_wrapper.usage.total_tokens)
-```
+Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションにあるアダプター固有の注意事項を確認し、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
## リクエストごとの使用量追跡
-SDK は、`request_usage_entries` 内の API リクエストごとの使用量を自動追跡します。これは詳細なコスト計算やコンテキストウィンドウ消費量の監視に有用です。
+SDK は、各 API リクエストの使用量を `request_usage_entries` で自動追跡します。これは、詳細なコスト計算やコンテキストウィンドウ消費の監視に役立ちます。
```python
result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -62,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")
@@ -76,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):
@@ -91,7 +82,7 @@ class MyHooks(RunHooks):
## API リファレンス
-詳細な API ドキュメントは次を参照してください。
+詳細な API ドキュメントは以下を参照してください。
- [`Usage`][agents.usage.Usage] - 使用量追跡データ構造
- [`RequestUsage`][agents.usage.RequestUsage] - リクエストごとの使用量詳細
diff --git a/docs/ko/examples.md b/docs/ko/examples.md
index 00fcb001d5..9d3d59cee4 100644
--- a/docs/ko/examples.md
+++ b/docs/ko/examples.md
@@ -2,38 +2,38 @@
search:
exclude: true
---
-# 예제
+# 코드 예제
-[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. examples는 서로 다른 패턴과 기능을 보여 주는 여러 카테고리로 구성되어 있습니다
+[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. examples는 다양한 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다.
## 카테고리
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
- 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여 줍니다
+ 이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다
- 결정론적 워크플로
- Agents as tools
- 병렬 에이전트 실행
- 조건부 도구 사용
- 입력/출력 가드레일
- - 심판으로서의 LLM
+ - 심사자로서의 LLM
- 라우팅
- 스트리밍 가드레일
- - 승인 흐름을 위한 사용자 지정 거부 메시지 (`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 예제(Default model, GPT-5, open-weight model)
- - 에이전트 수명 주기 관리
+ - Hello World 예제 (기본 모델, GPT-5, 오픈 가중치 모델)
+ - 에이전트 라이프사이클 관리
- 동적 시스템 프롬프트
- - 스트리밍 출력(텍스트, 항목, 함수 호출 인수)
+ - 스트리밍 출력 (텍스트, 항목, 함수 호출 인수)
- 턴 간 공유 세션 헬퍼를 사용하는 Responses websocket 전송 (`examples/basic/stream_ws.py`)
- 프롬프트 템플릿
- - 파일 처리(로컬 및 원격, 이미지 및 PDF)
+ - 파일 처리 (로컬 및 원격, 이미지 및 PDF)
- 사용량 추적
- Runner 관리 재시도 설정 (`examples/basic/retry.py`)
- - LiteLLM을 사용한 Runner 관리 재시도 (`examples/basic/retry_litellm.py`)
+ - 서드파티 어댑터를 통한 Runner 관리 재시도 (`examples/basic/retry_litellm.py`)
- 비엄격 출력 타입
- 이전 응답 ID 사용
@@ -41,41 +41,41 @@ search:
항공사를 위한 고객 서비스 시스템 예제입니다
- **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
- 금융 데이터 분석을 위한 에이전트와 도구를 사용해 구조화된 리서치 워크플로를 보여 주는 금융 리서치 에이전트입니다
+ 금융 데이터 분석을 위해 에이전트와 도구를 활용한 구조화된 리서치 워크플로를 보여주는 금융 리서치 에이전트입니다
- **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
- 메시지 필터링이 포함된 에이전트 핸드오프의 실용적인 예제를 확인해 보세요
+ 메시지 필터링을 사용하는 에이전트 핸드오프의 실용적인 예제를 확인하세요
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
- 호스티드 MCP(Model Context Protocol) 커넥터와 승인 사용 방법을 보여 주는 예제입니다
+ 호스티드 MCP (Model context protocol) 커넥터와 승인 사용 방법을 보여주는 예제입니다
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
- 다음을 포함해 MCP(Model Context Protocol)로 에이전트를 구축하는 방법을 알아보세요
+ 다음을 포함해 MCP (Model context protocol)로 에이전트를 구축하는 방법을 알아보세요
- - 파일시스템 예제
+ - 파일 시스템 예제
- Git 예제
- MCP 프롬프트 서버 예제
- - SSE(Server-Sent Events) 예제
+ - SSE (Server-Sent Events) 예제
- 스트리밍 가능한 HTTP 예제
- **[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`)
+ 다음을 포함한 에이전트를 위한 다양한 메모리 구현 예제입니다
+
+ - SQLite 세션 저장소
+ - 고급 SQLite 세션 저장소
+ - Redis 세션 저장소
+ - SQLAlchemy 세션 저장소
+ - Dapr 상태 저장소 세션 저장소
+ - 암호화된 세션 저장소
+ - OpenAI Conversations 세션 저장소
+ - Responses 컴팩션 세션 저장소
+ - `ModelSettings(store=False)`를 사용한 상태 비저장 Responses 컴팩션 (`examples/memory/compaction_session_stateless_example.py`)
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
- 사용자 지정 provider와 LiteLLM 통합을 포함해 SDK에서 OpenAI 이외 모델을 사용하는 방법을 살펴보세요
+ 사용자 지정 제공자와 서드파티 어댑터를 포함해 SDK에서 OpenAI가 아닌 모델을 사용하는 방법을 살펴보세요
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
- 다음을 포함해 SDK를 사용해 실시간 경험을 구축하는 방법을 보여 주는 예제입니다
+ 다음을 포함해 SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제입니다
- 구조화된 텍스트 및 이미지 메시지를 사용하는 웹 애플리케이션 패턴
- 명령줄 오디오 루프 및 재생 처리
@@ -83,25 +83,25 @@ search:
- Realtime Calls API attach 흐름을 사용하는 Twilio SIP 통합
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
- 추론 콘텐츠 및 structured outputs를 다루는 방법을 보여 주는 예제입니다
+ reasoning content 및 structured outputs를 다루는 방법을 보여주는 예제입니다
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
- 복잡한 멀티 에이전트 리서치 워크플로를 보여 주는 간단한 딥 리서치 클론입니다
+ 복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론입니다
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
- 다음과 같은 OpenAI 호스트하는 도구와 실험적 Codex 툴링을 구현하는 방법을 알아보세요
+ 다음과 같은 OpenAI 호스트하는 도구 및 실험적 Codex 도구 기능을 구현하는 방법을 알아보세요
- - 웹 검색 및 필터를 사용한 웹 검색
+ - 웹 검색 및 필터가 있는 웹 검색
- 파일 검색
- 코드 인터프리터
- - 인라인 스킬이 있는 호스티드 컨테이너 셸 (`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`)
+ - 인라인 스킬을 사용하는 호스티드 컨테이너 셸 (`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
+ 스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요
\ No newline at end of file
diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md
index 24013778b1..6e932e5bb0 100644
--- a/docs/ko/models/index.md
+++ b/docs/ko/models/index.md
@@ -4,42 +4,42 @@ 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]
+- **권장**: 새로운 [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 전송으로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket 전송 활성화 | [Responses WebSocket 전송](#responses-websocket-transport) |
-| OpenAI 가 아닌 provider 하나 사용 | 내장 provider 통합 지점으로 시작 | [OpenAI 가 아닌 모델](#non-openai-models) |
-| 에이전트 전반에서 모델 또는 provider 혼합 | 실행별 또는 에이전트별로 provider 선택 후 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [provider 간 모델 혼합](#mixing-models-across-providers) |
+| OpenAI 가 아닌 provider 하나 사용 | 내장된 provider 통합 지점부터 시작 | [OpenAI 가 아닌 모델](#non-openai-models) |
+| 에이전트 간에 모델 또는 provider 혼합 | 실행 단위 또는 에이전트 단위로 provider 선택 후 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [provider 간 모델 혼합](#mixing-models-across-providers) |
| 고급 OpenAI Responses 요청 설정 조정 | OpenAI Responses 경로에서 `ModelSettings` 사용 | [고급 OpenAI Responses 설정](#advanced-openai-responses-settings) |
-| OpenAI 가 아닌 Chat Completions provider 에 LiteLLM 사용 | LiteLLM 을 베타 대체 옵션으로 사용 | [LiteLLM](#litellm) |
+| OpenAI 가 아닌 경로 또는 혼합 provider 라우팅에 서드파티 adapter 사용 | 지원되는 베타 adapter 비교 후 배포할 provider 경로 검증 | [서드파티 adapter](#third-party-adapters) |
## OpenAI 모델
-대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider 와 문자열 모델 이름을 사용하고, Responses 모델 경로를 유지하는 것을 권장합니다.
+대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider 와 문자열 모델 이름을 사용하고, Responses 모델 경로를 유지하는 것을 권장합니다
-`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)입니다. 접근 권한이 있다면, 명시적인 `model_settings` 를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)로 설정하는 것을 권장합니다.
+`Agent` 를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)입니다. 사용 권한이 있다면, 명시적인 `model_settings` 를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)로 설정하는 것을 권장합니다
-[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다.
+[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다
### 기본 모델
-첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
+첫째, 사용자 지정 모델을 설정하지 않는 모든 에이전트에서 일관되게 특정 모델을 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.4
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.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 GPT-5 모델을 사용하면 SDK 가 기본 `ModelSettings` 를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 값을 설정합니다. 기본 모델의 reasoning effort 를 조정하려면 자체 `ModelSettings` 를 전달하세요:
+이 방식으로 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 GPT-5 모델을 사용하면 SDK 가 기본 `ModelSettings` 를 적용합니다. 대부분의 사용 사례에서 가장 잘 동작하는 값이 설정됩니다. 기본 모델의 reasoning effort 를 조정하려면 사용자 정의 `ModelSettings` 를 전달하세요:
```python
from openai.types.shared import Reasoning
@@ -74,21 +74,21 @@ my_agent = Agent(
)
```
-더 낮은 지연 시간을 위해 `gpt-5.4` 에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 인터랙티브 에이전트 앱 구축에 여전히 좋은 선택입니다.
+더 낮은 지연 시간을 위해 `gpt-5.4` 에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 대화형 에이전트 앱 구축에 여전히 좋은 선택입니다
#### ComputerTool 모델 선택
-에이전트가 [`ComputerTool`][agents.tool.ComputerTool] 을 포함하면, 실제 Responses 요청에서의 유효 모델이 SDK 가 어떤 컴퓨터 도구 페이로드를 보내는지 결정합니다. 명시적 `gpt-5.4` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적 `computer-use-preview` 요청은 기존 `computer_use_preview` 페이로드를 유지합니다.
+에이전트에 [`ComputerTool`][agents.tool.ComputerTool] 이 포함된 경우, 실제 Responses 요청에서의 유효 모델이 SDK 가 전송하는 컴퓨터 도구 payload 를 결정합니다. 명시적인 `gpt-5.4` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` payload 를 유지합니다
-주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK 가 요청에서 `model` 을 생략하면, SDK 는 프롬프트가 고정한 모델을 추측하지 않기 위해 preview 호환 컴퓨터 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에서 `model="gpt-5.4"` 를 명시하거나, `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")` 로 GA 선택기를 강제하세요.
+주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK 가 요청에서 `model` 을 생략하는 경우, SDK 는 프롬프트가 어떤 모델에 고정됐는지 추측하지 않기 위해 preview 호환 컴퓨터 payload 를 기본으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.4"` 를 명시하거나 `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` 이 등록되지 않은 경우 이 문자열은 일반 함수 이름처럼 계속 동작합니다
-preview 호환 요청은 `environment` 및 디스플레이 크기를 먼저 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리 흐름에서는 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청 전 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 사항은 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참고하세요.
+preview 호환 요청은 `environment` 와 디스플레이 크기를 미리 직렬화해야 하므로 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리 흐름에서는 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청 전송 전에 GA 선택자를 강제해야 합니다. 전체 마이그레이션 세부 사항은 [Tools](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요
#### GPT-5 가 아닌 모델
-사용자 지정 `model_settings` 없이 GPT-5 가 아닌 모델 이름을 전달하면 SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌아갑니다.
+사용자 지정 `model_settings` 없이 GPT-5 가 아닌 모델 이름을 전달하면 SDK 는 모든 모델과 호환되는 일반 `ModelSettings` 로 되돌아갑니다
### Responses 전용 도구 검색 기능
@@ -98,11 +98,11 @@ preview 호환 요청은 `environment` 및 디스플레이 크기를 먼저 직
- [`tool_namespace()`][agents.tool.tool_namespace]
- `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면
-이 기능들은 Chat Completions 모델과 Responses 가 아닌 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()` 을 추가하고, 네임스페이스 이름 또는 지연 전용 함수 이름을 강제하기보다 `auto` 또는 `required` tool choice 를 통해 모델이 도구를 로드하도록 하세요. 설정 세부 사항과 현재 제약은 [도구](../tools.md#hosted-tool-search)를 참고하세요.
+이 기능들은 Chat Completions 모델 및 Responses 가 아닌 backend 에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()` 을 추가하고, 빈 namespace 이름이나 지연 전용 함수 이름을 강제하는 대신 모델이 `auto` 또는 `required` tool choice 를 통해 도구를 로드하도록 하세요. 설정 세부 사항과 현재 제약은 [Tools](../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 provider 로 해석되는 OpenAI Responses 모델( `"gpt-5.4"` 같은 문자열 모델 이름 포함)에 영향을 줍니다.
+이는 기본 OpenAI provider 로 해석되는 OpenAI Responses 모델(`"gpt-5.4"` 같은 문자열 모델 이름 포함)에 적용됩니다
-전송 선택은 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 가 전송 선택을 제어합니다.
+전송 선택은 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 또는 실행 수준 설정
+#### provider 또는 실행 단위 설정
-provider 단위 또는 실행 단위로 websocket 전송을 구성할 수도 있습니다:
+websocket 전송은 provider 단위 또는 실행 단위로도 구성할 수 있습니다:
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -139,14 +139,14 @@ result = await Runner.run(
#### `MultiProvider` 를 사용한 고급 라우팅
-접두사 기반 모델 라우팅이 필요하다면(예: 하나의 실행에서 `openai/...` 와 `litellm/...` 모델 이름 혼합), [`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` 모델로 라우팅됩니다
+- `openai/...` 는 OpenAI provider 의 별칭으로 처리되어 `openai/gpt-4.1` 은 모델 `gpt-4.1` 로 라우팅됩니다
- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError` 를 발생시킵니다
-OpenAI 호환 엔드포인트가 리터럴 네임스페이스 모델 ID 를 기대하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket 활성화 구성에서는 `MultiProvider` 에서도 `openai_use_responses_websocket=True` 를 유지하세요:
+OpenAI provider 를 리터럴 네임스페이스 모델 ID 를 기대하는 OpenAI 호환 endpoint 로 지정하는 경우, pass-through 동작을 명시적으로 활성화하세요. websocket 활성화 설정에서는 `MultiProvider` 에서도 `openai_use_responses_websocket=True` 를 유지하세요:
```python
from agents import Agent, MultiProvider, RunConfig, Runner
@@ -172,52 +172,52 @@ 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] 에서도 사용할 수 있습니다.
+backend 가 리터럴 `openai/...` 문자열을 기대하면 `openai_prefix_mode="model_id"` 를 사용하세요. backend 가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID 를 기대하면 `unknown_prefix_mode="model_id"` 를 사용하세요. 이 옵션들은 websocket 전송 외부의 `MultiProvider` 에서도 동작합니다. 이 예시는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket 을 활성화한 상태를 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session] 에서도 사용할 수 있습니다
-사용자 지정 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우, websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이런 구성에서는 `websocket_base_url` 을 명시적으로 설정해야 할 수 있습니다.
+사용자 지정 OpenAI 호환 endpoint 또는 proxy 를 사용하는 경우 websocket 전송에도 호환되는 websocket `/responses` endpoint 가 필요합니다. 이런 설정에서는 `websocket_base_url` 을 명시적으로 설정해야 할 수 있습니다
#### 참고 사항
-- 이는 websocket 전송 위의 Responses API 이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 OpenAI 가 아닌 provider 에는 적용되지 않습니다
-- 환경에 아직 없다면 `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)를 참고하세요
+- 이것은 websocket 전송의 Responses API 이며 [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 Responses websocket `/responses` endpoint 를 지원하지 않는 OpenAI 가 아닌 provider 에는 적용되지 않습니다
+- 환경에 `websockets` 패키지가 아직 없다면 설치하세요
+- websocket 전송을 활성화한 뒤 [`Runner.run_streamed()`][agents.run.Runner.run_streamed] 를 직접 사용할 수 있습니다. 여러 턴 워크플로에서 턴 간(중첩된 agent-as-tool 호출 포함) 동일 websocket 연결을 재사용하려면 [`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)를 참조하세요
## OpenAI 가 아닌 모델
-OpenAI 가 아닌 provider 가 필요하면 SDK 의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서는 LiteLLM 을 추가하지 않아도 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다.
+OpenAI 가 아닌 provider 가 필요하면 SDK 의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서 서드파티 adapter 없이도 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다
### OpenAI 가 아닌 provider 통합 방법
-| 접근 방식 | 사용 시점 | 범위 |
+| 접근 방식 | 사용하는 경우 | 범위 |
| --- | --- | --- |
-| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트를 대부분 또는 모든 에이전트의 기본값으로 써야 할 때 | 전역 기본값 |
-| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider 를 단일 실행에 적용해야 할 때 | 실행별 |
-| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 provider 또는 구체적 모델 객체가 필요할 때 | 에이전트별 |
-| LiteLLM (베타) | LiteLLM 고유의 provider 범위 또는 라우팅이 필요할 때 | [LiteLLM](#litellm) 참고 |
+| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 endpoint 를 대부분 또는 모든 에이전트의 기본값으로 사용해야 하는 경우 | 전역 기본값 |
+| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider 를 단일 실행에 적용해야 하는 경우 | 실행 단위 |
+| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 provider 또는 구체적 모델 객체가 필요한 경우 | 에이전트 단위 |
+| 서드파티 adapter | 내장 경로가 제공하지 않는 adapter 관리 provider 범위 또는 라우팅이 필요한 경우 | [서드파티 adapters](#third-party-adapters) 참조 |
-다음 내장 경로로 다른 LLM provider 를 통합할 수 있습니다:
+이 내장 경로들로 다른 LLM provider 를 통합할 수 있습니다:
-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 provider 가 OpenAI 호환 API endpoint 를 제공하고 `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)를 참조하세요
-`platform.openai.com` 의 API 키가 없는 경우, `set_tracing_disabled()` 로 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다.
+`platform.openai.com` 의 API 키가 없는 경우에는 `set_tracing_disabled()` 로 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다
!!! note
- 이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider 가 아직 Responses API 를 지원하지 않기 때문입니다. LLM provider 가 이를 지원한다면 Responses 사용을 권장합니다
+ 이 예시들에서는 많은 LLM provider 가 아직 Responses API 를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. LLM provider 가 이를 지원한다면 Responses 사용을 권장합니다
## 하나의 워크플로에서 모델 혼합
-하나의 워크플로 안에서 에이전트별로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다:
+단일 워크플로 내에서 각 에이전트마다 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어, 분류에는 더 작고 빠른 모델을 사용하고 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent] 를 구성할 때는 다음 중 하나로 특정 모델을 선택할 수 있습니다:
1. 모델 이름 전달
-2. 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달
-3. [`Model`][agents.models.interface.Model] 구현을 직접 전달
+2. 임의의 모델 이름 + 해당 이름을 Model 인스턴스로 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달
+3. [`Model`][agents.models.interface.Model] 구현을 직접 제공
!!! note
- SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태는 지원 기능과 도구 세트가 다르므로 워크플로별로 하나의 모델 형태만 사용하는 것을 권장합니다. 워크플로에서 모델 형태를 혼합해야 한다면, 사용하는 모든 기능이 양쪽 모두에서 사용 가능한지 확인하세요
+ SDK 는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태는 지원 기능과 도구 집합이 다르므로 워크플로마다 단일 모델 형태를 사용하는 것을 권장합니다. 워크플로에서 모델 형태를 혼합해야 한다면 사용 중인 모든 기능이 양쪽 모두에서 사용 가능한지 확인하세요
```python
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -253,7 +253,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
@@ -268,19 +268,19 @@ english_agent = Agent(
## 고급 OpenAI Responses 설정
-OpenAI Responses 경로에서 더 세밀한 제어가 필요하면 `ModelSettings` 부터 시작하세요.
+OpenAI Responses 경로에서 더 많은 제어가 필요하면 `ModelSettings` 부터 시작하세요
-### 공통 고급 `ModelSettings` 옵션
+### 일반적인 고급 `ModelSettings` 옵션
-OpenAI Responses API 를 사용하는 경우, 여러 요청 필드가 이미 `ModelSettings` 에 직접 대응되므로 이를 위해 `extra_args` 를 사용할 필요가 없습니다.
+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`: 생성된 응답을 이후 조회를 위해 서버 측에 저장할지 제어. 이는 response ID 에 의존하는 후속 워크플로 및 `store=False` 일 때 로컬 입력으로 대체해야 할 수 있는 세션 압축 흐름에 중요합니다
- `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) 참고
+- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 payload 요청
+- `top_logprobs`: 출력 텍스트의 상위 토큰 logprobs 요청. SDK 는 `message.output_text.logprobs` 도 자동으로 추가합니다
+- `retry`: 모델 호출에 대해 runner 관리 재시도 설정 선택 적용. [Runner 관리 재시도](#runner-managed-retries) 참조
```python
from agents import Agent, ModelSettings
@@ -299,13 +299,13 @@ research_agent = Agent(
)
```
-`store=False` 를 설정하면 Responses API 는 해당 응답을 나중에 서버 측에서 조회 가능하게 유지하지 않습니다. 이는 stateless 또는 zero-data-retention 스타일 흐름에 유용하지만, 그렇지 않으면 응답 ID 를 재사용하던 기능이 대신 로컬 관리 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [세션 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참고하세요.
+`store=False` 를 설정하면 Responses API 는 이후 서버 측 조회를 위해 해당 응답을 보관하지 않습니다. 이는 무상태 또는 zero-data-retention 스타일 흐름에 유용하지만, 응답 ID 를 재사용하던 기능은 대신 로컬 관리 상태에 의존해야 함을 의미합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 은 마지막 응답이 저장되지 않았을 때 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [Sessions 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요
### `extra_args` 전달
-SDK 가 아직 최상위에서 직접 노출하지 않는 provider 전용 또는 최신 요청 필드가 필요할 때 `extra_args` 를 사용하세요.
+SDK 가 아직 최상위에 직접 노출하지 않는 provider 전용 또는 최신 요청 필드가 필요할 때 `extra_args` 를 사용하세요
-또한 OpenAI Responses API 사용 시 [다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create) (예: `user`, `service_tier` 등)가 있습니다. 이들이 최상위에 없으면 `extra_args` 로 전달할 수 있습니다.
+또한 OpenAI 의 Responses API 사용 시 [추가 선택 매개변수](https://platform.openai.com/docs/api-reference/responses/create) (예: `user`, `service_tier` 등)도 있습니다. 최상위에 없다면 `extra_args` 로 전달할 수 있습니다
```python
from agents import Agent, ModelSettings
@@ -323,7 +323,7 @@ english_agent = Agent(
## Runner 관리 재시도
-재시도는 런타임 전용이며 옵트인입니다. `ModelSettings(retry=...)` 를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK 는 일반 모델 요청을 재시도하지 않습니다.
+재시도는 런타임 전용이며 옵트인입니다. `ModelSettings(retry=...)` 를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK 는 일반 모델 요청을 재시도하지 않습니다
```python
from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
@@ -363,73 +363,73 @@ agent = Agent(
-재시도 정책은 다음 정보를 가진 [`RetryPolicyContext`][agents.retry.RetryPolicyContext] 를 받습니다:
+재시도 정책은 [`RetryPolicyContext`][agents.retry.RetryPolicyContext] 를 받으며 다음을 포함합니다:
-- `attempt` 와 `max_retries` 로 시도 횟수 인지형 결정 가능
+- `attempt` 와 `max_retries` 로 시도 횟수 인지 의사결정 가능
- `stream` 으로 스트리밍/비스트리밍 동작 분기 가능
-- 원문 확인을 위한 `error`
+- 원시 검사 용도의 `error`
- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 정보
-- 기본 모델 어댑터가 재시도 가이드를 제공할 수 있는 경우 `provider_advice`
+- 하위 모델 adapter 가 재시도 가이드를 제공할 수 있을 때의 `provider_advice`
정책은 다음 중 하나를 반환할 수 있습니다:
- 단순 재시도 결정을 위한 `True` / `False`
-- 지연을 재정의하거나 진단 사유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision]
+- 지연을 재정의하거나 진단 이유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision]
-SDK 는 `retry_policies` 에서 즉시 사용 가능한 헬퍼를 제공합니다:
+SDK 는 `retry_policies` 에 준비된 헬퍼를 제공합니다:
| 헬퍼 | 동작 |
| --- | --- |
-| `retry_policies.never()` | 항상 비활성화 |
+| `retry_policies.never()` | 항상 사용 안 함 |
| `retry_policies.provider_suggested()` | 가능할 때 provider 재시도 권고를 따름 |
-| `retry_policies.network_error()` | 일시적 전송/타임아웃 실패와 매칭 |
+| `retry_policies.network_error()` | 일시적 전송 및 timeout 실패와 매칭 |
| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 매칭 |
| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연으로 재시도 |
-| `retry_policies.any(...)` | 중첩 정책 중 하나라도 활성화하면 재시도 |
-| `retry_policies.all(...)` | 중첩 정책 모두 활성화할 때만 재시도 |
+| `retry_policies.any(...)` | 중첩 정책 중 하나라도 선택하면 재시도 |
+| `retry_policies.all(...)` | 중첩 정책 모두가 선택할 때만 재시도 |
-정책을 조합할 때 `provider_suggested()` 가 가장 안전한 첫 구성 요소입니다. provider 가 구분 가능한 경우 provider veto 와 replay-safe 승인 정보를 보존하기 때문입니다.
+정책 조합 시 `provider_suggested()` 가 가장 안전한 첫 구성 요소입니다. provider 가 이를 구분할 수 있을 때 provider veto 와 replay-safety 승인을 보존하기 때문입니다
##### 안전 경계
일부 실패는 자동 재시도되지 않습니다:
- Abort 오류
-- provider 권고가 replay 를 안전하지 않다고 표시한 요청
-- replay 가 안전하지 않게 되는 방식으로 출력이 이미 시작된 이후의 스트리밍 실행
+- provider 권고에서 replay 가 안전하지 않다고 표시된 요청
+- replay 를 안전하지 않게 만드는 방식으로 출력이 이미 시작된 스트리밍 실행
-`previous_response_id` 또는 `conversation_id` 를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이런 요청에서는 `network_error()` 나 `http_status([500])` 같은 비-provider 조건만으로는 충분하지 않습니다. 재시도 정책에 일반적으로 `retry_policies.provider_suggested()` 를 통한 replay-safe provider 승인이 포함되어야 합니다.
+`previous_response_id` 또는 `conversation_id` 를 사용하는 상태 저장형 후속 요청도 더 보수적으로 처리됩니다. 이런 요청에서는 `network_error()` 또는 `http_status([500])` 같은 비provider predicate 만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()` 를 통한 provider 의 replay-safe 승인이 포함되어야 합니다
##### Runner 와 에이전트 병합 동작
`retry` 는 runner 수준과 에이전트 수준 `ModelSettings` 사이에서 deep-merge 됩니다:
-- 에이전트는 `retry.max_retries` 만 재정의하고 runner 의 `policy` 를 상속할 수 있습니다
-- 에이전트는 `retry.backoff` 의 일부만 재정의하고 runner 의 같은 수준 다른 backoff 필드를 유지할 수 있습니다
-- `policy` 는 런타임 전용이므로 직렬화된 `ModelSettings` 는 `max_retries` 와 `backoff` 는 유지하지만 콜백 자체는 생략합니다
+- 에이전트는 `retry.max_retries` 만 재정의하고 runner 의 `policy` 는 상속할 수 있습니다
+- 에이전트는 `retry.backoff` 일부만 재정의하고 나머지 backoff 필드는 runner 값을 유지할 수 있습니다
+- `policy` 는 런타임 전용이므로 직렬화된 `ModelSettings` 에는 `max_retries` 와 `backoff` 는 남고 콜백 자체는 제외됩니다
-더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [`examples/basic/retry_litellm.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) 및 [adapter 기반 재시도 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요
## OpenAI 가 아닌 provider 문제 해결
### 트레이싱 클라이언트 오류 401
-트레이싱 관련 오류가 발생하면, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다:
+트레이싱 관련 오류가 발생한다면, 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다:
-1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
-2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 의 키여야 합니다
-3. OpenAI 가 아닌 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참고
+1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
+2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 키여야 합니다
+3. OpenAI 가 아닌 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참조
### Responses API 지원
-SDK 는 기본적으로 Responses API 를 사용하지만, 많은 다른 LLM provider 는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결하려면 두 가지 옵션이 있습니다:
+SDK 는 기본적으로 Responses API 를 사용하지만, 다른 많은 LLM provider 는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 이슈를 볼 수 있습니다. 해결 방법은 두 가지입니다:
-1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 호출. 이는 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우 동작합니다
+1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] 호출. 환경 변수로 `OPENAI_API_KEY` 와 `OPENAI_BASE_URL` 을 설정하는 경우 동작합니다
2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 사용. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다
### structured outputs 지원
-일부 모델 provider 는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이 경우 다음과 유사한 오류가 발생할 수 있습니다:
+일부 모델 provider 는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이 경우 때때로 다음과 같은 오류가 발생합니다:
```
@@ -437,24 +437,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
-이것은 일부 모델 provider 의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이 문제를 해결 중이지만, JSON schema 출력을 지원하는 provider 에 의존하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 깨질 수 있습니다.
+이는 일부 모델 provider 의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 이 문제에 대한 수정 작업을 진행 중이지만, JSON schema 출력을 지원하는 provider 에 의존하는 것을 권장합니다. 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 중단될 수 있습니다
## provider 간 모델 혼합
-모델 provider 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 file search 및 web search 를 지원하지만 많은 다른 provider 는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요:
+모델 provider 간 기능 차이를 인지하지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI 는 structured outputs, 멀티모달 입력, 호스티드 file search 와 web search 를 지원하지만 다른 많은 provider 는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요:
-- 지원하지 않는 provider 에는 지원되지 않는 `tools` 를 보내지 마세요
-- 텍스트 전용 모델 호출 전에 멀티모달 입력을 필터링하세요
-- structured JSON 출력 미지원 provider 는 때때로 유효하지 않은 JSON 을 생성할 수 있음을 유의하세요
+- 지원하지 않는 `tools` 를 이를 이해하지 못하는 provider 에 보내지 마세요
+- 텍스트 전용 모델 호출 전 멀티모달 입력을 필터링하세요
+- structured JSON 출력을 지원하지 않는 provider 는 때때로 유효하지 않은 JSON 을 생성할 수 있음을 유의하세요
-## LiteLLM
+## 서드파티 adapters
-LiteLLM 지원은 OpenAI 가 아닌 provider 를 Agents SDK 워크플로에 포함해야 하는 경우를 위한 best-effort 베타 기능으로 제공됩니다.
+SDK 의 내장 provider 통합 지점만으로 부족할 때만 서드파티 adapter 를 사용하세요. 이 SDK 에서 OpenAI 모델만 사용하는 경우 Any-LLM 이나 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 우선하세요. 서드파티 adapter 는 OpenAI 모델과 OpenAI 가 아닌 provider 를 함께 사용해야 하거나, 내장 경로가 제공하지 않는 adapter 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. adapter 는 SDK 와 업스트림 모델 provider 사이에 추가 호환성 계층을 더하므로 기능 지원과 요청 의미가 provider 별로 달라질 수 있습니다. SDK 는 현재 Any-LLM 과 LiteLLM 을 best-effort 베타 adapter 통합으로 포함합니다
-이 SDK 와 함께 OpenAI 모델을 사용하는 경우 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 권장합니다.
+### Any-LLM
-OpenAI 모델과 OpenAI 가 아닌 provider 를 함께 사용해야 하는 경우, 특히 Chat Completions 호환 API 를 통해 사용한다면 LiteLLM 을 베타 옵션으로 사용할 수 있지만 모든 설정에서 최적 선택은 아닐 수 있습니다.
+Any-LLM 지원은 Any-LLM 관리 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 형태로 제공됩니다
-OpenAI 가 아닌 provider 에 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] 을 직접 인스턴스화할 수 있습니다.
+업스트림 provider 경로에 따라 Any-LLM 은 Responses API, Chat Completions 호환 API 또는 provider 전용 호환성 계층을 사용할 수 있습니다
-LiteLLM 응답이 SDK 사용량 메트릭을 채우게 하려면 `ModelSettings(include_usage=True)` 를 전달하세요.
\ No newline at end of file
+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 은 여전히 서드파티 adapter 계층이므로 provider 의존성과 기능 격차는 SDK 가 아니라 Any-LLM 업스트림에서 정의됩니다. 사용량 지표는 업스트림 provider 가 반환할 때 자동 전파되지만, 스트리밍 Chat Completions backend 는 사용량 청크를 내보내기 전에 `ModelSettings(include_usage=True)` 가 필요할 수 있습니다. structured outputs, 도구 호출, 사용량 보고, Responses 전용 동작에 의존한다면 배포하려는 정확한 provider backend 를 검증하세요
+
+### LiteLLM
+
+LiteLLM 지원은 LiteLLM 전용 provider 범위 또는 라우팅이 필요한 경우를 위해 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 기반 provider 는 기본적으로 SDK 사용량 지표를 채우지 않습니다. 사용량 보고가 필요하면 `ModelSettings(include_usage=True)` 를 전달하고 structured outputs, 도구 호출, 사용량 보고 또는 adapter 전용 라우팅 동작에 의존한다면 배포하려는 정확한 provider backend 를 검증하세요
\ No newline at end of file
diff --git a/docs/ko/models/litellm.md b/docs/ko/models/litellm.md
index c610be0644..f6db4dd095 100644
--- a/docs/ko/models/litellm.md
+++ b/docs/ko/models/litellm.md
@@ -5,9 +5,9 @@ search:
# LiteLLM
-이 페이지는 [Models의 LiteLLM 섹션](index.md#litellm)(으)로 이동되었습니다
+이 페이지는 [Models의 서드파티 어댑터 섹션](index.md#third-party-adapters)으로 이동되었습니다.
-자동으로 리디렉션되지 않으면 위 링크를 사용하세요
\ No newline at end of file
+자동으로 리디렉션되지 않으면 위 링크를 사용하세요.
\ No newline at end of file
diff --git a/docs/ko/tracing.md b/docs/ko/tracing.md
index 6a2c46e610..cd360544b7 100644
--- a/docs/ko/tracing.md
+++ b/docs/ko/tracing.md
@@ -4,31 +4,31 @@ 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`로 설정하여 트레이싱을 비활성화할 수 있습니다
+ 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를 사용하면서 ZDR(Zero Data Retention) 정책으로 운영되는 조직에서는 트레이싱을 사용할 수 없습니다.***
## 트레이스와 스팬
-- **트레이스**는 "워크플로"의 단일 end-to-end 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
+- **트레이스**는 "워크플로"의 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
- `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "Code generation" 또는 "Customer service"
- - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다
- - `group_id`: 선택적 그룹 ID로, 같은 대화의 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다
+ - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>` 이어야 합니다
+ - `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 생성 정보가 포함됩니다
## 기본 트레이싱
@@ -42,15 +42,15 @@ Agents SDK에는 기본 제공 트레이싱이 포함되어 있어 에이전트
- 핸드오프는 `handoff_span()`으로 감싸집니다
- 오디오 입력(음성-텍스트)은 `transcription_span()`으로 감싸집니다
- 오디오 출력(텍스트-음성)은 `speech_span()`으로 감싸집니다
-- 관련 오디오 스팬은 `speech_group_span()` 하위로 부모 지정될 수 있습니다
+- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식으로 연결될 수 있습니다
-기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용할 때 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]로 이름 및 기타 속성을 구성할 수도 있습니다.
+기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하면 이 이름을 설정할 수 있고, [`RunConfig`][agents.run.RunConfig]로 이름과 기타 속성을 구성할 수도 있습니다.
-또한 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정해 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상).
+또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상(대체 또는 보조 대상)으로 전송할 수 있습니다.
## 상위 수준 트레이스
-경우에 따라 여러 번의 `run()` 호출을 하나의 트레이스에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다.
+때로는 `run()` 여러 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다.
```python
from agents import Agent, Runner, trace
@@ -65,60 +65,60 @@ async def main():
print(f"Rating: {second_result.final_output}")
```
-1. 두 번의 `Runner.run` 호출이 `with trace()`로 감싸져 있으므로, 개별 실행은 각각 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다
+1. `Runner.run`에 대한 두 호출이 `with trace()`로 감싸져 있으므로, 각 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다
## 트레이스 생성
-[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요합니다. 방법은 두 가지입니다:
+[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작 및 종료되어야 하며, 이를 위한 두 가지 방법이 있습니다:
-1. **권장**: 트레이스를 컨텍스트 매니저로 사용합니다. 즉, `with trace(...) as my_trace` 형태입니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작되고 종료됩니다
-2. [`trace.start()`][agents.tracing.Trace.start] 및 [`trace.finish()`][agents.tracing.Trace.finish]를 수동으로 호출할 수도 있습니다
+1. **권장**: 트레이스를 컨텍스트 매니저로 사용합니다. 즉 `with trace(...) as my_trace` 형태입니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작되고 종료됩니다
+2. [`trace.start()`][agents.tracing.Trace.start]와 [`trace.finish()`][agents.tracing.Trace.finish]를 수동으로 호출할 수도 있습니다
-현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 이는 동시성 환경에서도 자동으로 작동함을 의미합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 업데이트하려면 `start()`/`finish()`에 `mark_as_current`와 `reset_current`를 전달해야 합니다.
+현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 즉, 동시성에서도 자동으로 동작합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 업데이트하려면 `start()`/`finish()`에 `mark_as_current` 및 `reset_current`를 전달해야 합니다.
## 스팬 생성
-다양한 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 지정 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수도 제공됩니다.
+다양한 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 정의 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수도 제공됩니다.
스팬은 자동으로 현재 트레이스의 일부가 되며, Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다.
-## 민감 데이터
+## 민감한 데이터
-일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다.
+특정 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다.
`generation_span()`은 LLM 생성의 입력/출력을 저장하고, `function_span()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.
-마찬가지로 Audio 스팬은 기본적으로 입력 및 출력 오디오에 대한 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`으로 export하여 코드 변경 없이 기본값을 설정할 수 있습니다.
+기본적으로 `trace_include_sensitive_data`는 `True`입니다. 코드 없이 기본값을 설정하려면 앱 실행 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`으로 export하면 됩니다.
-## 사용자 지정 트레이싱 프로세서
+## 사용자 정의 트레이싱 프로세서
-트레이싱의 상위 수준 아키텍처는 다음과 같습니다:
+트레이싱의 상위 아키텍처는 다음과 같습니다:
-- 초기화 시 트레이스 생성을 담당하는 전역 [`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]에 전송합니다. `BackendSpanExporter`는 스팬과 트레이스를 배치로 OpenAI 백엔드에 내보냅니다
-이 기본 설정을 사용자 지정하여 트레이스를 대체 또는 추가 백엔드로 전송하거나 exporter 동작을 수정하려면 두 가지 옵션이 있습니다:
+이 기본 설정을 사용자 정의해 트레이스를 대체 또는 추가 백엔드로 전송하거나 exporter 동작을 수정하려면 두 가지 방법이 있습니다:
-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 모델에서의 트레이싱
-트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하기 위해 OpenAI API 키를 OpenAI가 아닌 모델과 함께 사용할 수 있습니다.
+OpenAI API 키를 비 OpenAI 모델과 함께 사용하면 트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 사용할 수 있습니다. 어댑터 선택 및 설정 시 주의사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요.
```python
import os
from agents import set_tracing_export_api_key, Agent, Runner
-from agents.extensions.models.litellm_model import LitellmModel
+from agents.extensions.models.any_llm_model import AnyLLMModel
tracing_api_key = os.environ["OPENAI_API_KEY"]
set_tracing_export_api_key(tracing_api_key)
-model = LitellmModel(
- model="your-model-name",
+model = AnyLLMModel(
+ model="your-provider/your-model-name",
api_key="your-api-key",
)
diff --git a/docs/ko/usage.md b/docs/ko/usage.md
index 7994c3ae88..9eb5d87e98 100644
--- a/docs/ko/usage.md
+++ b/docs/ko/usage.md
@@ -2,9 +2,9 @@
search:
exclude: true
---
-# 사용법
+# 사용
-Agents SDK는 모든 실행의 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하고 비용 모니터링, 한도 적용, 분석 기록에 활용할 수 있습니다
+Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하여 비용 모니터링, 제한 적용, 분석 기록에 활용할 수 있습니다.
## 추적 항목
@@ -17,9 +17,9 @@ Agents SDK는 모든 실행의 토큰 사용량을 자동으로 추적합니다.
- `input_tokens_details.cached_tokens`
- `output_tokens_details.reasoning_tokens`
-## 실행에서 사용량 액세스
+## 실행에서 사용량 접근
-`Runner.run(...)` 이후 `result.context_wrapper.usage`로 사용량에 액세스합니다
+`Runner.run(...)` 이후 `result.context_wrapper.usage`를 통해 사용량에 접근할 수 있습니다.
```python
result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -31,29 +31,20 @@ print("Output tokens:", usage.output_tokens)
print("Total tokens:", usage.total_tokens)
```
-사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 대해 집계됩니다
+사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다.
-### LiteLLM 모델에서 사용량 활성화
+### 서드파티 어댑터에서 사용량 활성화
-LiteLLM 제공자는 기본적으로 사용량 지표를 보고하지 않습니다. [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 사용하는 경우, LiteLLM 응답이 `result.context_wrapper.usage`를 채우도록 에이전트에 `ModelSettings(include_usage=True)`를 전달하세요. 설정 안내와 코드 예제는 Models 가이드의 [LiteLLM note](models/index.md#litellm)를 참고하세요
+사용량 보고는 서드파티 어댑터와 제공자 백엔드에 따라 달라집니다. 어댑터 기반 모델을 사용하고 정확한 `result.context_wrapper.usage` 값이 필요하다면 다음을 확인하세요:
-```python
-from agents import Agent, ModelSettings, Runner
-from agents.extensions.models.litellm_model import LitellmModel
-
-agent = Agent(
- name="Assistant",
- model=LitellmModel(model="your/model", api_key="..."),
- model_settings=ModelSettings(include_usage=True),
-)
+- `AnyLLMModel`에서는 업스트림 제공자가 사용량을 반환하면 자동으로 전파됩니다. 스트리밍 Chat Completions 백엔드의 경우, 사용량 청크가 전송되기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다
+- `LitellmModel`에서는 일부 제공자 백엔드가 기본적으로 사용량을 보고하지 않으므로, `ModelSettings(include_usage=True)`가 자주 필요합니다
-result = await Runner.run(agent, "What's the weather in Tokyo?")
-print(result.context_wrapper.usage.total_tokens)
-```
+모델 가이드의 [서드파티 어댑터](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?")
@@ -62,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")
@@ -76,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):
@@ -95,5 +86,5 @@ class MyHooks(RunHooks):
- [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조
- [`RequestUsage`][agents.usage.RequestUsage] - 요청별 사용량 세부 정보
-- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 액세스
+- [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근
- [`RunHooks`][agents.run.RunHooks] - 사용량 추적 라이프사이클에 훅 연결
\ No newline at end of file
diff --git a/docs/zh/examples.md b/docs/zh/examples.md
index 8ff4c17215..4ca594faf4 100644
--- a/docs/zh/examples.md
+++ b/docs/zh/examples.md
@@ -4,62 +4,62 @@ search:
---
# 示例
-请在 [repo](https://github.com/openai/openai-agents-python/tree/main/examples) 的示例部分查看 SDK 的多种 sample code。这些示例按多个目录组织，用于展示不同的模式与能力。
+在[repo](https://github.com/openai/openai-agents-python/tree/main/examples)的示例部分查看 SDK 的各种 sample code。这些示例按多个目录组织，展示了不同的模式与能力。
## 目录
- **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
- 此目录中的示例展示了常见的智能体设计模式，例如
+ 该目录中的示例展示了常见的智能体设计模式，例如
- 确定性工作流
- Agents as tools
- 并行智能体执行
- 条件化工具使用
- 输入/输出安全防护措施
- - LLM 作为评审
+ - LLM 作为评判者
- 路由
- 流式传输安全防护措施
- - 审批流程的自定义拒绝消息（`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 的基础能力，例如
- - Hello World 示例（默认模型、GPT-5、开源权重模型）
+ - Hello world 示例（默认模型、GPT-5、开放权重模型）
- 智能体生命周期管理
- 动态系统提示词
- 流式传输输出（文本、条目、函数调用参数）
- - 跨多轮共享会话辅助器的 Responses websocket 传输（`examples/basic/stream_ws.py`）
+ - 跨轮次使用共享会话助手的 Responses websocket 传输（`examples/basic/stream_ws.py`）
- 提示词模板
- - 文件处理（本地与远程、图像与 PDF）
- - 用量追踪
- - Runner 管理的重试设置（`examples/basic/retry.py`）
- - 通过 LiteLLM 使用 Runner 管理的重试（`examples/basic/retry_litellm.py`）
+ - 文件处理（本地与远程，图像与 PDF）
+ - 用量跟踪
+ - 由 Runner 管理的重试设置（`examples/basic/retry.py`）
+ - 通过第三方适配器进行由 Runner 管理的重试（`examples/basic/retry_litellm.py`）
- 非严格输出类型
- - 上一个 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):**
查看带有消息过滤的智能体任务转移实践示例。
- **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
- 展示如何使用托管 MCP（Model context protocol）连接器和审批流程的示例。
+ 演示如何使用托管 MCP（Model Context Protocol）连接器与审批的示例。
- **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
- 了解如何基于 MCP（Model context protocol）构建智能体，包括：
+ 了解如何使用 MCP（Model Context Protocol）构建智能体，包括：
- 文件系统示例
- Git 示例
- MCP 提示词服务示例
- - SSE（服务端发送事件）示例
+ - SSE（Server-Sent Events）示例
- 可流式 HTTP 示例
- **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
- 智能体的不同内存实现示例，包括：
+ 不同智能体记忆实现的示例，包括：
- SQLite 会话存储
- 高级 SQLite 会话存储
@@ -72,32 +72,32 @@ search:
- 使用 `ModelSettings(store=False)` 的无状态 Responses 压缩（`examples/memory/compaction_session_stateless_example.py`）
- **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
- 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和 LiteLLM 集成。
+ 探索如何在 SDK 中使用非 OpenAI 模型，包括自定义提供方和第三方适配器。
- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
展示如何使用 SDK 构建实时体验的示例，包括：
- 使用结构化文本与图像消息的 Web 应用模式
- 命令行音频循环与播放处理
- - 基于 WebSocket 的 Twilio Media Streams 集成
+ - 通过 WebSocket 集成 Twilio Media Streams
- 使用 Realtime Calls API 附加流程的 Twilio SIP 集成
- **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
- 展示如何处理推理内容与 structured outputs 的示例。
+ 演示如何处理推理内容和 structured outputs 的示例。
- **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
- 简单的深度研究克隆，展示复杂的多智能体研究工作流。
+ 简单的深度研究克隆，展示了复杂的多智能体研究工作流。
- **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
了解如何实现由OpenAI托管的工具和实验性 Codex 工具能力，例如：
- - 网络检索及带过滤器的网络检索
+ - 网络检索与带过滤器的网络检索
- 文件检索
- 代码解释器
- 带内联技能的托管容器 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/models/index.md b/docs/zh/models/index.md
index 0f2f1cfbab..02a98a3acb 100644
--- a/docs/zh/models/index.md
+++ b/docs/zh/models/index.md
@@ -4,42 +4,42 @@ 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 provider 的 Responses 模型路径 | [OpenAI 模型](#openai-models) |
+| 仅使用 OpenAI 模型 | 使用默认 OpenAI provider 与 Responses 模型路径 | [OpenAI 模型](#openai-models) |
| 通过 websocket 传输使用 OpenAI Responses API | 保持 Responses 模型路径并启用 websocket 传输 | [Responses WebSocket 传输](#responses-websocket-transport) |
| 使用一个非 OpenAI provider | 从内置 provider 集成点开始 | [非 OpenAI 模型](#non-openai-models) |
-| 在多个智能体之间混用模型或 provider | 按每次 run 或每个智能体选择 provider，并检查功能差异 | [在单个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨 provider 混用模型](#mixing-models-across-providers) |
+| 在智能体之间混合模型或 providers | 按每次运行或每个智能体选择 provider，并检查功能差异 | [在单个工作流中混合模型](#mixing-models-in-one-workflow) 和 [跨 providers 混合模型](#mixing-models-across-providers) |
| 调整高级 OpenAI Responses 请求设置 | 在 OpenAI Responses 路径上使用 `ModelSettings` | [高级 OpenAI Responses 设置](#advanced-openai-responses-settings) |
-| 为非 OpenAI Chat Completions provider 使用 LiteLLM | 将 LiteLLM 视为 beta 备用方案 | [LiteLLM](#litellm) |
+| 使用第三方适配器进行非 OpenAI 或混合 provider 路由 | 比较受支持的 beta 适配器，并验证你计划上线的 provider 路径 | [第三方适配器](#third-party-adapters) |
## OpenAI 模型
-对于大多数仅使用 OpenAI 的应用，推荐路径是使用字符串模型名称配合默认 OpenAI provider，并保持在 Responses 模型路径上。
+对于大多数仅使用 OpenAI 的应用，推荐路径是使用字符串模型名与默认 OpenAI provider，并保持在 Responses 模型路径上。
-当你在初始化 `Agent` 时未指定模型，将使用默认模型。当前默认模型是 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)，以兼顾兼容性和低延迟。如果你有权限，我们建议将智能体设置为 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 以获得更高质量，同时保持显式 `model_settings`。
+当你在初始化 `Agent` 时未指定模型，将使用默认模型。当前默认是 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)，以兼顾兼容性与低延迟。如果你有权限，我们建议将智能体设置为 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 以获得更高质量，同时显式设置 `model_settings`。
-如果你想切换到 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 等其他模型，可通过两种方式配置智能体。
+如果你想切换到其他模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)），有两种方式配置智能体。
### 默认模型
-首先，如果你希望所有未设置自定义模型的智能体都持续使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
+首先，如果你希望所有未设置自定义模型的智能体都稳定使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
```bash
export OPENAI_DEFAULT_MODEL=gpt-5.4
python3 my_awesome_agent.py
```
-其次，你可以通过 `RunConfig` 为一次 run 设置默认模型。如果你未为智能体设置模型，将使用该 run 的模型。
+其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果某个智能体未设置模型，将使用该运行的模型。
```python
from agents import Agent, RunConfig, Runner
@@ -58,7 +58,7 @@ result = await Runner.run(
#### GPT-5 模型
-当你以这种方式使用任意 GPT-5 模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)）时，SDK 会应用默认 `ModelSettings`。它会设置最适合大多数用例的选项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
+当你以这种方式使用任意 GPT-5 模型（例如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)）时，SDK 会应用默认 `ModelSettings`。它会设置适用于大多数场景的最佳选项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
```python
from openai.types.shared import Reasoning
@@ -74,21 +74,21 @@ my_agent = Agent(
)
```
-为了降低延迟，建议在 `gpt-5.4` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）在构建交互式智能体应用时也依然是稳健选择。
+为了更低延迟，建议在 `gpt-5.4` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）在构建交互式智能体应用时也依然是稳健选择。
#### ComputerTool 模型选择
-如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，则实际 Responses 请求中生效的模型会决定 SDK 发送哪种 computer-tool 载荷。显式 `gpt-5.4` 请求会使用 GA 内置 `computer` 工具，而显式 `computer-use-preview` 请求会保留旧的 `computer_use_preview` 载荷。
+如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求中的生效模型将决定 SDK 发送哪种 computer-tool 负载。显式的 `gpt-5.4` 请求会使用 GA 内置 `computer` 工具；显式的 `computer-use-preview` 请求则保持旧版 `computer_use_preview` 负载。
-由提示词管理的调用是主要例外。如果提示词模板持有模型且 SDK 在请求中省略 `model`，SDK 会默认使用与 preview 兼容的 computer 载荷，以避免猜测提示词绑定了哪个模型。要在该流程中保持 GA 路径，可在请求中显式设置 `model="gpt-5.4"`，或通过 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。
+由提示词管理的调用是主要例外。如果提示模板拥有模型且 SDK 在请求中省略 `model`，SDK 会默认使用与 preview 兼容的 computer 负载，以避免猜测提示绑定了哪个模型。要在该流程中保持 GA 路径，可在请求中显式设置 `model="gpt-5.4"`，或通过 `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`，这些字符串会继续按普通函数名处理。
-与 preview 兼容的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程应在发送请求前传入具体的 `Computer` 或 `AsyncComputer` 实例，或强制 GA 选择器。完整迁移细节见 [工具](../tools.md#computertool-and-the-responses-computer-tool)。
+与 preview 兼容的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词管理流程应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制使用 GA 选择器。完整迁移细节见 [Tools](../tools.md#computertool-and-the-responses-computer-tool)。
#### 非 GPT-5 模型
-如果你传入非 GPT-5 模型名且未自定义 `model_settings`，SDK 会回退为与任意模型兼容的通用 `ModelSettings`。
+如果你传入非 GPT-5 模型名且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。
### 仅 Responses 的工具检索功能
@@ -98,7 +98,7 @@ my_agent = Agent(
- [`tool_namespace()`][agents.tool.tool_namespace]
- `@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](../tools.md#hosted-tool-search)。
### Responses 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.4"` 这样的字符串模型名）。
+这会影响由默认 OpenAI provider 解析出的 OpenAI Responses 模型（包括如 `"gpt-5.4"` 的字符串模型名）。
-传输方式的选择发生在 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 控制传输选择，而不是全局默认值。
+传输方式的选择发生在 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 或 run 级设置
+#### Provider 或运行级设置
-你也可以按 provider 或按 run 配置 websocket 传输：
+你也可以按 provider 或按运行配置 websocket 传输：
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -139,14 +139,14 @@ result = await Runner.run(
#### 使用 `MultiProvider` 的高级路由
-如果你需要基于前缀的模型路由（例如在一次 run 中混用 `openai/...` 和 `litellm/...` 模型名），请使用 [`MultiProvider`][agents.MultiProvider]，并在其中设置 `openai_use_responses_websocket=True`。
+如果你需要基于前缀的模型路由（例如在一次运行中混用 `openai/...` 和 `any-llm/...` 模型名），请使用 [`MultiProvider`][agents.MultiProvider]，并在其中设置 `openai_use_responses_websocket=True`。
-`MultiProvider` 保留了两个历史默认行为：
+`MultiProvider` 保留两个历史默认行为：
-- `openai/...` 被视为 OpenAI provider 的别名，因此 `openai/gpt-4.1` 会被路由为模型 `gpt-4.1`。
+- `openai/...` 被视为 OpenAI provider 的别名，因此 `openai/gpt-4.1` 会按模型 `gpt-4.1` 路由。
- 未知前缀会抛出 `UserError`，而不是透传。
-当你将 OpenAI provider 指向一个期望字面命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的设置中，也要在 `MultiProvider` 上保持 `openai_use_responses_websocket=True`：
+当你将 OpenAI provider 指向一个期望字面量命名空间模型 ID 的 OpenAI 兼容端点时，请显式启用透传行为。在启用 websocket 的设置中，也请在 `MultiProvider` 上保持 `openai_use_responses_websocket=True`：
```python
from agents import Agent, MultiProvider, RunConfig, Runner
@@ -172,48 +172,48 @@ 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]。
-如果你使用自定义 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 provider，除非它们支持 Responses websocket `/responses` 端点。
+- 这是基于 websocket 传输的 Responses API，不是[Realtime API](../realtime/guide.md)。除非支持 Responses websocket `/responses` 端点，否则不适用于 Chat Completions 或非 OpenAI providers。
- 如果你的环境中尚未安装，请安装 `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)。
+- 启用 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)。
## 非 OpenAI 模型
-如果你需要非 OpenAI provider，请先从 SDK 内置 provider 集成点开始。在很多设置中，无需添加 LiteLLM 就足够了。每种模式的示例位于 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
+如果你需要非 OpenAI provider，请先使用 SDK 的内置 provider 集成点。在许多设置中，这已经足够，无需增加第三方适配器。每种模式的示例见 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
### 非 OpenAI provider 集成方式
| 方式 | 适用场景 | 范围 |
| --- | --- | --- |
-| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应作为大多数或全部智能体的默认值 | 全局默认 |
-| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义 provider 应用于单次 run | 每次 run |
+| [`set_default_openai_client`][agents.set_default_openai_client] | 一个 OpenAI 兼容端点应作为大多数或所有智能体的默认值 | 全局默认 |
+| [`ModelProvider`][agents.models.interface.ModelProvider] | 一个自定义 provider 应用于单次运行 | 每次运行 |
| [`Agent.model`][agents.agent.Agent.model] | 不同智能体需要不同 provider 或具体模型对象 | 每个智能体 |
-| LiteLLM（beta） | 你需要 LiteLLM 特有的 provider 覆盖或路由 | 见 [LiteLLM](#litellm) |
+| 第三方适配器 | 你需要内置路径未提供的适配器管理 provider 覆盖或路由 | 见[第三方适配器](#third-party-adapters) |
-你可以通过这些内置路径集成其他 LLM provider：
+你可以通过这些内置路径集成其他 LLM providers：
-1. 在你希望全局使用 `AsyncOpenAI` 实例作为 LLM 客户端时，[`set_default_openai_client`][agents.set_default_openai_client] 很有用。这适用于 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` 层级。这让你可以指定“本次 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 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 实例上指定模型。这使你可以为不同智能体混合搭配不同 providers。可配置示例见 [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)。
!!! note
- 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM provider 仍不支持 Responses API。如果你的 LLM provider 支持，我们建议使用 Responses。
+ 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM providers 仍不支持 Responses API。如果你的 LLM provider 支持，我们建议使用 Responses。
-## 在单个工作流中混用模型
+## 在单个工作流中混合模型
-在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以为分流使用更小、更快的模型，同时为复杂任务使用更大、能力更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式选择特定模型：
+在单个工作流内，你可能希望每个智能体使用不同模型。例如，你可以在分流阶段使用更小、更快的模型，在复杂任务中使用更大、更强的模型。配置 [`Agent`][agents.Agent] 时，你可以通过以下方式选择特定模型：
1. 传入模型名称。
-2. 传入任意模型名称 + 一个可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。
-3. 直接提供 [`Model`][agents.models.interface.Model] 实现。
+2. 传入任意模型名 + 一个可将该名称映射为 Model 实例的 [`ModelProvider`][agents.models.interface.ModelProvider]。
+3. 直接提供一个 [`Model`][agents.models.interface.Model] 实现。
!!! note
@@ -251,9 +251,9 @@ async def main():
```
1. 直接设置 OpenAI 模型名称。
-2. 提供 [`Model`][agents.models.interface.Model] 实现。
+2. 提供一个 [`Model`][agents.models.interface.Model] 实现。
-当你希望进一步配置某个智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供诸如 temperature 等可选模型配置参数。
+当你希望进一步配置智能体所用模型时，可传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供如 temperature 等可选模型配置参数。
```python
from agents import Agent, ModelSettings
@@ -268,19 +268,19 @@ english_agent = Agent(
## 高级 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`：控制是否将生成的响应存储在服务端以便后续检索。这会影响依赖 response ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程。
-- `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)。
+- `truncation`：设为 `"auto"` 可让 Responses API 在上下文将溢出时丢弃最旧会话项，而不是直接失败。
+- `store`：控制生成的响应是否存储在服务端供后续检索。这会影响依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程。
+- `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
@@ -299,13 +299,13 @@ research_agent = Agent(
)
```
-当你设置 `store=False` 时，Responses API 不会保留该响应供后续服务端检索。这对无状态或零数据保留风格流程很有用，但也意味着原本可复用 response 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 指南](../sessions/index.md#openai-responses-compaction-sessions)。
### 传递 `extra_args`
-当你需要 SDK 顶层尚未直接暴露的 provider 特定字段或较新的请求字段时，请使用 `extra_args`。
+当你需要 SDK 尚未直接在顶层暴露的 provider 特定字段或较新请求字段时，使用 `extra_args`。
-另外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（如 `user`、`service_tier` 等）。如果它们在顶层不可用，也可用 `extra_args` 传递。
+另外，当你使用 OpenAI 的 Responses API 时，[还有一些其他可选参数](https://platform.openai.com/docs/api-reference/responses/create)（例如 `user`、`service_tier` 等）。如果它们未在顶层提供，你也可以通过 `extra_args` 传递。
```python
from agents import Agent, ModelSettings
@@ -321,9 +321,9 @@ english_agent = Agent(
)
```
-## 由 Runner 管理的重试
+## Runner 管理的重试
-重试是仅运行时生效并需显式启用的功能。除非你设置 `ModelSettings(retry=...)` 且重试策略选择重试，否则 SDK 不会重试一般模型请求。
+重试是仅运行时生效且需显式启用的。除非你设置 `ModelSettings(retry=...)` 且重试策略选择重试，否则 SDK 不会重试普通模型请求。
```python
from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
@@ -357,79 +357,79 @@ agent = Agent(
| 字段 | 类型 | 说明 |
| --- | --- | --- |
-| `max_retries` | `int | None` | 初始请求之后允许的重试次数。 |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试但未返回显式延迟时的默认延迟策略。 |
-| `policy` | `RetryPolicy | None` | 决定是否重试的回调。该字段仅在运行时使用，不会被序列化。 |
+| `max_retries` | `int | None` | 初次请求之后允许的重试次数。 |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略选择重试但未返回显式延迟时使用的默认延迟策略。 |
+| `policy` | `RetryPolicy | None` | 决定是否重试的回调。此字段仅在运行时生效，不会被序列化。 |
-重试策略会接收一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含：
+重试策略会收到一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含：
-- `attempt` 和 `max_retries`，便于你基于尝试次数决策。
-- `stream`，用于在流式与非流式行为之间分支。
-- `error`，用于原始检查。
-- `normalized` 事实，例如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。
-- 当底层模型适配器可提供重试指引时的 `provider_advice`。
+- `attempt` 和 `max_retries`，便于做与尝试次数相关的决策。
+- `stream`，便于区分流式与非流式行为。
+- `error`，用于原始错误检查。
+- `normalized` 事实，如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。
+- 当底层模型适配器可提供重试建议时的 `provider_advice`。
策略可返回：
-- `True` / `False`，用于简单的重试决策。
+- `True` / `False`，用于简单重试决策。
- [`RetryDecision`][agents.retry.RetryDecision]，用于覆盖延迟或附加诊断原因。
-SDK 在 `retry_policies` 中导出了一组现成辅助函数：
+SDK 在 `retry_policies` 中导出了现成辅助函数：
| 辅助函数 | 行为 |
| --- | --- |
| `retry_policies.never()` | 始终不重试。 |
-| `retry_policies.provider_suggested()` | 若可用则遵循 provider 的重试建议。 |
-| `retry_policies.network_error()` | 匹配瞬时传输错误与超时失败。 |
-| `retry_policies.http_status([...])` | 匹配选定的 HTTP 状态码。 |
-| `retry_policies.retry_after()` | 仅当存在 retry-after 提示时重试，并使用该延迟。 |
-| `retry_policies.any(...)` | 任一嵌套策略选择重试即重试。 |
+| `retry_policies.provider_suggested()` | 在可用时遵循 provider 的重试建议。 |
+| `retry_policies.network_error()` | 匹配临时传输错误与超时失败。 |
+| `retry_policies.http_status([...])` | 匹配指定的 HTTP 状态码。 |
+| `retry_policies.retry_after()` | 仅在存在 retry-after 提示时重试，并使用该延迟。 |
+| `retry_policies.any(...)` | 任一嵌套策略选择重试时即重试。 |
| `retry_policies.all(...)` | 仅当所有嵌套策略都选择重试时才重试。 |
-组合策略时，`provider_suggested()` 是最安全的首个构件，因为当 provider 能区分时，它可保留 provider 的否决与重放安全批准。
+组合策略时，`provider_suggested()` 是最安全的首个构建块，因为当 provider 可区分时，它能保留 provider 否决与重放安全批准。
##### 安全边界
某些失败永远不会自动重试：
- Abort 错误。
-- provider 建议标记重放不安全的请求。
-- 流式 run 中输出已开始且重放会不安全的情况。
+- provider 建议将重放标记为不安全的请求。
+- 在输出已开始且重放会不安全的流式运行中发生的错误。
-使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会被更保守地处理。对于这些请求，仅使用 `network_error()` 或 `http_status([500])` 等非 provider 谓词本身并不足够。重试策略应包含来自 provider 的重放安全批准，通常通过 `retry_policies.provider_suggested()`。
+使用 `previous_response_id` 或 `conversation_id` 的有状态后续请求也会更保守处理。对这类请求，仅有 `network_error()` 或 `http_status([500])` 等非 provider 谓词还不够。重试策略应包含来自 provider 的重放安全批准，通常通过 `retry_policies.provider_suggested()`。
-##### Runner 与智能体合并行为
+##### Runner 与智能体的合并行为
-在 runner 级和智能体级 `ModelSettings` 之间，`retry` 会进行深度合并：
+`retry` 会在 runner 级和智能体级 `ModelSettings` 之间进行深度合并：
-- 智能体可仅覆盖 `retry.max_retries`，并继承 runner 的 `policy`。
-- 智能体可仅覆盖 `retry.backoff` 的一部分，并保留 runner 中同级的其他 backoff 字段。
-- `policy` 仅运行时有效，因此序列化后的 `ModelSettings` 会保留 `max_retries` 和 `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) 和 [`examples/basic/retry_litellm.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 provider 故障排查
+## 非 OpenAI providers 故障排查
### 追踪客户端错误 401
-如果你遇到与追踪相关的错误，是因为追踪数据会上传到 OpenAI 服务端，而你没有 OpenAI API key。你有三种解决方案：
+如果你遇到与追踪相关的错误，这是因为 trace 会上传到 OpenAI 服务端，而你没有 OpenAI API key。你有三种解决方式：
1. 完全禁用追踪：[`set_tracing_disabled(True)`][agents.set_tracing_disabled]。
-2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API key 仅用于上传追踪，且必须来自 [platform.openai.com](https://platform.openai.com/)。
-3. 使用非 OpenAI 的追踪进程。参见[追踪文档](../tracing.md#custom-tracing-processors)。
+2. 为追踪设置 OpenAI key：[`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。该 API key 仅用于上传 trace，且必须来自 [platform.openai.com](https://platform.openai.com/)。
+3. 使用非 OpenAI 的 trace 进程。见[追踪文档](../tracing.md#custom-tracing-processors)。
### Responses API 支持
-SDK 默认使用 Responses API，但许多其他 LLM provider 仍不支持它。因此你可能会看到 404 或类似问题。可通过以下两种方式解决：
+SDK 默认使用 Responses API，但许多其他 LLM providers 仍不支持它。因此你可能会看到 404 或类似问题。你有两种解决方式：
-1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。当你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 时，此方式可用。
+1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。这适用于你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 的情况。
2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
### structured outputs 支持
-某些模型 provider 不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误：
+一些模型 provider 不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致如下错误：
```
@@ -437,24 +437,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
-这是某些模型 provider 的不足——它们支持 JSON 输出，但不允许你指定用于输出的 `json_schema`。我们正在修复这一问题，但建议你依赖支持 JSON schema 输出的 provider，否则应用会经常因 JSON 格式错误而中断。
+这是一些模型 provider 的短板——它们支持 JSON 输出，但不允许你指定输出使用的 `json_schema`。我们正在修复此问题，但建议你依赖支持 JSON schema 输出的 provider，否则应用会经常因 JSON 格式错误而中断。
-## 跨 provider 混用模型
+## 跨 providers 混合模型
-你需要了解不同模型 provider 的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入、托管文件检索和网络检索，但许多其他 provider 不支持这些功能。请注意以下限制：
+你需要了解不同模型 provider 的功能差异，否则可能会遇到错误。例如，OpenAI 支持 structured outputs、多模态输入以及托管文件检索和网络检索，但许多其他 providers 不支持这些功能。请注意以下限制：
- 不要向不支持的 provider 发送其无法理解的 `tools`
-- 在调用仅文本模型前，先过滤掉多模态输入
-- 注意不支持 structured JSON 输出的 provider 偶尔会生成无效 JSON
+- 在调用纯文本模型前过滤掉多模态输入
+- 注意不支持结构化 JSON 输出的 providers 偶尔会产生无效 JSON。
-## LiteLLM
+## 第三方适配器
-对于需要将非 OpenAI provider 引入 Agents SDK 工作流的场景，LiteLLM 支持以尽力而为的 beta 形式提供。
+仅当 SDK 的内置 provider 集成点不足时再使用第三方适配器。如果你在此 SDK 中仅使用 OpenAI 模型，优先使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于你需要将 OpenAI 模型与非 OpenAI providers 组合使用，或需要内置路径未提供的适配器管理 provider 覆盖或路由的场景。适配器在 SDK 与上游模型 provider 之间增加了一层兼容层，因此功能支持和请求语义会因 provider 而异。SDK 当前将 Any-LLM 和 LiteLLM 作为尽力支持的 beta 适配器集成。
-如果你在此 SDK 中使用 OpenAI 模型，我们建议使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而非 LiteLLM。
+### Any-LLM
-如果你需要将 OpenAI 模型与非 OpenAI provider 组合使用，尤其是通过 Chat Completions 兼容 API，LiteLLM 可作为 beta 选项，但未必是每种设置下的最优选择。
+Any-LLM 支持以尽力支持的 beta 形式提供，适用于你需要 Any-LLM 管理的 provider 覆盖或路由的场景。
-如果你需要为非 OpenAI provider 使用 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]。
+根据上游 provider 路径，Any-LLM 可能使用 Responses API、兼容 Chat Completions 的 API，或 provider 特定兼容层。
-如果你希望 LiteLLM 响应填充 SDK 的用量指标，请传入 `ModelSettings(include_usage=True)`。
\ No newline at end of file
+如果你需要 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 依赖与能力缺口由 Any-LLM 上游定义，而非 SDK 定义。当上游 provider 返回使用量指标时会自动透传；但流式 Chat Completions 后端可能需要先设置 `ModelSettings(include_usage=True)` 才会输出使用量分片。若你依赖 structured outputs、工具调用、使用量上报或 Responses 特定行为，请验证你计划部署的具体 provider 后端。
+
+### LiteLLM
+
+LiteLLM 支持以尽力支持的 beta 形式提供，适用于你需要 LiteLLM 特定 provider 覆盖或路由的场景。
+
+如果你需要 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 支持的 providers 默认不会填充 SDK 使用量指标。如果你需要使用量上报，请传入 `ModelSettings(include_usage=True)`，并在依赖 structured outputs、工具调用、使用量上报或适配器特定路由行为时，验证你计划部署的具体 provider 后端。
\ No newline at end of file
diff --git a/docs/zh/models/litellm.md b/docs/zh/models/litellm.md
index 3352d3966e..3c32c8df8b 100644
--- a/docs/zh/models/litellm.md
+++ b/docs/zh/models/litellm.md
@@ -5,9 +5,9 @@ search:
# LiteLLM
-本页面已移动到[模型中的 LiteLLM 部分](index.md#litellm)。
+本页面已移动到[模型中的第三方适配器部分](index.md#third-party-adapters)。
如果未自动重定向，请使用上方链接。
\ No newline at end of file
diff --git a/docs/zh/tracing.md b/docs/zh/tracing.md
index ced155a3e5..6580b0f350 100644
--- a/docs/zh/tracing.md
+++ b/docs/zh/tracing.md
@@ -8,49 +8,49 @@ Agents SDK 内置了追踪功能，可在智能体运行期间收集完整的事
!!!note
- 默认启用追踪。你可以通过三种常见方式禁用它：
+ 默认启用追踪。你可以通过三种常见方式禁用：
- 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 下使用零数据保留（ZDR）策略的组织，追踪不可用。***
+***对于在 OpenAI API 上使用零数据保留（ZDR）策略运行的组织，追踪不可用。***
-## Trace 与 Span
+## Traces 与 spans
-- **Traces** 表示一个“工作流”的单次端到端操作。它们由 Spans 组成。Traces 具有以下属性：
- - `workflow_name`：逻辑工作流或应用名称。例如“代码生成”或“客户服务”。
- - `trace_id`：Trace 的唯一 ID。如果你不传入会自动生成。格式必须为 `trace_<32_alphanumeric>`。
+- **Traces** 表示“工作流”的一次端到端操作。它由 Span 组成。Trace 具有以下属性：
+ - `workflow_name`：逻辑工作流或应用。例如“代码生成”或“客户服务”。
+ - `trace_id`：Trace 的唯一 ID。如果你未传入则自动生成。格式必须为 `trace_<32_alphanumeric>`。
- `group_id`：可选分组 ID，用于关联同一会话中的多个 Trace。例如，你可以使用聊天线程 ID。
- `disabled`：若为 True，则不会记录该 Trace。
- `metadata`：Trace 的可选元数据。
- **Spans** 表示具有开始和结束时间的操作。Span 具有：
- `started_at` 和 `ended_at` 时间戳。
- - `trace_id`，表示它们所属的 Trace
- - `parent_id`，指向该 Span 的父 Span（如果有）
- - `span_data`，即关于 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息，等等。
+ - `trace_id`，表示其所属的 Trace
+ - `parent_id`，指向该 Span 的父 Span（若有）
+ - `span_data`，即 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息，等等。
## 默认追踪
默认情况下，SDK 会追踪以下内容：
-- 整个 `Runner.{run, run_sync, run_streamed}()` 会包裹在 `trace()` 中。
-- 每次智能体运行都会包裹在 `agent_span()` 中
-- LLM 生成会包裹在 `generation_span()` 中
-- 每次函数工具调用都会包裹在 `function_span()` 中
-- 安全防护措施会包裹在 `guardrail_span()` 中
-- 任务转移会包裹在 `handoff_span()` 中
-- 音频输入（语音转文本）会包裹在 `transcription_span()` 中
-- 音频输出（文本转语音）会包裹在 `speech_span()` 中
-- 相关音频 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()` 中
+- 相关音频 Span 可能作为 `speech_group_span()` 的子级
-默认情况下，Trace 名称为“Agent workflow”。如果你使用 `trace`，可以设置此名称；也可以通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。
+默认情况下，Trace 名称为“Agent workflow”。如果你使用 `trace`，可以设置该名称；也可以通过[`RunConfig`][agents.run.RunConfig]配置名称和其他属性。
-此外，你还可以设置[自定义追踪进程](#custom-tracing-processors)，将 Trace 推送到其他目标（作为替代或辅助目标）。
+此外，你还可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪发送到其他目标（作为替代目标或次要目标）。
-## 更高层级的 Trace
+## 更高层级的追踪
-有时，你可能希望多次对 `run()` 的调用都属于同一个 Trace。你可以通过将整段代码包裹在 `trace()` 中来实现。
+有时，你可能希望将多次 `run()` 调用纳入同一个 Trace。你可以通过将整段代码包裹在 `trace()` 中来实现。
```python
from agents import Agent, Runner, trace
@@ -65,60 +65,60 @@ async def main():
print(f"Rating: {second_result.final_output}")
```
-1. 因为两次对 `Runner.run` 的调用都包裹在 `with trace()` 中，所以这些单独运行会属于同一个总体 Trace，而不是创建两个 Trace。
+1. 因为这两次 `Runner.run` 调用被包裹在 `with trace()` 中，所以这些单独运行会成为整体 Trace 的一部分，而不是创建两个 Trace。
## 创建 Trace
-你可以使用 [`trace()`][agents.tracing.trace] 函数来创建 Trace。Trace 需要开始和结束。你有两种方式：
+你可以使用 [`trace()`][agents.tracing.trace] 函数创建 Trace。Trace 需要被启动和结束。你有两种方式：
-1. **推荐**：将 trace 用作上下文管理器，即 `with trace(...) as my_trace`。这会在正确的时间自动开始和结束 Trace。
+1. **推荐**：将 Trace 用作上下文管理器，即 `with trace(...) as my_trace`。这会在正确的时间自动启动和结束 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。
+当前 Trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。这意味着它可自动适配并发。如果你手动启动/结束 Trace，则需要向 `start()`/`finish()` 传递 `mark_as_current` 和 `reset_current` 来更新当前 Trace。
## 创建 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 下；这同样通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。
+Span 会自动归属于当前 Trace，并嵌套在最近的当前 Span 之下，后者通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。
## 敏感数据
某些 Span 可能会捕获潜在的敏感数据。
-`generation_span()` 会存储 LLM 生成的输入/输出，`function_span()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用此类数据的捕获。
+`generation_span()` 会存储 LLM 生成的输入/输出，`function_span()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用这类数据采集。
-类似地，默认情况下，音频 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]，负责创建 Trace。
-- 我们使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 配置 `TraceProvider`，它会将 Trace/Span 批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者会将 Span 和 Trace 批量导出到 OpenAI 后端。
+- 我们为 `TraceProvider` 配置一个 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，它会将 Trace/Span 批量发送给 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者再将 Span 和 Trace 批量导出到 OpenAI 后端。
-若要自定义此默认设置，将 Trace 发送到替代或附加后端，或修改导出器行为，你有两种选择：
+要自定义此默认设置，将追踪发送到替代或附加后端，或修改导出器行为，你有两个选项：
-1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外的**追踪进程，在 Trace 和 Span 就绪时接收它们。这使你可以在发送到 OpenAI 后端之外执行自己的处理。
-2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着除非你包含一个会执行该发送的 `TracingProcessor`，否则 Trace 不会发送到 OpenAI 后端。
+1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外**的追踪进程，它会在 Trace 和 Span 就绪时接收它们。这样你就可以在发送到 OpenAI 后端之外执行自己的处理。
+2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着除非你包含可执行该操作的 `TracingProcessor`，否则 Trace 不会发送到 OpenAI 后端。
-## 使用非 OpenAI 模型进行追踪
+## 对非 OpenAI 模型进行追踪
-你可以在非 OpenAI 模型中使用 OpenAI API key，在无需禁用追踪的情况下，于 OpenAI Traces 仪表板启用免费追踪。
+你可以将 OpenAI API key 与非 OpenAI 模型一起使用，从而在无需禁用追踪的情况下，在 OpenAI Traces 仪表板启用免费追踪。有关适配器选择和设置注意事项，请参阅 Models 指南中的[第三方适配器](models/index.md#third-party-adapters)部分。
```python
import os
from agents import set_tracing_export_api_key, Agent, Runner
-from agents.extensions.models.litellm_model import LitellmModel
+from agents.extensions.models.any_llm_model import AnyLLMModel
tracing_api_key = os.environ["OPENAI_API_KEY"]
set_tracing_export_api_key(tracing_api_key)
-model = LitellmModel(
- model="your-model-name",
+model = AnyLLMModel(
+ model="your-provider/your-model-name",
api_key="your-api-key",
)
@@ -141,12 +141,12 @@ await Runner.run(
```
## 附加说明
-- 在 Openai Traces 仪表板查看免费 Trace。
+- 在 Openai Traces 仪表板查看免费追踪。
## 生态系统集成
-以下社区和供应商集成支持 OpenAI Agents SDK 追踪接口。
+以下社区和供应商集成支持 OpenAI Agents SDK 的追踪接口。
### 外部追踪进程列表
diff --git a/docs/zh/usage.md b/docs/zh/usage.md
index b02d7097e0..743098f221 100644
--- a/docs/zh/usage.md
+++ b/docs/zh/usage.md
@@ -4,7 +4,7 @@ search:
---
# 用法
-Agents SDK 会自动追踪每次运行的 token 使用量。你可以从运行上下文中访问它，并用它来监控成本、实施限制或记录分析数据。
+Agents SDK 会自动追踪每次运行的 token 使用情况。你可以从运行上下文中访问这些数据，并用它来监控成本、执行限制或记录分析数据。
## 追踪内容
@@ -12,14 +12,14 @@ Agents SDK 会自动追踪每次运行的 token 使用量。你可以从运行
- **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,29 +31,20 @@ print("Output tokens:", usage.output_tokens)
print("Total tokens:", usage.total_tokens)
```
-使用量会聚合该次运行期间的所有模型调用（包括工具调用和任务转移）。
+使用量会汇总该次运行期间所有模型调用（包括工具调用和任务转移）。
-### 为 LiteLLM 模型启用使用量追踪
+### 在第三方适配器中启用使用情况追踪
-LiteLLM 提供方默认不会上报使用量指标。使用 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] 时，请向你的智能体传入 `ModelSettings(include_usage=True)`，以便 LiteLLM 响应填充 `result.context_wrapper.usage`。有关设置指南和示例，请参阅模型指南中的 [LiteLLM 说明](models/index.md#litellm)。
+不同第三方适配器和提供方后端的使用情况上报方式有所不同。如果你依赖由适配器支持的模型并且需要准确的 `result.context_wrapper.usage` 值：
-```python
-from agents import Agent, ModelSettings, Runner
-from agents.extensions.models.litellm_model import LitellmModel
-
-agent = Agent(
- name="Assistant",
- model=LitellmModel(model="your/model", api_key="..."),
- model_settings=ModelSettings(include_usage=True),
-)
+- 使用 `AnyLLMModel` 时，如果上游提供方返回了使用数据，则会自动透传。对于流式 Chat Completions 后端，在发出 usage 分块前，你可能需要设置 `ModelSettings(include_usage=True)`。
+- 使用 `LitellmModel` 时，某些提供方后端默认不会上报使用数据，因此通常需要 `ModelSettings(include_usage=True)`。
-result = await Runner.run(agent, "What's the weather in Tokyo?")
-print(result.context_wrapper.usage.total_tokens)
-```
+请查看 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?")
@@ -62,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")
@@ -76,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 中使用使用量
+## 在 hooks 中使用使用情况
-如果你正在使用 `RunHooks`，传递给每个 hook 的 `context` 对象都包含 `usage`。这使你可以在关键生命周期节点记录使用量。
+如果你使用 `RunHooks`，传递给每个 hook 的 `context` 对象都包含 `usage`。这使你可以在关键生命周期节点记录使用情况。
```python
class MyHooks(RunHooks):
@@ -91,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] - 接入使用量追踪生命周期 hooks
\ 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