` です。`run_context_thread_id_key` で上書きできます。
ランタイム設定:
-- 認証: `CODEX_API_KEY` (推奨) または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡します。
-- ランタイム: `codex_options.base_url` は CLI の base URL を上書きします。
-- バイナリ解決: CLI パスを固定するには `codex_options.codex_path_override` (または `CODEX_PATH`) を設定します。設定しない場合、 SDK は `PATH` から `codex` を解決し、その後バンドル済み vendor バイナリへフォールバックします。
-- 環境: `codex_options.env` はサブプロセス環境を完全に制御します。これを指定すると、サブプロセスは `os.environ` を継承しません。
-- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes` (または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`) は stdout / stderr リーダー制限を制御します。有効範囲は `65536` から `67108864`、デフォルトは `8388608` です。
-- ストリーミング: `on_stream` はスレッド / ターンのライフサイクルイベントとアイテムイベント (`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、`error` のアイテム更新) を受け取ります。
-- 出力: 結果には `response`、`usage`、`thread_id` が含まれます。usage は `RunContextWrapper.usage` に追加されます。
+- 認証: `CODEX_API_KEY`（推奨）または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡します。
+- ランタイム: `codex_options.base_url` は CLI ベース URL を上書きします。
+- バイナリ解決: CLI パスを固定するには `codex_options.codex_path_override`（または `CODEX_PATH`）を設定します。それ以外の場合、SDK は `PATH` から `codex` を解決し、その後バンドルされたベンダーバイナリへフォールバックします。
+- 環境: `codex_options.env` はサブプロセス環境を完全に制御します。指定された場合、サブプロセスは `os.environ` を継承しません。
+- ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes`（または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）は stdout/stderr リーダーの制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。
+- ストリーミング: `on_stream` はスレッド/ターンのライフサイクルイベントとアイテムイベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、および `error` アイテム更新）を受け取ります。
+- 出力: 実行結果には `response`、`usage`、`thread_id` が含まれます。usage は `RunContextWrapper.usage` に追加されます。
-参照:
+参考:
-- [Codex tool API reference](ref/extensions/experimental/codex/codex_tool.md)
-- [ThreadOptions reference](ref/extensions/experimental/codex/thread_options.md)
-- [TurnOptions reference](ref/extensions/experimental/codex/turn_options.md)
-- 完全に実行可能なサンプルは `examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。
\ No newline at end of file
+- [Codex ツール API リファレンス](ref/extensions/experimental/codex/codex_tool.md)
+- [ThreadOptions リファレンス](ref/extensions/experimental/codex/thread_options.md)
+- [TurnOptions リファレンス](ref/extensions/experimental/codex/turn_options.md)
+- 完全に実行可能なサンプルについては `examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。
\ No newline at end of file
diff --git a/docs/ja/voice/quickstart.md b/docs/ja/voice/quickstart.md
index 06b8ccf963..4e93673a60 100644
--- a/docs/ja/voice/quickstart.md
+++ b/docs/ja/voice/quickstart.md
@@ -6,7 +6,7 @@ search:
## 前提条件
-Agents SDK の基本的な [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。次に、 SDK からオプションの音声依存関係をインストールします。
+Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップ済みであることを確認してください。次に、SDK からオプションの音声依存関係をインストールします。
```bash
pip install 'openai-agents[voice]'
@@ -14,11 +14,11 @@ pip install 'openai-agents[voice]'
## 概念
-主に理解しておくべき概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] で、これは 3 ステップのプロセスです。
+知っておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。
-1. 音声認識モデルを実行して、音声をテキストに変換します。
-2. コード（通常はエージェントオーケストレーションのワークフロー）を実行して、結果を生成します。
-3. 音声合成モデルを実行して、結果のテキストを音声に戻します。
+1. 音声をテキストに変換するために speech-to-text モデルを実行します。
+2. 結果を生成するために、通常はエージェント型ワークフローであるあなたのコードを実行します。
+3. 結果テキストを音声に戻すために text-to-speech モデルを実行します。
```mermaid
graph LR
@@ -48,7 +48,7 @@ graph LR
## エージェント
-まず、いくつかの Agents をセットアップしましょう。この SDK でエージェントを構築したことがあれば、ここは馴染みのある内容です。複数の Agents と、ハンドオフ、ツールを用意します。
+まず、いくつかのエージェントを設定しましょう。この SDK でエージェントを構築したことがあれば、おなじみの内容です。いくつかのエージェント、ハンドオフ、ツールを用意します。
```python
import asyncio
@@ -76,7 +76,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -84,7 +84,7 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
@@ -92,14 +92,14 @@ agent = Agent(
## 音声パイプライン
-ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使い、シンプルな音声パイプラインをセットアップします。
+ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用して、シンプルな音声パイプラインを設定します。
```python
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
```
-## パイプライン実行
+## パイプラインの実行
```python
import numpy as np
@@ -124,7 +124,7 @@ async for event in result.stream():
```
-## 全体の統合
+## すべての統合
```python
import asyncio
@@ -160,7 +160,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -168,7 +168,7 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
@@ -195,4 +195,4 @@ if __name__ == "__main__":
asyncio.run(main())
```
-この example を実行すると、エージェントがあなたに話しかけます。[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の example では、自分でエージェントに話しかけられるデモを確認できます。
\ No newline at end of file
+この例を実行すると、エージェントがあなたに話しかけます！エージェントに自分で話しかけられるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。
\ No newline at end of file
diff --git a/docs/ko/agents.md b/docs/ko/agents.md
index c75ac43436..ebdedd84ef 100644
--- a/docs/ko/agents.md
+++ b/docs/ko/agents.md
@@ -4,49 +4,49 @@ search:
---
# 에이전트
-에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 handoffs, 가드레일, structured outputs 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다
+에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다.
-이 페이지는 단일 일반 `Agent`를 정의하거나 커스터마이즈하려는 경우에 사용합니다. 여러 에이전트가 어떻게 협업해야 하는지 결정하려면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 manifest로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 내부에서 실행되어야 한다면 [Sandbox agent concepts](sandbox/guide.md)를 읽어보세요
+단일 일반 `Agent`를 정의하거나 사용자 지정하려는 경우 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 매니페스트로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 안에서 실행되어야 한다면 [샌드박스 에이전트 개념](sandbox/guide.md)을 읽어보세요.
-SDK는 OpenAI 모델에 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다: `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 제어하고 싶다면 Responses API를 직접 사용하세요
+SDK는 OpenAI 모델에 대해 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다. `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 제어하려면 대신 Responses API를 직접 사용하세요.
## 다음 가이드 선택
-이 페이지를 에이전트 정의의 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요
+이 페이지를 에이전트 정의를 위한 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요.
-| 다음을 원한다면... | 다음 읽기 |
+| 원하는 작업 | 다음 읽을 문서 |
| --- | --- |
-| 모델 또는 provider 설정 선택 | [모델](models/index.md) |
+| 모델 또는 프로바이더 설정 선택 | [모델](models/index.md) |
| 에이전트에 기능 추가 | [도구](tools.md) |
-| 실제 repo, 문서 번들 또는 격리된 워크스페이스에 대해 에이전트 실행 | [Sandbox agents quickstart](sandbox_agents.md) |
-| 관리자 스타일 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) |
+| 실제 리포지토리, 문서 번들 또는 격리된 워크스페이스에 대해 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) |
+| 매니저 방식 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) |
| 핸드오프 동작 구성 | [핸드오프](handoffs.md) |
-| 턴 실행, 이벤트 스트리밍, 대화 상태 관리 | [에이전트 실행](running_agents.md) |
-| 최종 출력, 실행 항목, 재개 가능한 상태 점검 | [결과](results.md) |
-| 로컬 의존성 및 런타임 상태 공유 | [컨텍스트 관리](context.md) |
+| 턴 실행, 이벤트 스트리밍 또는 대화 상태 관리 | [에이전트 실행](running_agents.md) |
+| 최종 출력, 실행 항목 또는 재개 가능한 상태 검사 | [결과](results.md) |
+| 로컬 종속성 및 런타임 상태 공유 | [컨텍스트 관리](context.md) |
## 기본 구성
-에이전트의 가장 일반적인 속성은 다음과 같습니다
+에이전트의 가장 일반적인 속성은 다음과 같습니다.
-| 속성 | 필수 | 설명 |
+| 속성 | 필수 여부 | 설명 |
| --- | --- | --- |
-| `name` | 예 | 사람이 읽기 쉬운 에이전트 이름 |
-| `instructions` | 예 | 시스템 프롬프트 또는 동적 instructions 콜백. [동적 instructions](#dynamic-instructions) 참고 |
-| `prompt` | 아니요 | OpenAI Responses API 프롬프트 구성. 정적 프롬프트 객체 또는 함수를 허용합니다. [프롬프트 템플릿](#prompt-templates) 참고 |
-| `handoff_description` | 아니요 | 이 에이전트가 핸드오프 대상으로 제공될 때 노출되는 짧은 설명 |
-| `handoffs` | 아니요 | 대화를 전문 에이전트에 위임합니다. [handoffs](handoffs.md) 참고 |
-| `model` | 아니요 | 사용할 LLM. [모델](models/index.md) 참고 |
-| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice` 같은 모델 튜닝 매개변수 |
-| `tools` | 아니요 | 에이전트가 호출할 수 있는 도구. [도구](tools.md) 참고 |
-| `mcp_servers` | 아니요 | 에이전트를 위한 MCP 기반 도구. [MCP 가이드](mcp.md) 참고 |
-| `mcp_config` | 아니요 | strict schema conversion, MCP failure formatting 등 MCP 도구 준비 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration) 참고 |
-| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 사용자 입력에서 실행되는 가드레일. [가드레일](guardrails.md) 참고 |
-| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에서 실행되는 가드레일. [가드레일](guardrails.md) 참고 |
-| `output_type` | 아니요 | 일반 텍스트 대신 structured output 타입. [출력 타입](#output-types) 참고 |
-| `hooks` | 아니요 | 에이전트 범위의 lifecycle 콜백. [라이프사이클 이벤트(hooks)](#lifecycle-events-hooks) 참고 |
-| `tool_use_behavior` | 아니요 | 도구 결과를 모델로 다시 보낼지 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior) 참고 |
-| `reset_tool_choice` | 아니요 | 도구 호출 후 `tool_choice`를 재설정(기본값: `True`)하여 도구 사용 루프를 방지합니다. [도구 사용 강제](#forcing-tool-use) 참고 |
+| `name` | 예 | 사람이 읽을 수 있는 에이전트 이름입니다. |
+| `instructions` | 예 | 시스템 프롬프트 또는 동적 instructions 콜백입니다. [동적 instructions](#dynamic-instructions)를 참조하세요. |
+| `prompt` | 아니요 | OpenAI Responses API 프롬프트 구성입니다. 정적 프롬프트 객체 또는 함수를 허용합니다. [프롬프트 템플릿](#prompt-templates)을 참조하세요. |
+| `handoff_description` | 아니요 | 이 에이전트가 핸드오프 대상으로 제공될 때 노출되는 짧은 설명입니다. |
+| `handoffs` | 아니요 | 대화를 전문 에이전트에 위임합니다. [핸드오프](handoffs.md)를 참조하세요. |
+| `model` | 아니요 | 사용할 LLM입니다. [모델](models/index.md)을 참조하세요. |
+| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice` 같은 모델 튜닝 매개변수입니다. |
+| `tools` | 아니요 | 에이전트가 호출할 수 있는 도구입니다. [도구](tools.md)를 참조하세요. |
+| `mcp_servers` | 아니요 | 에이전트를 위한 MCP 기반 도구입니다. [MCP 가이드](mcp.md)를 참조하세요. |
+| `mcp_config` | 아니요 | 엄격한 스키마 변환 및 MCP 실패 형식화와 같이 MCP 도구가 준비되는 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration)를 참조하세요. |
+| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 사용자 입력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
+| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
+| `output_type` | 아니요 | 일반 텍스트 대신 structured outputs 타입입니다. [출력 타입](#output-types)을 참조하세요. |
+| `hooks` | 아니요 | 에이전트 범위의 라이프사이클 콜백입니다. [라이프사이클 이벤트(훅)](#lifecycle-events-hooks)을 참조하세요. |
+| `tool_use_behavior` | 아니요 | 도구 결과가 모델로 다시 전달될지, 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior)을 참조하세요. |
+| `reset_tool_choice` | 아니요 | 도구 사용 루프를 피하기 위해 도구 호출 후 `tool_choice`를 재설정합니다(기본값: `True`). [도구 사용 강제](#forcing-tool-use)를 참조하세요. |
```python
from agents import Agent, ModelSettings, function_tool
@@ -64,23 +64,23 @@ agent = Agent(
)
```
-이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 같은 개념을 기반으로 하고, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [Sandbox agent concepts](sandbox/guide.md) 참고
+이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 동일한 아이디어를 기반으로 하며, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [샌드박스 에이전트 개념](sandbox/guide.md)을 참조하세요.
## 프롬프트 템플릿
-`prompt`를 설정하여 OpenAI 플랫폼에서 생성한 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 동작합니다
+`prompt`를 설정하여 OpenAI 플랫폼에서 생성한 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 작동합니다.
-사용 방법은 다음과 같습니다:
+사용하려면 다음을 수행하세요.
1. https://platform.openai.com/playground/prompts 로 이동합니다
-2. 새 프롬프트 변수 `poem_style`를 생성합니다
-3. 다음 내용으로 시스템 프롬프트를 생성합니다:
+2. 새 프롬프트 변수 `poem_style`을 만듭니다.
+3. 다음 내용으로 시스템 프롬프트를 만듭니다.
```
Write a poem in {{poem_style}}
```
-4. `--prompt-id` 플래그로 예제를 실행합니다
+4. `--prompt-id` 플래그로 예제를 실행합니다.
```python
from agents import Agent
@@ -95,7 +95,7 @@ agent = Agent(
)
```
-실행 시점에 프롬프트를 동적으로 생성할 수도 있습니다:
+런타임에 프롬프트를 동적으로 생성할 수도 있습니다.
```python
from dataclasses import dataclass
@@ -127,9 +127,9 @@ result = await Runner.run(
## 컨텍스트
-에이전트는 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다: 사용자가 생성해 `Runner.run()`에 전달하는 객체로, 모든 에이전트, 도구, 핸드오프 등에 전달되며 에이전트 실행에 필요한 의존성과 상태를 담는 바구니 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다
+에이전트는 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다. 사용자가 생성하여 `Runner.run()`에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되고, 에이전트 실행을 위한 의존성과 상태를 담는 모음 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다.
-전체 `RunContextWrapper` 표면, 공유 사용량 추적, 중첩 `tool_input`, 직렬화 관련 주의사항은 [컨텍스트 가이드](context.md)를 읽어보세요
+전체 `RunContextWrapper` 표면, 공유 사용량 추적, 중첩된 `tool_input`, 직렬화 시 주의 사항은 [컨텍스트 가이드](context.md)를 읽어보세요.
```python
@dataclass
@@ -148,7 +148,7 @@ agent = Agent[UserContext](
## 출력 타입
-기본적으로 에이전트는 일반 텍스트(즉 `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하게 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택지는 [Pydantic](https://docs.pydantic.dev/) 객체지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 래핑할 수 있는 타입이라면 모두 지원합니다 - dataclasses, lists, TypedDict 등
+기본적으로 에이전트는 일반 텍스트(즉 `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 래핑할 수 있는 모든 타입을 지원합니다. dataclasses, lists, TypedDict 등이 포함됩니다.
```python
from pydantic import BaseModel
@@ -169,20 +169,20 @@ agent = Agent(
!!! note
- `output_type`를 전달하면, 모델은 일반 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용합니다
+ `output_type`을 전달하면, 이는 모델에 일반 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하라고 지시합니다.
## 멀티 에이전트 시스템 설계 패턴
-멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 널리 적용 가능한 두 가지 패턴이 자주 사용됩니다:
+멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 폭넓게 적용 가능한 두 가지 패턴을 자주 볼 수 있습니다.
-1. 매니저(Agents as tools): 중앙 매니저/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화 제어를 유지합니다
-2. 핸드오프: 동등한 에이전트가 대화를 인계받아 처리할 전문 에이전트로 제어를 넘깁니다. 이는 분산형 패턴입니다
+1. 매니저(Agents as tools): 중앙 매니저/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화 제어를 유지합니다.
+2. 핸드오프: 동등한 에이전트가 대화 제어를 이를 이어받는 전문 에이전트에게 넘깁니다. 이는 분산형 방식입니다.
-자세한 내용은 [our practical guide to building agents](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)를 참고하세요
+자세한 내용은 [에이전트 구축을 위한 실용 가이드](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)를 참조하세요.
### 매니저(Agents as tools)
-`customer_facing_agent`는 모든 사용자 상호작용을 처리하고, 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [tools](tools.md#agents-as-tools) 문서를 참고하세요
+`customer_facing_agent`는 모든 사용자 상호작용을 처리하고, 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 읽어보세요.
```python
from agents import Agent
@@ -211,7 +211,7 @@ customer_facing_agent = Agent(
### 핸드오프
-핸드오프는 에이전트가 위임할 수 있는 하위 에이전트입니다. 핸드오프가 발생하면 위임된 에이전트가 대화 기록을 전달받아 대화를 이어받습니다. 이 패턴은 단일 작업에 뛰어난 모듈형 전문 에이전트를 가능하게 합니다. 자세한 내용은 [handoffs](handoffs.md) 문서를 참고하세요
+핸드오프는 에이전트가 위임할 수 있는 하위 에이전트입니다. 핸드오프가 발생하면 위임된 에이전트가 대화 기록을 받고 대화를 이어받습니다. 이 패턴은 단일 작업에 뛰어난 모듈식 전문 에이전트를 가능하게 합니다. 자세한 내용은 [핸드오프](handoffs.md) 문서를 읽어보세요.
```python
from agents import Agent
@@ -232,7 +232,7 @@ triage_agent = Agent(
## 동적 instructions
-대부분의 경우 에이전트를 생성할 때 instructions를 제공하면 됩니다. 하지만 함수를 통해 동적 instructions를 제공할 수도 있습니다. 함수는 에이전트와 컨텍스트를 전달받고 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수 모두 허용됩니다
+대부분의 경우 에이전트를 만들 때 instructions를 제공할 수 있습니다. 그러나 함수를 통해 동적 instructions를 제공할 수도 있습니다. 함수는 에이전트와 컨텍스트를 받으며 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수가 모두 허용됩니다.
```python
def dynamic_instructions(
@@ -247,29 +247,29 @@ agent = Agent[UserContext](
)
```
-## 라이프사이클 이벤트(hooks)
+## 라이프사이클 이벤트(훅)
-때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어 이벤트를 로깅하거나, 데이터를 사전 로드하거나, 특정 이벤트 발생 시 사용량을 기록할 수 있습니다
+때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어 특정 이벤트가 발생할 때 이벤트를 로깅하거나, 데이터를 미리 가져오거나, 사용량을 기록할 수 있습니다.
-hook 범위는 두 가지입니다:
+두 가지 훅 범위가 있습니다.
-- [`RunHooks`][agents.lifecycle.RunHooks]는 다른 에이전트로의 핸드오프를 포함해 전체 `Runner.run(...)` 호출을 관찰합니다
-- [`AgentHooks`][agents.lifecycle.AgentHooks]는 `agent.hooks`를 통해 특정 에이전트 인스턴스에 연결됩니다
+- [`RunHooks`][agents.lifecycle.RunHooks]는 다른 에이전트로의 핸드오프를 포함하여 전체 `Runner.run(...)` 호출을 관찰합니다.
+- [`AgentHooks`][agents.lifecycle.AgentHooks]는 `agent.hooks`를 통해 특정 에이전트 인스턴스에 연결됩니다.
-이벤트에 따라 콜백 컨텍스트도 달라집니다:
+콜백 컨텍스트도 이벤트에 따라 달라집니다.
-- 에이전트 시작/종료 hook은 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받으며, 이는 원래 컨텍스트를 래핑하고 공유 실행 사용량 상태를 포함합니다
-- LLM, 도구, 핸드오프 hook은 [`RunContextWrapper`][agents.run_context.RunContextWrapper]를 받습니다
+- 에이전트 시작/종료 훅은 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받으며, 이는 원래 컨텍스트를 래핑하고 공유 실행 사용량 상태를 포함합니다.
+- LLM, 도구, 핸드오프 훅은 [`RunContextWrapper`][agents.run_context.RunContextWrapper]를 받습니다.
-일반적인 hook 타이밍:
+일반적인 훅 타이밍은 다음과 같습니다.
-- `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 끝낼 때
-- `on_llm_start` / `on_llm_end`: 각 모델 호출 직전/직후
-- `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출 전후
- 함수 도구의 경우 hook `context`는 보통 `ToolContext`이므로 `tool_call_id` 같은 도구 호출 메타데이터를 확인할 수 있습니다
-- `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때
+- `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 완료할 때입니다.
+- `on_llm_start` / `on_llm_end`: 각 모델 호출의 바로 전후입니다.
+- `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출의 전후입니다.
+ 함수 도구의 경우 훅 `context`는 일반적으로 `ToolContext`이므로 `tool_call_id` 같은 도구 호출 메타데이터를 검사할 수 있습니다.
+- `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때입니다.
-전체 워크플로에 대해 단일 관찰자가 필요하면 `RunHooks`를, 하나의 에이전트에 맞춤 부수 효과가 필요하면 `AgentHooks`를 사용하세요
+전체 워크플로를 위한 단일 관찰자가 필요하면 `RunHooks`를 사용하고, 한 에이전트에 사용자 지정 부수 효과가 필요하면 `AgentHooks`를 사용하세요.
```python
from agents import Agent, RunHooks, Runner
@@ -291,21 +291,21 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
print(result.final_output)
```
-전체 콜백 표면은 [Lifecycle API reference](ref/lifecycle.md)를 참고하세요
+전체 콜백 표면은 [라이프사이클 API 참조](ref/lifecycle.md)를 참조하세요.
## 가드레일
-가드레일을 사용하면 에이전트 실행과 병렬로 사용자 입력에 대한 검사/검증을 수행하고, 에이전트 출력이 생성된 뒤 해당 출력에 대해서도 검사/검증을 수행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 점검할 수 있습니다. 자세한 내용은 [guardrails](guardrails.md) 문서를 참고하세요
+가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대해 병렬로 검사/검증을 실행하고, 에이전트 출력이 생성된 후 그 출력에 대해서도 검사/검증을 실행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 검사할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 읽어보세요.
## 에이전트 복제/복사
-에이전트에서 `clone()` 메서드를 사용하면 Agent를 복제하고, 원하면 어떤 속성이든 변경할 수 있습니다
+에이전트의 `clone()` 메서드를 사용하면 Agent를 복제하고, 원하는 속성을 선택적으로 변경할 수 있습니다.
```python
pirate_agent = Agent(
name="Pirate",
instructions="Write like a pirate",
- model="gpt-5.4",
+ model="gpt-5.5",
)
robot_agent = pirate_agent.clone(
@@ -316,14 +316,14 @@ robot_agent = pirate_agent.clone(
## 도구 사용 강제
-도구 목록을 제공한다고 해서 항상 LLM이 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정해 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다:
+도구 목록을 제공한다고 해서 LLM이 항상 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다.
-1. `auto`: LLM이 도구 사용 여부를 결정하도록 허용
-2. `required`: LLM이 도구를 반드시 사용(단, 어떤 도구를 쓸지는 지능적으로 결정 가능)
-3. `none`: LLM이 도구를 _사용하지 않도록_ 강제
-4. 특정 문자열(예: `my_tool`) 설정: LLM이 해당 특정 도구를 사용하도록 강제
+1. `auto`: LLM이 도구 사용 여부를 결정할 수 있게 합니다.
+2. `required`: LLM이 도구를 사용해야 합니다(하지만 어떤 도구를 사용할지는 지능적으로 결정할 수 있습니다).
+3. `none`: LLM이 도구를 _사용하지 않도록_ 요구합니다.
+4. 특정 문자열(예: `my_tool`)을 설정하면 LLM이 해당 특정 도구를 사용해야 합니다.
-OpenAI Responses 도구 검색을 사용할 때는 이름 기반 도구 선택이 더 제한됩니다: `tool_choice`로는 네임스페이스 이름만 있는 도구나 deferred-only 도구를 지정할 수 없고, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 하지 않습니다. 이런 경우 `auto` 또는 `required`를 권장합니다. Responses 전용 제약 사항은 [Hosted tool search](tools.md#hosted-tool-search)를 참고하세요
+OpenAI Responses 도구 검색을 사용하는 경우 명명된 도구 선택은 더 제한됩니다. `tool_choice`로 단순 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없으며, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 지정하지 않습니다. 이러한 경우에는 `auto` 또는 `required`를 선호하세요. Responses 관련 제약 조건은 [호스티드 도구 검색](tools.md#hosted-tool-search)을 참조하세요.
```python
from agents import Agent, Runner, function_tool, ModelSettings
@@ -343,10 +343,10 @@ agent = Agent(
## 도구 사용 동작
-`Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력 처리 방식을 제어합니다:
+`Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력이 처리되는 방식을 제어합니다.
-- `"run_llm_again"`: 기본값입니다. 도구를 실행하고 LLM이 결과를 처리해 최종 응답을 생성합니다
-- `"stop_on_first_tool"`: 추가 LLM 처리 없이 첫 번째 도구 호출의 출력을 최종 응답으로 사용합니다
+- `"run_llm_again"`: 기본값입니다. 도구가 실행되고, LLM이 결과를 처리하여 최종 응답을 생성합니다.
+- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력이 추가 LLM 처리 없이 최종 응답으로 사용됩니다.
```python
from agents import Agent, Runner, function_tool, ModelSettings
@@ -364,7 +364,7 @@ agent = Agent(
)
```
-- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고 해당 출력을 최종 응답으로 사용합니다
+- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고, 그 출력을 최종 응답으로 사용합니다.
```python
from agents import Agent, Runner, function_tool
@@ -388,7 +388,7 @@ agent = Agent(
)
```
-- `ToolsToFinalOutputFunction`: 도구 결과를 처리하고 LLM으로 계속할지 중지할지 결정하는 사용자 정의 함수입니다
+- `ToolsToFinalOutputFunction`: 도구 결과를 처리하고 LLM으로 중지할지 계속할지 결정하는 사용자 지정 함수입니다.
```python
from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -426,4 +426,4 @@ agent = Agent(
!!! note
- 무한 루프를 방지하기 위해 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]로 구성할 수 있습니다. 무한 루프가 생기는 이유는 도구 결과가 LLM으로 전달되고, LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 과정이 무한 반복되기 때문입니다
\ No newline at end of file
+ 무한 루프를 방지하기 위해, 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]를 통해 구성할 수 있습니다. 무한 루프가 발생하는 이유는 도구 결과가 LLM으로 전송되고, 그러면 LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 일이 무한히 반복되기 때문입니다.
\ No newline at end of file
diff --git a/docs/ko/models/index.md b/docs/ko/models/index.md
index e9d94db341..b342f73cf7 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) |
+| OpenAI 모델만 사용 | Responses 모델 경로와 함께 기본 OpenAI provider 사용 | [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) |
+| 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가 아닌 또는 혼합 provider 라우팅에 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 출시할 provider 경로 검증 | [서드파티 어댑터](#third-party-adapters) |
+| OpenAI 외 또는 혼합 provider 라우팅에 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 출시하려는 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)입니다. 접근 권한이 있다면, 명시적인 `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.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하는 것을 권장합니다.
-[`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 다른 모델로 전환하려면 에이전트를 구성하는 방법이 두 가지 있습니다
+[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법이 두 가지 있습니다.
### 기본 모델
-첫째, 사용자 지정 모델을 설정하지 않은 모든 에이전트에서 특정 모델을 일관되게 사용하려면, 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요
+먼저, 사용자 지정 모델을 설정하지 않은 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
```bash
-export OPENAI_DEFAULT_MODEL=gpt-5.4
+export OPENAI_DEFAULT_MODEL=gpt-5.5
python3 my_awesome_agent.py
```
-둘째, `RunConfig`를 통해 실행(run) 단위 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다
+둘째, `RunConfig`를 통해 실행의 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 실행의 모델이 사용됩니다.
```python
from agents import Agent, RunConfig, Runner
@@ -52,13 +52,13 @@ agent = Agent(
result = await Runner.run(
agent,
"Hello",
- run_config=RunConfig(model="gpt-5.4"),
+ run_config=RunConfig(model="gpt-5.5"),
)
```
#### GPT-5 모델
-이 방식으로 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 같은 GPT-5 모델을 사용할 때 SDK는 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에서 가장 잘 동작하는 설정이 적용됩니다. 기본 모델의 reasoning effort를 조정하려면 사용자 지정 `ModelSettings`를 전달하세요:
+이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 GPT-5 모델을 사용하면 SDK는 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 값들이 설정됩니다. 기본 모델의 reasoning effort를 조정하려면 자체 `ModelSettings`를 전달하세요.
```python
from openai.types.shared import Reasoning
@@ -67,42 +67,42 @@ from agents import Agent, ModelSettings
my_agent = Agent(
name="My Agent",
instructions="You're a helpful agent.",
- # If OPENAI_DEFAULT_MODEL=gpt-5.4 is set, passing only model_settings works.
+ # If OPENAI_DEFAULT_MODEL=gpt-5.5 is set, passing only model_settings works.
# It's also fine to pass a GPT-5 model name explicitly:
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(reasoning=Reasoning(effort="high"), verbosity="low")
)
```
-더 낮은 지연 시간을 위해 `gpt-5.4`에서 `reasoning.effort="none"` 사용을 권장합니다. gpt-4.1 계열( mini 및 nano 변형 포함)도 인터랙티브 에이전트 앱 구축에 여전히 좋은 선택입니다
+더 낮은 지연 시간을 위해서는 `gpt-5.5`와 함께 `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가 전송하는 computer-tool 페이로드를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 기본 제공 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` 페이로드를 유지합니다.
-주요 예외는 프롬프트 관리 호출입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하면, SDK는 프롬프트가 어떤 모델을 고정했는지 추측하지 않기 위해 preview 호환 컴퓨터 페이로드를 기본으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.4"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요
+프롬프트 관리 호출이 주된 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않도록 preview 호환 computer 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요.
-[`ComputerTool`][agents.tool.ComputerTool]이 등록된 상태에서는 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 유효 요청 모델에 맞는 내장 선택기로 정규화됩니다. `ComputerTool`이 등록되지 않은 경우에는 이러한 문자열이 일반 함수 이름처럼 계속 동작합니다
+등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효한 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. 등록된 `ComputerTool`이 없으면 이러한 문자열은 일반 함수 이름처럼 계속 동작합니다.
-preview 호환 요청은 `environment`와 디스플레이 크기를 사전에 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청 전 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 사항은 [Tools](../tools.md#computertool-and-the-responses-computer-tool)를 참고하세요
+Preview 호환 요청은 `environment`와 표시 크기를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩터리를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참고하세요.
-#### GPT-5가 아닌 모델
+#### GPT-5 외 모델
-사용자 지정 `model_settings` 없이 GPT-5가 아닌 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다
+사용자 지정 `model_settings` 없이 GPT-5가 아닌 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다.
### Responses 전용 도구 검색 기능
-다음 도구 기능은 OpenAI Responses 모델에서만 지원됩니다:
+다음 도구 기능은 OpenAI Responses 모델에서만 지원됩니다.
- [`ToolSearchTool`][agents.tool.ToolSearchTool]
- [`tool_namespace()`][agents.tool.tool_namespace]
- `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면
-이 기능들은 Chat Completions 모델과 non-Responses 백엔드에서는 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 네임스페이스 이름이나 지연 전용 함수 이름을 강제하는 대신 모델이 `auto` 또는 `required` tool choice를 통해 도구를 로드하도록 하세요. 설정 세부 사항과 현재 제약은 [Tools](../tools.md#hosted-tool-search)를 참고하세요
+이러한 기능은 Chat Completions 모델 및 Responses가 아닌 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 모델이 bare namespace 이름이나 지연 전용 함수 이름을 강제하는 대신 `auto` 또는 `required` 도구 선택을 통해 도구를 로드하게 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../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.5"` 같은 문자열 모델 이름 포함)에 영향을 줍니다.
-전송 방식 선택은 SDK가 모델 이름을 모델 인스턴스로 해석할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 전송 방식은 이미 고정됩니다: [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions를 유지합니다. `RunConfig(model_provider=...)`를 전달하면 전역 기본값 대신 해당 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 또는 실행 수준 설정
-websocket 전송은 provider별 또는 실행(run)별로도 설정할 수 있습니다:
+provider별 또는 실행별로 websocket 전송을 구성할 수도 있습니다.
```python
from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -137,7 +137,7 @@ result = await Runner.run(
)
```
-OpenAI 기반 provider는 선택적 에이전트 등록 설정도 허용합니다. 이는 OpenAI 설정이 harness ID 같은 provider 수준 등록 메타데이터를 기대하는 경우를 위한 고급 옵션입니다
+OpenAI 기반 provider는 선택적 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정에서 harness ID와 같은 provider 수준 등록 메타데이터가 필요한 경우를 위한 고급 옵션입니다.
```python
from agents import (
@@ -163,14 +163,14 @@ result = await Runner.run(
#### `MultiProvider`를 사용한 고급 라우팅
-접두사 기반 모델 라우팅(예: 한 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합)이 필요하면 [`MultiProvider`][agents.MultiProvider]를 사용하고 거기서 `openai_use_responses_websocket=True`를 설정하세요
+접두사 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 그곳에서 `openai_use_responses_websocket=True`를 설정하세요.
-`MultiProvider`는 두 가지 기존 기본값을 유지합니다:
+`MultiProvider`는 두 가지 기존 기본값을 유지합니다.
-- `openai/...`는 OpenAI provider의 별칭으로 처리되어, `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다
-- 알 수 없는 접두사는 통과되지 않고 `UserError`를 발생시킵니다
+- `openai/...`는 OpenAI provider의 별칭으로 취급되므로, `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다.
+- 알 수 없는 접두사는 그대로 전달되지 않고 `UserError`를 발생시킵니다.
-OpenAI provider를 문자 그대로의 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트에 연결하는 경우, 명시적으로 pass-through 동작을 활성화하세요. websocket 활성 설정에서도 `MultiProvider`에 `openai_use_responses_websocket=True`를 유지하세요:
+OpenAI provider가 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키는 경우, pass-through 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요.
```python
from agents import Agent, MultiProvider, RunConfig, Runner
@@ -196,38 +196,38 @@ result = await Runner.run(
)
```
-백엔드가 문자 그대로 `openai/...` 문자열을 기대하면 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대하면 `unknown_prefix_mode="model_id"`를 사용하세요. 이 옵션들은 websocket 전송 외부의 `MultiProvider`에서도 동작합니다; 이 예제는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket을 활성화한 상태를 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다
+백엔드가 리터럴 `openai/...` 문자열을 기대할 때 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대할 때 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket 전송 외부의 `MultiProvider`에서도 작동합니다. 이 예시는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다.
-`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요하면 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 하위 OpenAI provider로 전달됩니다
+`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요하면 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 기본 OpenAI provider로 전달됩니다.
-사용자 지정 OpenAI 호환 엔드포인트 또는 프록시를 사용하는 경우 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` 엔드포인트를 지원하지 않는 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)를 참고하세요
+- 이는 websocket 전송을 통한 Responses API이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 OpenAI가 아닌 provider에는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 한 적용되지 않습니다.
+- 환경에서 아직 사용할 수 없다면 `websockets` 패키지를 설치하세요.
+- websocket 전송을 활성화한 뒤 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 여러 턴에 걸친 워크플로에서 같은 websocket 연결을 턴 간(및 중첩된 agent-as-tool 호출 간)에 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼를 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참고하세요.
-## OpenAI가 아닌 모델
+## OpenAI 외 모델
-OpenAI가 아닌 provider가 필요하면 SDK의 내장 provider 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 충분합니다. 각 패턴의 예제는 [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 통합 방식
+### OpenAI 외 provider 통합 방법
| 접근 방식 | 사용 시점 | 범위 |
| --- | --- | --- |
-| [`set_default_openai_client`][agents.set_default_openai_client] | OpenAI 호환 엔드포인트 하나를 대부분 또는 전체 에이전트의 기본값으로 사용해야 할 때 | 전역 기본값 |
-| [`ModelProvider`][agents.models.interface.ModelProvider] | 사용자 지정 provider 하나를 단일 실행(run)에 적용해야 할 때 | 실행(run)별 |
-| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 provider 또는 구체적인 모델 객체가 필요할 때 | 에이전트별 |
-| 서드파티 어댑터 | 내장 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요할 때 | [서드파티 어댑터](#third-party-adapters) 참고 |
+| [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트가 대부분 또는 모든 에이전트의 기본값이어야 하는 경우 | 전역 기본값 |
+| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider를 단일 실행에 적용해야 하는 경우 | 실행별 |
+| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트가 다른 provider 또는 구체적인 모델 객체를 필요로 하는 경우 | 에이전트별 |
+| 서드파티 어댑터 | 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우 | [서드파티 어댑터](#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 엔드포인트를 가지고 있고, `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)를 설정하는 것을 권장합니다.
``` python
from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
@@ -242,19 +242,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model
!!! note
- 이 예제들에서는 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. LLM provider가 이를 지원한다면 Responses 사용을 권장합니다
+ 이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문입니다. LLM provider가 이를 지원한다면 Responses 사용을 권장합니다.
## 하나의 워크플로에서 모델 혼합
-단일 워크플로 내에서 에이전트마다 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 분류(triage)에는 더 작고 빠른 모델을, 복잡한 작업에는 더 크고 성능이 높은 모델을 사용할 수 있습니다. [`Agent`][agents.Agent]를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다:
+단일 워크플로 내에서 각 에이전트마다 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 triage에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 성능이 뛰어난 모델을 사용할 수 있습니다. [`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
@@ -279,7 +279,7 @@ triage_agent = Agent(
name="Triage agent",
instructions="Handoff to the appropriate agent based on the language of the request.",
handoffs=[spanish_agent, english_agent],
- model="gpt-5.4",
+ model="gpt-5.5",
)
async def main():
@@ -287,10 +287,10 @@ async def main():
print(result.final_output)
```
-1. OpenAI 모델 이름을 직접 설정합니다
-2. [`Model`][agents.models.interface.Model] 구현을 제공합니다
+1. OpenAI 모델 이름을 직접 설정합니다.
+2. [`Model`][agents.models.interface.Model] 구현을 제공합니다.
-에이전트가 사용할 모델을 추가로 구성하려면 temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다
+에이전트에 사용되는 모델을 더 세부적으로 구성하려면 temperature와 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다.
```python
from agents import Agent, ModelSettings
@@ -305,26 +305,26 @@ 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`: 컨텍스트가 넘칠 때 실패 대신 가장 오래된 대화 항목을 Responses API가 삭제하도록 `"auto"` 설정
-- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 제어. 응답 ID에 의존하는 후속 워크플로와 `store=False`일 때 로컬 입력으로 폴백이 필요할 수 있는 세션 압축 흐름에 중요합니다
-- `prompt_cache_retention`: 예를 들어 `"24h"`처럼 캐시된 프롬프트 접두사를 더 오래 유지
-- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드 요청
-- `top_logprobs`: 출력 텍스트에 대한 상위 토큰 로그확률 요청. SDK는 `message.output_text.logprobs`도 자동 추가합니다
-- `retry`: 모델 호출에 대해 runner 관리 재시도 설정 사용. [Runner 관리 재시도](#runner-managed-retries) 참고
+- `parallel_tool_calls`: 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다.
+- `truncation`: context가 넘칠 때 실패하는 대신 Responses API가 가장 오래된 대화 항목을 삭제하도록 `"auto"`를 설정합니다.
+- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와, `store=False`일 때 로컬 입력으로 fallback해야 할 수 있는 세션 압축 흐름에 중요합니다.
+- `prompt_cache_retention`: 예를 들어 `"24h"`로 캐시된 프롬프트 접두사를 더 오래 유지합니다.
+- `response_include`: `web_search_call.action.sources`, `file_search_call.results` 또는 `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다.
+- `top_logprobs`: 출력 텍스트의 상위 토큰 logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다.
+- `retry`: 모델 호출에 대해 runner 관리 재시도 설정을 사용합니다. [Runner 관리 재시도](#runner-managed-retries)를 참고하세요.
```python
from agents import Agent, ModelSettings
research_agent = Agent(
name="Research agent",
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(
parallel_tool_calls=False,
truncation="auto",
@@ -336,13 +336,13 @@ research_agent = Agent(
)
```
-`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)를 참고하세요
+`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)를 참고하세요.
### `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
@@ -360,14 +360,14 @@ english_agent = Agent(
## Runner 관리 재시도
-재시도는 런타임 전용이며 옵트인입니다. SDK는 `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택한 경우를 제외하면 일반 모델 요청을 재시도하지 않습니다
+재시도는 런타임 전용이며 명시적으로 사용해야 합니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않는 한, SDK는 일반 모델 요청을 재시도하지 않습니다.
```python
from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
agent = Agent(
name="Assistant",
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(
retry=ModelRetrySettings(
max_retries=4,
@@ -388,85 +388,85 @@ agent = Agent(
)
```
-`ModelRetrySettings`에는 세 필드가 있습니다:
+`ModelRetrySettings`에는 세 가지 필드가 있습니다.
| 필드 | 타입 | 참고 |
| --- | --- | --- |
-| `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`: 원문 검사를 위한 값입니다.
+- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 사실
+- 기본 모델 어댑터가 재시도 지침을 제공할 수 있는 경우 `provider_advice`
-정책은 다음 중 하나를 반환할 수 있습니다:
+정책은 다음 중 하나를 반환할 수 있습니다.
-- 단순 재시도 결정을 위한 `True` / `False`
-- 지연 재정의 또는 진단 사유 첨부가 필요한 경우 [`RetryDecision`][agents.retry.RetryDecision]
+- 단순한 재시도 결정을 위한 `True` / `False`
+- 지연을 재정의하거나 진단 사유를 첨부하고 싶을 때 [`RetryDecision`][agents.retry.RetryDecision]
-SDK는 `retry_policies`에 즉시 사용 가능한 헬퍼를 제공합니다:
+SDK는 `retry_policies`에서 바로 사용할 수 있는 헬퍼를 내보냅니다.
| 헬퍼 | 동작 |
| --- | --- |
-| `retry_policies.never()` | 항상 재시도하지 않음 |
-| `retry_policies.provider_suggested()` | 가능할 때 provider 재시도 권고를 따름 |
-| `retry_policies.network_error()` | 일시적 전송/타임아웃 실패에 일치 |
-| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드에 일치 |
-| `retry_policies.retry_after()` | retry-after 힌트가 있을 때만 해당 지연으로 재시도 |
-| `retry_policies.any(...)` | 중첩 정책 중 하나라도 선택하면 재시도 |
-| `retry_policies.all(...)` | 중첩 정책 모두 선택할 때만 재시도 |
+| `retry_policies.never()` | 항상 사용하지 않습니다. |
+| `retry_policies.provider_suggested()` | 가능한 경우 provider의 재시도 조언을 따릅니다. |
+| `retry_policies.network_error()` | 일시적인 전송 및 timeout 실패와 일치합니다. |
+| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 일치합니다. |
+| `retry_policies.retry_after()` | retry-after 힌트를 사용할 수 있을 때만 해당 지연을 사용해 재시도합니다. |
+| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 사용을 선택하면 재시도합니다. |
+| `retry_policies.all(...)` | 모든 중첩 정책이 사용을 선택한 경우에만 재시도합니다. |
-정책을 조합할 때 `provider_suggested()`는 provider가 이를 구분할 수 있을 때 provider veto와 replay 안전 승인(replay-safety approvals)을 보존하므로 가장 안전한 첫 구성 요소입니다
+정책을 조합할 때는 provider가 이를 구분할 수 있는 경우 provider 거부와 replay-safety 승인을 보존하므로 `provider_suggested()`가 가장 안전한 첫 구성 요소입니다.
##### 안전 경계
-일부 실패는 자동으로 재시도되지 않습니다:
+일부 실패는 자동으로 재시도되지 않습니다.
- Abort 오류
-- provider 권고가 replay를 안전하지 않다고 표시한 요청
-- 출력이 이미 시작되어 replay가 안전하지 않게 되는 스트리밍 실행
+- provider 조언이 replay를 안전하지 않다고 표시한 요청
+- replay를 안전하지 않게 만들 방식으로 출력이 이미 시작된 이후의 스트리밍 실행
-`previous_response_id` 또는 `conversation_id`를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이런 요청에서는 `network_error()`나 `http_status([500])` 같은 non-provider 조건만으로는 충분하지 않습니다. 재시도 정책에 보통 `retry_policies.provider_suggested()`를 통한 provider의 replay-safe 승인이 포함되어야 합니다
+`previous_response_id` 또는 `conversation_id`를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청의 경우 `network_error()` 또는 `http_status([500])` 같은 provider가 아닌 predicate만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통해 provider의 replay-safe 승인이 포함되어야 합니다.
-##### Runner와 에이전트 병합 동작
+##### Runner 및 에이전트 병합 동작
-`retry`는 runner 수준과 에이전트 수준 `ModelSettings` 사이에서 깊은 병합(deep-merge)됩니다:
+`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`의 일부만 재정의하고 runner의 sibling backoff 필드를 유지할 수 있습니다.
+- `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries`와 `backoff`를 유지하지만 콜백 자체는 생략합니다.
-더 자세한 예제는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예제](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참고하세요
+더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참고하세요.
-## OpenAI가 아닌 provider 문제 해결
+## OpenAI 외 provider 문제 해결
### 트레이싱 클라이언트 오류 401
-트레이싱 관련 오류가 발생하면, trace가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 세 가지입니다:
+트레이싱과 관련된 오류가 발생한다면, 이는 trace가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 이를 해결하는 방법은 세 가지입니다.
-1. 트레이싱 완전 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
-2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/) 발급 키여야 합니다
-3. OpenAI가 아닌 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors) 참고
+1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
+2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)의 키여야 합니다.
+3. OpenAI가 아닌 trace 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참고하세요.
### Responses API 지원
-SDK는 기본적으로 Responses API를 사용하지만, 다른 많은 LLM 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`을 설정하는 경우 동작합니다
-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 지원
-일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이 경우 아래와 같은 오류가 발생할 수 있습니다:
+일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 유사한 오류가 발생합니다.
```
@@ -474,34 +474,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
```
-이는 일부 모델 provider의 한계입니다 - JSON 출력은 지원하지만 출력에 사용할 `json_schema` 지정은 허용하지 않습니다. 현재 수정 작업 중이지만, 그렇지 않으면 잘못된 JSON으로 앱이 자주 깨질 수 있으므로 JSON schema 출력을 지원하는 provider 사용을 권장합니다
+이는 일부 모델 provider의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정하도록 허용하지 않습니다. 이 문제를 해결하기 위해 작업 중이지만, 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 중단되므로 JSON schema 출력을 지원하는 provider에 의존하는 것을 권장합니다.
-## provider 간 모델 혼합
+## provider 전반에서 모델 혼합
-모델 provider 간 기능 차이를 인지해야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만 다른 많은 provider는 이를 지원하지 않습니다. 다음 제한을 유의하세요:
+모델 provider 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 다른 많은 provider는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요.
-- 지원하지 않는 provider에 지원되지 않는 `tools`를 보내지 마세요
-- 텍스트 전용 모델 호출 전 멀티모달 입력을 필터링하세요
-- structured JSON 출력을 지원하지 않는 provider는 가끔 유효하지 않은 JSON을 생성할 수 있음을 유의하세요
+- 이해하지 못하는 provider에 지원되지 않는 `tools`를 보내지 마세요
+- 텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하세요
+- structured JSON 출력을 지원하지 않는 provider는 때때로 잘못된 JSON을 생성한다는 점을 유의하세요.
## 서드파티 어댑터
-SDK의 내장 provider 통합 지점만으로 부족할 때만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM이나 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 우선하세요. 서드파티 어댑터는 OpenAI 모델과 OpenAI가 아닌 provider를 결합해야 하거나, 내장 경로가 제공하지 않는 어댑터 관리 provider 범위/라우팅이 필요할 때를 위한 것입니다. 어댑터는 SDK와 상위 모델 provider 사이에 또 하나의 호환 계층을 추가하므로 기능 지원과 요청 의미론은 provider마다 다를 수 있습니다. SDK는 현재 Any-LLM과 LiteLLM을 best-effort 베타 어댑터 통합으로 포함합니다
+SDK의 기본 제공 provider 통합 지점으로 충분하지 않을 때만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 기본 제공 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 OpenAI가 아닌 provider와 결합해야 하거나, 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 업스트림 모델 provider 사이에 또 다른 호환성 계층을 추가하므로, 기능 지원과 요청 의미 체계는 provider에 따라 달라질 수 있습니다. SDK는 현재 Any-LLM과 LiteLLM을 best-effort 베타 어댑터 통합으로 포함합니다.
### Any-LLM
-Any-LLM 지원은 Any-LLM 관리 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다
+Any-LLM 지원은 Any-LLM이 관리하는 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 기준으로 포함되어 있습니다.
-상위 provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환 계층을 사용할 수 있습니다
+업스트림 provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환성 계층을 사용할 수 있습니다.
-Any-LLM이 필요하면 `openai-agents[any-llm]`을 설치한 뒤 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)부터 시작하세요. [`MultiProvider`][agents.MultiProvider]와 함께 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 하면 `AnyLLMModel` 생성 시 `api="responses"` 또는 `api="chat_completions"`를 전달하세요
+Any-LLM이 필요하다면 `openai-agents[any-llm]`을 설치한 뒤 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)에서 시작하세요. [`MultiProvider`][agents.MultiProvider]와 함께 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 한다면 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요.
-Any-LLM은 서드파티 어댑터 계층이므로 provider 의존성과 기능 격차는 SDK가 아니라 Any-LLM 상위 계층에서 정의됩니다. 사용량 메트릭은 상위 provider가 반환하면 자동 전파되지만, 스트리밍 Chat Completions 백엔드는 사용량 청크를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, 도구 호출, 사용량 보고, Responses 전용 동작에 의존한다면 배포 예정 provider 백엔드를 정확히 검증하세요
+Any-LLM은 서드파티 어댑터 계층으로 남아 있으므로, provider 종속성과 기능 격차는 SDK가 아니라 Any-LLM이 업스트림에서 정의합니다. 업스트림 provider가 usage metrics를 반환하면 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 usage chunk를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, 도구 호출, usage reporting 또는 Responses-specific 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요.
### LiteLLM
-LiteLLM 지원은 LiteLLM 전용 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타로 포함됩니다
+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이 필요하다면 `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, 도구 호출, 사용량 보고, 어댑터별 라우팅 동작에 의존한다면 배포 예정 provider 백엔드를 정확히 검증하세요
\ No newline at end of file
+일부 LiteLLM 기반 provider는 기본적으로 SDK usage metrics를 채우지 않습니다. usage reporting이 필요하다면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, 도구 호출, usage reporting 또는 어댑터별 라우팅 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요.
\ No newline at end of file
diff --git a/docs/ko/results.md b/docs/ko/results.md
index 2e62face05..c5eeb4c9b5 100644
--- a/docs/ko/results.md
+++ b/docs/ko/results.md
@@ -4,95 +4,95 @@ search:
---
# 결과
-`Runner.run` 메서드를 호출하면 두 가지 결과 타입 중 하나를 받습니다:
+`Runner.run` 메서드를 호출하면 두 가지 결과 타입 중 하나를 받습니다.
- `Runner.run(...)` 또는 `Runner.run_sync(...)`의 [`RunResult`][agents.result.RunResult]
- `Runner.run_streamed(...)`의 [`RunResultStreaming`][agents.result.RunResultStreaming]
-두 타입 모두 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()` 같은 공통 결과 표면을 제공합니다
+둘 다 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()` 같은 공통 결과 표면을 노출합니다.
-`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어 기능을 추가로 제공합니다
+`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어를 추가합니다.
-## 올바른 결과 표면 선택
+## 적절한 결과 표면 선택
-대부분의 애플리케이션은 몇 가지 결과 속성이나 헬퍼만 필요합니다:
+대부분의 애플리케이션에는 몇 가지 결과 속성이나 헬퍼만 필요합니다.
-| 다음이 필요할 때... | 사용 |
+| 필요한 경우... | 사용 |
| --- | --- |
-| 사용자에게 보여줄 최종 응답 | `final_output` |
-| 전체 로컬 기록이 포함된, 재생 가능한 다음 턴 입력 목록 | `to_input_list()` |
-| 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 실행 아이템 | `new_items` |
+| 사용자에게 보여줄 최종 답변 | `final_output` |
+| 전체 로컬 transcript가 포함된, 재생 준비가 된 다음 턴 입력 목록 | `to_input_list()` |
+| 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 실행 항목 | `new_items` |
| 일반적으로 다음 사용자 턴을 처리해야 하는 에이전트 | `last_agent` |
-| `previous_response_id`를 사용하는 OpenAI Responses API 체이닝 | `last_response_id` |
-| 보류 중인 승인 및 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` |
+| `previous_response_id`를 사용한 OpenAI Responses API 체이닝 | `last_response_id` |
+| 대기 중인 승인과 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` |
| 현재 중첩된 `Agent.as_tool()` 호출에 대한 메타데이터 | `agent_tool_invocation` |
-| 원시 모델 호출 또는 가드레일 진단 | `raw_responses` 및 가드레일 결과 배열 |
+| 원문 모델 호출 또는 가드레일 진단 | `raw_responses` 및 가드레일 결과 배열 |
## 최종 출력
-[`final_output`][agents.result.RunResultBase.final_output] 속성은 마지막으로 실행된 에이전트의 최종 출력을 포함합니다. 이는 다음 중 하나입니다:
+[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이는 다음 중 하나입니다.
-- 마지막 에이전트에 `output_type`이 정의되지 않은 경우 `str`
-- 마지막 에이전트에 출력 타입이 정의된 경우 `last_agent.output_type` 타입의 객체
-- 최종 출력이 생성되기 전에 실행이 중지된 경우 `None`(예: 승인 인터럽션(중단 처리)에서 일시 중지된 경우)
+- 마지막 에이전트에 정의된 `output_type`이 없는 경우 `str`
+- 마지막 에이전트에 정의된 출력 타입이 있는 경우 `last_agent.output_type` 타입의 객체
+- 예를 들어 승인 인터럽션(중단 처리)에서 일시 중지되어 최종 출력이 생성되기 전에 실행이 중단된 경우 `None`
!!! note
- `final_output`의 타입은 `Any`입니다. 핸드오프가 실행을 완료하는 에이전트를 변경할 수 있으므로, SDK는 가능한 출력 타입의 전체 집합을 정적으로 알 수 없습니다
+ `final_output`은 `Any`로 타입이 지정되어 있습니다. 핸드오프는 어떤 에이전트가 실행을 완료하는지 바꿀 수 있으므로, SDK는 가능한 전체 출력 타입 집합을 정적으로 알 수 없습니다.
-스트리밍 모드에서는 스트림 처리가 끝날 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [Streaming](streaming.md)을 참고하세요
+스트리밍 모드에서는 스트림 처리가 완료될 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [스트리밍](streaming.md)을 참조하세요.
-## 입력, 다음 턴 기록, 새 아이템
+## 입력, 다음 턴 히스토리, 새 항목
-이 표면들은 서로 다른 질문에 답합니다:
+이 표면들은 서로 다른 질문에 답합니다.
-| 속성 또는 헬퍼 | 포함 내용 | 적합한 용도 |
+| 속성 또는 헬퍼 | 포함 내용 | 최적의 용도 |
| --- | --- | --- |
-| [`input`][agents.result.RunResultBase.input] | 이 실행 세그먼트의 기본 입력. 핸드오프 입력 필터가 기록을 다시 쓴 경우, 실행이 이어진 필터링된 입력을 반영합니다 | 이 실행이 실제로 어떤 입력을 사용했는지 감사 |
-| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 아이템 뷰. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 기록을 유지하며, `mode="normalized"`는 핸드오프 필터링이 모델 기록을 다시 쓸 때 정규화된 연속 입력을 우선합니다 | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 아이템 기록 점검 |
-| [`new_items`][agents.result.RunResultBase.new_items] | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 [`RunItem`][agents.items.RunItem] 래퍼 | 로그, UI, 감사, 디버깅 |
-| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행의 각 모델 호출에서 나온 원시 [`ModelResponse`][agents.items.ModelResponse] 객체 | 제공자 수준 진단 또는 원시 응답 점검 |
+| [`input`][agents.result.RunResultBase.input] | 이 실행 구간의 기본 입력입니다. 핸드오프 입력 필터가 히스토리를 다시 썼다면, 실행이 계속된 필터링된 입력을 반영합니다. | 이 실행이 실제로 입력으로 사용한 내용을 감사 |
+| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 항목 뷰입니다. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 히스토리를 유지합니다. `mode="normalized"`는 핸드오프 필터링이 모델 히스토리를 다시 쓸 때 표준 계속 입력을 우선합니다. | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 항목 히스토리 검사 |
+| [`new_items`][agents.result.RunResultBase.new_items] | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 [`RunItem`][agents.items.RunItem] 래퍼입니다. | 로그, UI, 감사, 디버깅 |
+| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행 중 각 모델 호출에서 나온 원문 [`ModelResponse`][agents.items.ModelResponse] 객체입니다. | 제공자 수준 진단 또는 원문 응답 검사 |
-실제로는 다음과 같습니다:
+실제로는 다음과 같습니다.
-- 실행의 일반 입력 아이템 뷰가 필요하면 `to_input_list()`를 사용하세요
-- 핸드오프 필터링 또는 중첩 핸드오프 기록 재작성 이후 다음 `Runner.run(..., input=...)` 호출에 사용할 정규화된 로컬 입력이 필요하면 `to_input_list(mode="normalized")`를 사용하세요
-- SDK가 기록을 대신 로드/저장하도록 하려면 [`session=...`](sessions/index.md)을 사용하세요
-- `conversation_id` 또는 `previous_response_id`로 OpenAI 서버 관리 상태를 사용하는 경우, 보통 `to_input_list()`를 다시 보내기보다 새 사용자 입력만 전달하고 저장된 ID를 재사용하세요
-- 로그, UI, 감사용으로 전체 변환 기록이 필요하면 기본 `to_input_list()` 모드 또는 `new_items`를 사용하세요
+- 실행의 일반 입력 항목 뷰가 필요할 때는 `to_input_list()`를 사용하세요.
+- 핸드오프 필터링 또는 중첩 핸드오프 히스토리 재작성 후 다음 `Runner.run(..., input=...)` 호출을 위한 표준 로컬 입력이 필요할 때는 `to_input_list(mode="normalized")`를 사용하세요.
+- SDK가 히스토리를 로드하고 저장해 주기를 원할 때는 [`session=...`](sessions/index.md)을 사용하세요.
+- `conversation_id` 또는 `previous_response_id`로 OpenAI 서버 관리 상태를 사용하는 경우, 일반적으로 `to_input_list()`를 다시 보내는 대신 새 사용자 입력만 전달하고 저장된 ID를 재사용하세요.
+- 로그, UI, 감사에 사용할 전체 변환 히스토리가 필요할 때는 기본 `to_input_list()` 모드 또는 `new_items`를 사용하세요.
-JavaScript SDK와 달리 Python은 모델 형태 델타 전용의 별도 `output` 속성을 제공하지 않습니다. SDK 메타데이터가 필요하면 `new_items`를 사용하고, 원시 모델 페이로드가 필요하면 `raw_responses`를 확인하세요
+JavaScript SDK와 달리 Python은 모델 형태의 델타만을 위한 별도의 `output` 속성을 노출하지 않습니다. SDK 메타데이터가 필요할 때는 `new_items`를 사용하고, 원문 모델 페이로드가 필요할 때는 `raw_responses`를 검사하세요.
-컴퓨터 도구 재생은 원시 Responses 페이로드 형태를 따릅니다. 프리뷰 모델의 `computer_call` 아이템은 단일 `action`을 유지하고, `gpt-5.4` 컴퓨터 호출은 일괄 `actions[]`를 유지할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 기록이 프리뷰와 GA 컴퓨터 도구 호출 모두에서 계속 동작합니다. 로컬 실행 결과는 여전히 `new_items`의 `computer_call_output` 아이템으로 나타납니다
+컴퓨터 도구 재생은 원문 Responses 페이로드 형태를 따릅니다. 프리뷰 모델 `computer_call` 항목은 단일 `action`을 보존하는 반면, `gpt-5.5` 컴퓨터 호출은 배치된 `actions[]`를 보존할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 transcript가 프리뷰 및 GA 컴퓨터 도구 호출 모두에서 계속 작동합니다. 로컬 실행 결과는 여전히 `new_items`에 `computer_call_output` 항목으로 표시됩니다.
-### 새 아이템
+### 새 항목
-[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 발생한 일을 가장 풍부하게 보여줍니다. 일반적인 아이템 타입은 다음과 같습니다:
+[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 일어난 일을 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다.
- 어시스턴트 메시지용 [`MessageOutputItem`][agents.items.MessageOutputItem]
-- 추론 아이템용 [`ReasoningItem`][agents.items.ReasoningItem]
-- Responses 도구 검색 요청과 로드된 도구 검색 결과용 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 및 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
-- 도구 호출과 그 결과용 [`ToolCallItem`][agents.items.ToolCallItem] 및 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
-- 승인을 위해 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
-- 핸드오프 요청과 완료된 전송용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
+- 추론 항목용 [`ReasoningItem`][agents.items.ReasoningItem]
+- Responses 도구 검색 요청 및 로드된 도구 검색 결과용 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 및 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
+- 도구 호출 및 그 결과용 [`ToolCallItem`][agents.items.ToolCallItem] 및 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
+- 승인 대기 중 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
+- 핸드오프 요청 및 완료된 전환용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
-에이전트 연관성, 도구 출력, 핸드오프 경계, 승인 경계가 필요할 때는 `to_input_list()`보다 `new_items`를 선택하세요
+에이전트 연결, 도구 출력, 핸드오프 경계 또는 승인 경계가 필요할 때마다 `to_input_list()` 대신 `new_items`를 선택하세요.
-호스티드 툴 검색을 사용할 때는 모델이 생성한 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을, 해당 턴에서 어떤 네임스페이스, 함수, 또는 호스티드 MCP 서버가 로드되었는지 보려면 `ToolSearchOutputItem.raw_item`을 확인하세요
+호스티드 툴 검색을 사용할 때는 모델이 내보낸 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을 검사하고, 해당 턴에 로드된 네임스페이스, 함수 또는 호스티드 MCP 서버를 보려면 `ToolSearchOutputItem.raw_item`을 검사하세요.
## 대화 계속 또는 재개
### 다음 턴 에이전트
-[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 들어 있습니다. 핸드오프 이후 다음 사용자 턴에서 재사용할 최적의 에이전트인 경우가 많습니다
+[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 들어 있습니다. 이는 핸드오프 후 다음 사용자 턴에 재사용하기 가장 좋은 에이전트인 경우가 많습니다.
-스트리밍 모드에서는 실행이 진행됨에 따라 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 업데이트되므로, 스트림이 끝나기 전에도 핸드오프를 관찰할 수 있습니다
+스트리밍 모드에서는 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 실행 진행에 따라 업데이트되므로, 스트림이 끝나기 전에 핸드오프를 관찰할 수 있습니다.
### 인터럽션(중단 처리) 및 실행 상태
-도구에 승인이 필요하면 보류 중인 승인 항목이 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구에서 발생한 승인, 핸드오프 이후 도달한 도구에서 발생한 승인, 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다
+도구에 승인이 필요한 경우, 대기 중인 승인은 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구, 핸드오프 후 도달한 도구 또는 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다.
-재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하려면 [`to_state()`][agents.result.RunResult.to_state]를 호출하고, 보류 중인 아이템을 승인 또는 거부한 다음, `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요
+[`to_state()`][agents.result.RunResult.to_state]를 호출해 재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하고, 대기 중인 항목을 승인하거나 거부한 다음 `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요.
```python
from agents import Agent, Runner
@@ -107,59 +107,59 @@ if result.interruptions:
result = await Runner.run(agent, state)
```
-스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음 `result.interruptions`를 확인하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [Human-in-the-loop](human_in_the_loop.md)를 참고하세요
+스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음 `result.interruptions`를 검사하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md)를 참조하세요.
-### 서버 관리 연속 실행
+### 서버 관리 계속
-[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행의 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 이어가려면 다음 턴에서 이를 `previous_response_id`로 다시 전달하세요
+[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행의 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 계속하려면 다음 턴에서 `previous_response_id`로 다시 전달하세요.
-이미 `to_input_list()`, `session`, 또는 `conversation_id`로 대화를 이어가고 있다면 보통 `last_response_id`는 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하면 대신 `raw_responses`를 확인하세요
+이미 `to_input_list()`, `session` 또는 `conversation_id`로 대화를 계속하고 있다면 일반적으로 `last_response_id`가 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하다면 대신 `raw_responses`를 검사하세요.
## Agent-as-tool 메타데이터
-결과가 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 바깥 도구 호출에 대한 불변 메타데이터를 제공합니다:
+결과가 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 외부 도구 호출에 대한 불변 메타데이터를 노출합니다.
- `tool_name`
- `tool_call_id`
- `tool_arguments`
-일반적인 최상위 실행에서는 `agent_tool_invocation`이 `None`입니다
+일반적인 최상위 실행의 경우 `agent_tool_invocation`은 `None`입니다.
-이는 특히 `custom_output_extractor` 내부에서 유용합니다. 중첩 결과를 후처리하는 동안 바깥 도구 이름, 호출 ID, 또는 원시 인자가 필요할 수 있기 때문입니다. 주변 `Agent.as_tool()` 패턴은 [Tools](tools.md)를 참고하세요
+이는 중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 수 있는 `custom_output_extractor` 내부에서 특히 유용합니다. 관련 `Agent.as_tool()` 패턴은 [도구](tools.md)를 참조하세요.
-해당 중첩 실행의 파싱된 구조화 입력도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 중첩 도구 입력에 대해 [`RunState`][agents.run_state.RunState]가 일반적으로 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출을 위한 실시간 결과 접근자입니다
+해당 중첩 실행의 파싱된 structured input도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 [`RunState`][agents.run_state.RunState]가 중첩 도구 입력을 일반적으로 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출에 대한 실시간 결과 접근자입니다.
## 스트리밍 수명 주기 및 진단
-[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 표면을 상속하지만, 스트리밍 전용 제어 기능을 추가합니다:
+[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 표면을 상속하지만, 스트리밍 전용 제어를 추가합니다.
-- 의미 단위 스트림 이벤트 소비용 [`stream_events()`][agents.result.RunResultStreaming.stream_events]
-- 실행 중 활성 에이전트 추적용 [`current_agent`][agents.result.RunResultStreaming.current_agent]
-- 스트리밍 실행의 완전 종료 여부 확인용 [`is_complete`][agents.result.RunResultStreaming.is_complete]
-- 즉시 또는 현재 턴 이후 실행 중지용 [`cancel(...)`][agents.result.RunResultStreaming.cancel]
+- 의미론적 스트림 이벤트를 소비하기 위한 [`stream_events()`][agents.result.RunResultStreaming.stream_events]
+- 실행 중 활성 에이전트를 추적하기 위한 [`current_agent`][agents.result.RunResultStreaming.current_agent]
+- 스트리밍된 실행이 완전히 완료되었는지 확인하기 위한 [`is_complete`][agents.result.RunResultStreaming.is_complete]
+- 실행을 즉시 또는 현재 턴 이후 중지하기 위한 [`cancel(...)`][agents.result.RunResultStreaming.cancel]
-비동기 이터레이터가 끝날 때까지 `stream_events()` 소비를 계속하세요. 스트리밍 실행은 해당 이터레이터가 종료되어야 완료되며, 마지막으로 보이는 토큰이 도착한 뒤에도 `final_output`, `interruptions`, `raw_responses`, 세션 영속화 부작용 같은 요약 속성은 아직 정리 중일 수 있습니다
+비동기 이터레이터가 끝날 때까지 `stream_events()` 소비를 계속하세요. 스트리밍 실행은 해당 이터레이터가 종료되기 전까지 완료되지 않으며, `final_output`, `interruptions`, `raw_responses` 같은 요약 속성과 세션 지속성 부작용은 마지막으로 보이는 토큰이 도착한 후에도 아직 정리 중일 수 있습니다.
-`cancel()`을 호출한 경우에도 취소 및 정리가 올바르게 완료되도록 `stream_events()` 소비를 계속하세요
+`cancel()`을 호출했다면 취소와 정리가 올바르게 완료될 수 있도록 `stream_events()` 소비를 계속하세요.
-Python은 별도의 스트리밍 `completed` promise나 `error` 속성을 제공하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외를 발생시키는 방식으로 표면화되며, `is_complete`는 실행이 최종 상태에 도달했는지를 반영합니다
+Python은 별도의 스트리밍된 `completed` promise나 `error` 속성을 노출하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외를 발생시키는 방식으로 표시되며, `is_complete`는 실행이 최종 상태에 도달했는지 여부를 반영합니다.
-### 원시 응답
+### 원문 응답
-[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원시 모델 응답이 포함됩니다. 다단계 실행에서는 예를 들어 핸드오프 또는 반복적인 모델/도구/모델 사이클 전반에 걸쳐 둘 이상의 응답이 생성될 수 있습니다
+[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원문 모델 응답이 들어 있습니다. 다단계 실행은 예를 들어 핸드오프 또는 반복되는 모델/도구/모델 사이클 전반에서 둘 이상의 응답을 생성할 수 있습니다.
-[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목 ID일 뿐입니다
+[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목에서 나온 ID일 뿐입니다.
### 가드레일 결과
-에이전트 수준 가드레일은 [`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results]와 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results]로 노출됩니다
+에이전트 수준 가드레일은 [`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] 및 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results]로 노출됩니다.
-도구 가드레일은 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results]와 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results]로 별도로 노출됩니다
+도구 가드레일은 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 및 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results]로 별도로 노출됩니다.
-이 배열들은 실행 전반에 걸쳐 누적되므로, 결정 사항 로깅, 추가 가드레일 메타데이터 저장, 또는 실행이 차단된 이유 디버깅에 유용합니다
+이 배열들은 실행 전반에 걸쳐 누적되므로, 의사결정 로깅, 추가 가드레일 메타데이터 저장 또는 실행이 차단된 이유 디버깅에 유용합니다.
### 컨텍스트 및 사용량
-[`context_wrapper`][agents.result.RunResultBase.context_wrapper]는 승인, 사용량, 중첩 `tool_input` 같은 SDK 관리 런타임 메타데이터와 함께 앱 컨텍스트를 제공합니다
+[`context_wrapper`][agents.result.RunResultBase.context_wrapper]는 승인, 사용량, 중첩 `tool_input` 같은 SDK 관리 런타임 메타데이터와 함께 앱 컨텍스트를 노출합니다.
-사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행에서는 스트림의 최종 청크가 처리될 때까지 사용량 합계가 지연될 수 있습니다. 전체 래퍼 형태와 영속성 주의사항은 [Context management](context.md)를 참고하세요
\ No newline at end of file
+사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행의 경우 사용량 합계는 스트림의 마지막 청크가 처리될 때까지 지연될 수 있습니다. 전체 래퍼 형태와 지속성 관련 주의사항은 [컨텍스트 관리](context.md)를 참조하세요.
\ No newline at end of file
diff --git a/docs/ko/sandbox/guide.md b/docs/ko/sandbox/guide.md
index 719dabd26a..a14ee063d6 100644
--- a/docs/ko/sandbox/guide.md
+++ b/docs/ko/sandbox/guide.md
@@ -6,35 +6,35 @@ search:
!!! warning "베타 기능"
- Sandbox Agents는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+ Sandbox 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
-현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. **Sandbox Agents**는 특화된 도구와 셸 명령을 활용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 워크스페이스를 제공하며, 에이전트는 이를 사용해 사용자를 대신해 작업할 수 있습니다. Agents SDK의 Sandbox Agents는 샌드박스 환경과 연결된 에이전트를 쉽게 실행할 수 있게 해주며, 파일시스템에 올바른 파일을 배치하고 샌드박스를 오케스트레이션해 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있도록 도와줍니다.
+최신 에이전트는 파일시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. **Sandbox 에이전트**는 특수 도구와 셸 명령을 사용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 에이전트가 사용자를 대신해 작업하는 데 사용할 수 있는 지속적 워크스페이스를 모델에 제공합니다. Agents SDK의 Sandbox 에이전트는 샌드박스 환경과 결합된 에이전트를 쉽게 실행하도록 도와주며, 적절한 파일을 파일시스템에 배치하고 샌드박스를 오케스트레이션하여 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다.
-워크스페이스는 에이전트에 필요한 데이터를 중심으로 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
+에이전트가 필요로 하는 데이터를 중심으로 워크스페이스를 정의합니다. GitHub 저장소, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 다른 샌드박스 입력에서 시작할 수 있습니다.
-
+
-`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 그대로 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.
+`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.
-- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스 전용 기본값과 파일시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다
-- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함해 새 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다
-- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 실제 격리 환경입니다
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 샌드박스 세션을 어떻게 얻는지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 재연결하거나, 샌드박스 클라이언트를 통해 새로운 샌드박스 세션을 생성할 수 있습니다
-- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 재연결하거나 저장된 콘텐츠로 새로운 샌드박스 세션을 시드할 수 있습니다
+- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값, 파일시스템 도구, 셸 접근, 스킬, 메모리 또는 컴팩션 같은 기능을 포함합니다.
+- `Manifest`는 파일, 저장소, 마운트, 환경을 포함하여 새 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다.
+- 샌드박스 세션은 명령이 실행되고 파일이 변경되는 라이브 격리 환경입니다.
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 얻을지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성할 수 있습니다.
+- 저장된 샌드박스 상태와 스냅샷을 통해 이후 실행이 이전 작업에 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시작할 수 있습니다.
-`Manifest`는 새 세션 워크스페이스 계약이지, 모든 실제 샌드박스의 완전한 단일 진실 공급원은 아닙니다. 실행의 실효 워크스페이스는 대신 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시점에 선택된 스냅샷에서 올 수 있습니다.
+`Manifest`는 새 세션 워크스페이스 계약이지, 모든 라이브 샌드박스에 대한 전체 진실의 원천은 아닙니다. 실행의 실제 워크스페이스는 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시 선택된 스냅샷에서 올 수도 있습니다.
-이 페이지 전반에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 실제 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에서 설명하는 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와는 다릅니다.
+이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 라이브 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에 설명된 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와 다릅니다.
-바깥 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 기록 관리를 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 모델의 핵심 부분입니다.
+외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 북키핑을 소유합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 소유합니다. 이 분리는 모델의 핵심 부분입니다.
-### 구성 요소의 결합 방식
+### 구성 요소의 조합
-샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. 러너는 에이전트를 준비하고, 이를 실제 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
+샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. runner는 에이전트를 준비하고 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
```mermaid
flowchart LR
@@ -50,33 +50,33 @@ flowchart LR
sandbox --> saved
```
-샌드박스 전용 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다.
+샌드박스별 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다.
-수명주기를 세 단계로 생각해 보세요.
+라이프사이클을 세 단계로 생각해 보세요.
-1. `SandboxAgent`, `Manifest`, 기능을 사용해 에이전트와 새 워크스페이스 계약을 정의합니다
-2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공해 실행합니다
-3. 러너가 관리하는 `RunState`, 명시적인 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어갑니다
+1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 워크스페이스 계약을 정의합니다.
+2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공하여 실행을 수행합니다.
+3. runner가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어서 진행합니다.
-셸 접근이 가끔 필요한 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
+셸 접근이 가끔 사용하는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부일 때 샌드박스 에이전트를 사용하세요.
## 사용 시점
-샌드박스 에이전트는 워크스페이스 중심 워크플로에 적합합니다. 예를 들면 다음과 같습니다.
+샌드박스 에이전트는 다음과 같은 워크스페이스 중심 워크플로에 적합합니다.
-- 코딩 및 디버깅. 예를 들어 GitHub 리포지토리의 이슈 보고서에 대한 자동 수정 작업을 오케스트레이션하고 대상 테스트를 실행하는 경우
-- 문서 처리 및 편집. 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성 완료된 세금 양식 초안을 만드는 경우
-- 파일 기반 검토 또는 분석. 예를 들어 온보딩 패킷, 생성된 보고서, 또는 아티팩트 번들을 확인한 뒤 응답하는 경우
-- 격리된 다중 에이전트 패턴. 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 워크스페이스를 제공하는 경우
-- 다단계 워크스페이스 작업. 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개하는 경우
+- 코딩 및 디버깅. 예를 들어 GitHub 저장소의 이슈 보고서에 대한 자동 수정 오케스트레이션과 대상 테스트 실행
+- 문서 처리 및 편집. 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성된 세금 양식 초안 생성
+- 파일 기반 검토 또는 분석. 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 아티팩트 번들 확인
+- 격리된 다중 에이전트 패턴. 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 워크스페이스 제공
+- 다단계 워크스페이스 작업. 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개
-파일이나 실제 파일시스템에 대한 접근이 필요하지 않다면 계속 `Agent`를 사용하세요. 셸 접근이 가끔 필요한 기능일 뿐이라면 호스티드 셸을 추가하고, 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
+파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
## 샌드박스 클라이언트 선택
-로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리나 이미지 일치성이 필요하면 `DockerSandboxClient`로 이동하세요. 제공업체가 관리하는 실행이 필요하면 호스티드 제공업체로 이동하세요.
+로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리 또는 이미지 동등성이 필요할 때 `DockerSandboxClient`로 이동하세요. 제공자 관리 실행이 필요할 때 호스티드 제공자로 이동하세요.
-대부분의 경우 `SandboxAgent` 정의는 그대로 유지되고, 샌드박스 클라이언트와 해당 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [Sandbox clients](clients.md)를 참고하세요.
+대부분의 경우 `SandboxAgent` 정의는 그대로 두고, 샌드박스 클라이언트와 해당 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경합니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
## 핵심 구성 요소
@@ -84,69 +84,69 @@ flowchart LR
| 계층 | 주요 SDK 구성 요소 | 답하는 질문 |
| --- | --- | --- |
-| 에이전트 정의 | `SandboxAgent`, `Manifest`, capabilities | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하는가? |
-| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 실제 샌드박스 세션 | 이 실행은 실제 샌드박스 세션을 어떻게 얻으며, 작업은 어디에서 실행되는가? |
-| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 재연결하거나 저장된 콘텐츠로 새로운 샌드박스 세션을 어떻게 시드하는가? |
+| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하나요? |
+| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 어떻게 라이브 샌드박스 세션을 얻으며, 작업은 어디서 실행되나요? |
+| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시작하나요? |
-주요 SDK 구성 요소는 다음과 같이 해당 계층에 매핑됩니다.
+주요 SDK 구성 요소는 다음과 같이 이러한 계층에 매핑됩니다.
-| 구성 요소 | 소유 대상 | 확인할 질문 |
+| 구성 요소 | 소유 대상 | 질문 |
| --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값을 함께 가져가야 하는가? |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일 및 폴더 | 실행 시작 시 파일시스템에 어떤 파일과 폴더가 있어야 하는가? |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 어떤 도구, 지시문 조각, 또는 런타임 동작을 이 에이전트에 부착해야 하는가? |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트 및 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 생성해야 하는가? |
-| [`RunState`][agents.run_state.RunState] | 러너가 관리하는 저장된 샌드박스 상태 | 이전에 러너가 관리하던 워크플로를 재개하면서 샌드박스 상태를 자동으로 이어받고 있는가? |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적인 직렬화된 샌드박스 세션 상태 | 이미 `RunState` 외부에서 직렬화한 샌드박스 상태로 재개하고 싶은가? |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새로운 샌드박스 세션을 위한 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하는가? |
+| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 이동해야 하나요? |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일과 폴더 | 실행 시작 시 파일시스템에 어떤 파일과 폴더가 있어야 하나요? |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 이 에이전트에 어떤 도구, instruction 조각, 또는 런타임 동작을 연결해야 하나요? |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트와 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 생성 중 무엇으로 처리해야 하나요? |
+| [`RunState`][agents.run_state.RunState] | runner가 관리하는 저장된 샌드박스 상태 | 이전 runner 관리 워크플로를 재개하고 그 샌드박스 상태를 자동으로 이어가고 있나요? |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적으로 직렬화된 샌드박스 세션 상태 | `RunState` 외부에서 이미 직렬화한 샌드박스 상태에서 재개하고 싶나요? |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션을 위한 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하나요? |
실용적인 설계 순서는 다음과 같습니다.
-1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다
-2. `SandboxAgent`로 에이전트를 정의합니다
-3. 내장 또는 커스텀 기능을 추가합니다
-4. `RunConfig(sandbox=SandboxRunConfig(...))`에서 각 실행이 샌드박스 세션을 어떻게 얻을지 결정합니다
+1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다.
+2. `SandboxAgent`로 에이전트를 정의합니다.
+3. 내장 또는 사용자 지정 기능을 추가합니다.
+4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 어떻게 얻을지 결정합니다.
## 샌드박스 실행 준비 방식
-실행 시 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
+실행 시 runner는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
-1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다
- `session=...`을 전달하면 해당 실제 샌드박스 세션을 재사용합니다
- 그렇지 않으면 `client=...`를 사용해 생성하거나 재개합니다
-2. 실행의 실효 워크스페이스 입력을 결정합니다
- 실행이 샌드박스 세션을 주입하거나 재개하는 경우, 기존 샌드박스 상태가 우선합니다
- 그렇지 않으면 러너는 일회성 manifest 재정의 또는 `agent.default_manifest`에서 시작합니다
- 그래서 `Manifest`만으로는 모든 실행의 최종 실제 워크스페이스를 정의하지 않습니다
-3. 기능이 결과 manifest를 처리하도록 합니다
- 이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 워크스페이스 범위 동작을 추가할 수 있습니다
-4. 고정된 순서로 최종 instructions를 구성합니다
- SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 `base_instructions`, 그 다음 `instructions`, 그 다음 기능 지시문 조각, 그 다음 원격 마운트 정책 텍스트, 마지막으로 렌더링된 파일시스템 트리 순입니다
-5. 기능 도구를 실제 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다
+1. `SandboxRunConfig`에서 샌드박스 세션을 해석합니다.
+ `session=...`을 전달하면 해당 라이브 샌드박스 세션을 재사용합니다.
+ 그렇지 않으면 `client=...`를 사용해 세션을 생성하거나 재개합니다.
+2. 실행의 실제 워크스페이스 입력을 결정합니다.
+ 실행이 샌드박스 세션을 주입하거나 재개하면 해당 기존 샌드박스 상태가 우선합니다.
+ 그렇지 않으면 runner는 일회성 manifest 재정의 또는 `agent.default_manifest`에서 시작합니다.
+ 이것이 `Manifest`만으로는 모든 실행의 최종 라이브 워크스페이스를 정의하지 않는 이유입니다.
+3. 기능이 결과 manifest를 처리하도록 합니다.
+ 이를 통해 최종 에이전트가 준비되기 전에 기능이 파일, 마운트 또는 다른 워크스페이스 범위 동작을 추가할 수 있습니다.
+4. 고정된 순서로 최종 instructions를 구성합니다.
+ SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 instruction 조각, 그다음 원격 마운트 정책 텍스트, 그다음 렌더링된 파일시스템 트리입니다.
+5. 기능 도구를 라이브 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다.
-샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 작업이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 안에 머무를 수 있고, 다른 작업은 도구 결과, 승인, 또는 또 다른 모델 단계가 필요한 기타 상태를 반환할 수 있습니다. 실용적으로 말하면, 샌드박스 작업이 발생한 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 턴이 소비됩니다.
+샌드박싱은 turn의 의미를 바꾸지 않습니다. turn은 여전히 모델 단계이지, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 turn 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머무를 수 있고, 다른 작업은 도구 결과, 승인 또는 다른 상태를 반환하여 또 다른 모델 단계가 필요할 수 있습니다. 실용적인 규칙으로, 샌드박스 작업이 발생한 뒤 에이전트 런타임에 또 다른 모델 응답이 필요할 때만 또 다른 turn이 소비됩니다.
-이러한 준비 단계 때문에 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`가 `SandboxAgent`를 설계할 때 생각해야 할 주요 샌드박스 전용 옵션입니다.
+이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 생각해야 할 주요 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다.
## `SandboxAgent` 옵션
-다음은 일반적인 `Agent` 필드에 더해지는 샌드박스 전용 옵션입니다.
+일반적인 `Agent` 필드에 추가되는 샌드박스별 옵션은 다음과 같습니다.
-| 옵션 | 적절한 사용처 |
+| 옵션 | 최적의 사용 |
| --- | --- |
-| `default_manifest` | 러너가 생성하는 새로운 샌드박스 세션의 기본 워크스페이스 |
+| `default_manifest` | runner가 생성하는 새 샌드박스 세션의 기본 워크스페이스 |
| `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 |
| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 |
-| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구 및 동작 |
-| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
+| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구와 동작 |
+| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대면 샌드박스 도구의 사용자 ID |
@@ -154,97 +154,97 @@ flowchart LR
### `default_manifest`
-`default_manifest`는 러너가 이 에이전트를 위해 새로운 샌드박스 세션을 만들 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작할 파일, 리포지토리, 도우미 자료, 출력 디렉터리, 마운트에 사용하세요.
+`default_manifest`는 runner가 이 에이전트에 대해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작해야 하는 파일, 저장소, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
-이것은 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있고, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
+이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
-### `instructions`와 `base_instructions`
+### `instructions` 및 `base_instructions`
-다양한 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
+서로 다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
-SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정할 필요가 없습니다.
+SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정하지 않아야 합니다.
-| 다음에 넣기... | 용도 | 예시 |
+| 넣을 위치 | 용도 | 예시 |
| --- | --- | --- |
-| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 뒤 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
-| `base_instructions` | SDK 샌드박스 기본 프롬프트의 완전한 대체 | 커스텀 저수준 샌드박스 래퍼 프롬프트 |
-| 사용자 프롬프트 | 이번 실행을 위한 일회성 요청 | "이 워크스페이스를 요약하세요." |
-| manifest의 워크스페이스 파일 | 더 긴 작업 명세, 리포지토리 로컬 instructions, 또는 범위가 제한된 참조 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
+| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 다음 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
+| `base_instructions` | SDK 샌드박스 기본 프롬프트의 완전한 대체 | 사용자 지정 저수준 샌드박스 래퍼 프롬프트 |
+| 사용자 프롬프트 | 이 실행의 일회성 요청 | "이 워크스페이스를 요약하세요." |
+| manifest의 워크스페이스 파일 | 더 긴 작업 명세, 저장소 로컬 instructions, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
`instructions`의 좋은 사용 예는 다음과 같습니다.
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트가 하나의 인터랙티브 프로세스 안에 머물도록 합니다
-- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 샌드박스 리뷰어가 검토 후 사용자에게 직접 응답하지 못하도록 금지합니다
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성된 파일이 실제로 `output/`에 저장되도록 요구합니다
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 워크스페이스 루트 기준의 패치 경로를 명확히 합니다
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트를 하나의 대화형 프로세스에 유지합니다.
+- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 샌드박스 리뷰어가 검사 후 사용자에게 직접 답변하는 것을 금지합니다.
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종으로 채워진 파일이 실제로 `output/`에 저장되도록 요구합니다.
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 워크스페이스 루트 기준 패치 경로를 명확히 합니다.
-사용자의 일회성 작업을 `instructions`에 복사하거나, manifest에 들어가야 할 긴 참조 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시점에 필요로 하지 않는 로컬 설치 메모를 섞어 넣는 것은 피하세요.
+사용자의 일회성 작업을 `instructions`에 복사하거나, manifest에 속해야 하는 긴 참고 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 다시 서술하거나, 런타임에 모델에 필요하지 않은 로컬 설치 메모를 섞지 마세요.
-`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 저수준 래퍼에는 이것만으로 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공하는 것이 좋습니다.
+`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대면 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다.
### `capabilities`
-Capabilities는 샌드박스 네이티브 동작을 `SandboxAgent`에 부착합니다. 실행 시작 전 워크스페이스를 구성하고, 샌드박스 전용 instructions를 추가하며, 실제 샌드박스 세션에 바인딩되는 도구를 노출하고, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
+기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 실행 시작 전에 워크스페이스를 형성하고, 샌드박스별 instructions를 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작 또는 입력 처리를 조정할 수 있습니다.
-내장 기능에는 다음이 포함됩니다.
+내장 기능은 다음과 같습니다.
-| Capability | 추가할 시점 | 참고 |
+| 기능 | 추가할 때 | 참고 |
| --- | --- | --- |
-| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가합니다 |
-| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 확인해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준 상대 경로입니다 |
-| `Skills` | 샌드박스에서 스킬 검색과 구체화가 필요할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 대신 이것을 권장합니다. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화해 줍니다 |
-| `Memory` | 후속 실행이 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요하며, 실시간 업데이트에는 `Filesystem`도 필요합니다 |
-| `Compaction` | 장시간 실행 흐름에서 컴팩션 항목 이후 컨텍스트 축소가 필요할 때 | 모델 샘플링과 입력 처리를 조정합니다 |
+| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하고, 샌드박스 클라이언트가 PTY 상호작용을 지원할 때 `write_stdin`도 추가합니다. |
+| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준입니다. |
+| `Skills` | 샌드박스에서 스킬 검색과 구체화가 필요할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이를 선호하세요. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화합니다. |
+| `Memory` | 후속 실행이 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. |
+| `Compaction` | 장기 실행 흐름이 컴팩션 항목 이후 컨텍스트 트리밍을 필요로 할 때 | 모델 샘플링과 입력 처리를 조정합니다. |
-기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 그 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 함께 포함해야 합니다.
+기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 포함하세요.
-스킬의 경우, 구체화 방식을 기준으로 소스를 선택하세요.
+스킬의 경우, 어떻게 구체화할지에 따라 소스를 선택하세요.
-- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 더 큰 로컬 스킬 디렉터리에 적합한 기본 선택입니다. 모델이 먼저 인덱스를 탐색하고 필요한 것만 로드할 수 있기 때문입니다
-- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 워크스페이스 내부에만 존재하는 경로가 아니라 원래 호스트 측 스킬 디렉터리를 전달하세요
-- `Skills(from_=LocalDir(src=...))`는 미리 단계적으로 올려두고 싶은 작은 로컬 번들에 더 적합합니다
-- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다
+- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있으므로 더 큰 로컬 스킬 디렉터리에 좋은 기본값입니다.
+- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 워크스페이스 내부에만 존재하는 경로가 아니라 원래의 호스트 측 스킬 디렉터리를 전달하세요.
+- `Skills(from_=LocalDir(src=...))`는 미리 스테이징하려는 작은 로컬 번들에 더 적합합니다.
+- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 저장소에서 와야 할 때 적합합니다.
-`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 배치되는 샌드박스 워크스페이스 내부의 상대 대상 경로입니다.
+`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 워크스페이스 내부의 상대 대상 경로입니다.
-스킬이 이미 `.agents/skills//SKILL.md` 같은 형태로 디스크에 있다면, `LocalDir(...)`는 해당 소스 루트를 가리키게 하고, 노출에는 여전히 `Skills(...)`를 사용하세요. 기존 워크스페이스 계약이 다른 샌드박스 내부 레이아웃에 의존하지 않는 한 기본 `skills_path=".agents"`를 유지하세요.
+스킬이 이미 `.agents/skills//SKILL.md` 같은 디스크 위치에 있다면, 해당 소스 루트를 `LocalDir(...)`로 지정하되, 여전히 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 워크스페이스 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요.
-적합하다면 내장 기능을 우선 사용하세요. 내장 기능으로 다루지 못하는 샌드박스 전용 도구나 지시문 표면이 필요할 때만 커스텀 capability를 작성하세요.
+적합할 때는 내장 기능을 선호하세요. 내장 기능이 제공하지 않는 샌드박스별 도구나 instruction 표면이 필요할 때만 사용자 지정 기능을 작성하세요.
## 개념
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest]는 새로운 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 대한 접근을 부여할 수 있습니다.
+[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 저장소를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자 또는 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 접근 권한을 부여할 수 있습니다.
-Manifest 항목 경로는 워크스페이스 상대 경로입니다. 절대 경로일 수 없고 `..`로 워크스페이스를 벗어날 수도 없으므로, 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
+Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절대 경로가 될 수 없고 `..`로 워크스페이스를 벗어날 수 없으므로, 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
-작업 시작 전에 에이전트가 필요로 하는 자료에는 manifest 항목을 사용하세요.
+작업이 시작되기 전에 에이전트가 필요로 하는 자료에는 manifest 항목을 사용하세요.
| Manifest 항목 | 용도 |
| --- | --- |
-| `File`, `Dir` | 작은 합성 입력, 도우미 파일, 또는 출력 디렉터리 |
-| `LocalFile`, `LocalDir` | 샌드박스에 구체화되어야 하는 호스트 파일 또는 디렉터리 |
-| `GitRepo` | 워크스페이스로 가져와야 하는 리포지토리 |
-| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 mounts | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
+| `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 |
+| `LocalFile`, `LocalDir` | 샌드박스에 구체화해야 하는 호스트 파일 또는 디렉터리 |
+| `GitRepo` | 워크스페이스로 가져와야 하는 저장소 |
+| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 마운트 | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
-Mount 항목은 노출할 스토리지를 설명하고, mount 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 마운트 옵션과 제공업체 지원은 [Sandbox clients](clients.md#mounts-and-remote-storage)를 참고하세요.
+마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 제공자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요.
-좋은 manifest 설계는 보통 워크스페이스 계약을 좁게 유지하고, 긴 작업 절차는 `repo/task.md` 같은 워크스페이스 파일에 넣고, instructions에서는 `repo/task.md`나 `output/report.md`처럼 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` capability의 `apply_patch` 도구로 파일을 편집한다면, 패치 경로는 셸 `workdir`이 아니라 샌드박스 워크스페이스 루트 기준 상대 경로임을 기억하세요.
+좋은 manifest 설계는 일반적으로 워크스페이스 계약을 좁게 유지하고, 긴 작업 레시피는 `repo/task.md` 같은 워크스페이스 파일에 넣으며, instructions에서는 `repo/task.md` 또는 `output/report.md` 같은 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준이라는 점을 기억하세요.
-에이전트가 워크스페이스 외부의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력을 위한 `/tmp`나 읽기 전용 런타임을 위한 `/opt/toolchain` 등이 있습니다. 권한 부여는 백엔드가 파일시스템 정책을 강제할 수 있는 SDK 파일 API와 셸 실행 모두에 적용됩니다.
+에이전트가 워크스페이스 외부의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력을 위한 `/tmp` 또는 읽기 전용 런타임을 위한 `/opt/toolchain`입니다. grant는 SDK 파일 API와, 백엔드가 파일시스템 정책을 강제할 수 있는 경우 셸 실행 모두에 적용됩니다.
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -257,13 +257,13 @@ manifest = Manifest(
)
```
-스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 부여된 경로는 런타임 접근이지, 지속되는 워크스페이스 상태가 아닙니다.
+스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 권한이 부여된 경로는 런타임 접근이며, 지속되는 워크스페이스 상태가 아닙니다.
### 권한
-`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 대한 것이며, 모델 권한, 승인 정책, API 자격 증명에 대한 것이 아닙니다.
+`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책 또는 API 자격 증명에 관한 것이 아닙니다.
-기본적으로 manifest 항목은 소유자 읽기/쓰기/실행 가능, 그룹과 기타 사용자 읽기/실행 가능입니다. 단계적으로 올린 파일을 비공개, 읽기 전용, 또는 실행 가능으로 해야 할 때 이를 재정의하세요.
+기본적으로 manifest 항목은 소유자가 읽기/쓰기/실행 가능하고 그룹과 기타 사용자가 읽기/실행 가능합니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능해야 할 때 이를 재정의하세요.
```python
from agents.sandbox import FileMode, Permissions
@@ -279,9 +279,9 @@ private_notes = File(
)
```
-`Permissions`는 소유자, 그룹, 기타에 대한 개별 비트와 해당 항목이 디렉터리인지 여부를 저장합니다. 직접 구성할 수도 있고, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수도 있습니다.
+`Permissions`는 소유자, 그룹, 기타 사용자 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 만들거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다.
-사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재하도록 하려면 manifest에 `User`를 추가하고, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구를 해당 사용자로 실행하려면 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 러너가 이를 실효 manifest에 자동으로 추가합니다.
+사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 할 때 manifest에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대면 샌드박스 도구가 해당 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 runner가 이를 실제 manifest에 추가합니다.
```python
from agents import Runner
@@ -333,13 +333,13 @@ result = await Runner.run(
)
```
-파일 수준 공유 규칙도 필요하다면, 사용자와 manifest 그룹 및 항목 `group` 메타데이터를 함께 사용하세요. `run_as` 사용자는 누가 샌드박스 네이티브 작업을 실행하는지 제어하고, `Permissions`는 샌드박스가 워크스페이스를 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지 제어합니다.
+파일 수준 공유 규칙도 필요하다면 사용자를 manifest 그룹 및 항목 `group` 메타데이터와 결합하세요. `run_as` 사용자는 누가 샌드박스 네이티브 작업을 실행하는지 제어하고, `Permissions`는 샌드박스가 워크스페이스를 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지 제어합니다.
### SnapshotSpec
-`SnapshotSpec`은 새로운 샌드박스 세션에 저장된 워크스페이스 콘텐츠를 어디서 복원하고 어디로 다시 저장할지 알려줍니다. 이는 샌드박스 워크스페이스의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
+`SnapshotSpec`은 새 샌드박스 세션이 저장된 워크스페이스 콘텐츠를 어디에서 복원하고 어디에 다시 저장해야 하는지 알려줍니다. 이는 샌드박스 워크스페이스의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
-로컬의 지속 스냅샷에는 `LocalSnapshotSpec`을 사용하고, 앱이 원격 스냅샷 클라이언트를 제공하는 경우에는 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 설정을 사용할 수 없으면 no-op 스냅샷이 대체로 사용되며, 고급 사용자는 워크스페이스 스냅샷 지속성이 필요 없을 때 이를 명시적으로 사용할 수 있습니다.
+로컬의 지속 가능한 스냅샷에는 `LocalSnapshotSpec`을 사용하고, 앱이 원격 스냅샷 클라이언트를 제공할 때는 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 no-op 스냅샷이 폴백으로 사용되며, 고급 호출자는 워크스페이스 스냅샷 지속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다.
```python
from pathlib import Path
@@ -356,13 +356,13 @@ run_config = RunConfig(
)
```
-러너가 새로운 샌드박스 세션을 만들면 샌드박스 클라이언트는 해당 세션을 위한 스냅샷 인스턴스를 생성합니다. 시작 시 스냅샷이 복원 가능하면, 샌드박스는 실행이 계속되기 전에 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 러너가 소유한 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 저장합니다.
+runner가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트가 해당 세션의 스냅샷 인스턴스를 만듭니다. 시작 시 스냅샷을 복원할 수 있으면, 실행이 계속되기 전에 샌드박스가 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 runner 소유 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 저장합니다.
-`snapshot`을 생략하면 런타임은 가능할 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 no-op 스냅샷으로 대체됩니다. 마운트된 경로와 임시 경로는 지속 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
+`snapshot`을 생략하면 런타임은 가능할 때 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 설정할 수 없으면 no-op 스냅샷으로 폴백합니다. 마운트된 경로와 임시 경로는 지속 가능한 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
-### 샌드박스 수명주기
+### 샌드박스 라이프사이클
-수명주기 모드는 두 가지입니다. **SDK 소유**와 **개발자 소유**입니다.
+두 가지 라이프사이클 모드가 있습니다. **SDK 소유**와 **개발자 소유**입니다.
@@ -390,7 +390,7 @@ sequenceDiagram
-샌드박스가 한 번의 실행 동안만 살아 있으면 SDK 소유 수명주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 러너가 샌드박스를 생성 또는 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 저장하고, 샌드박스를 종료하고, 클라이언트가 러너 소유 리소스를 정리하도록 합니다.
+샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 라이프사이클을 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 runner가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 저장하고, 샌드박스를 종료하며, 클라이언트가 runner 소유 리소스를 정리하도록 합니다.
```python
result = await Runner.run(
@@ -402,7 +402,7 @@ result = await Runner.run(
)
```
-샌드박스를 미리 생성하거나, 여러 실행에 걸쳐 하나의 실제 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에 대해 스트리밍하거나, 정리 시점을 정확히 제어하려면 개발자 소유 수명주기를 사용하세요. `session=...`을 전달하면 러너가 해당 실제 샌드박스를 사용하지만, 이를 대신 닫지는 않습니다.
+샌드박스를 미리 생성하거나, 여러 실행에서 하나의 라이브 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때 개발자 소유 라이프사이클을 사용하세요. `session=...`을 전달하면 runner는 해당 라이브 샌드박스를 사용하지만 대신 닫아 주지는 않습니다.
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -413,7 +413,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 수명주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명주기 메서드를 직접 호출하세요.
+컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 라이프사이클을 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 라이프사이클 메서드를 직접 호출하세요.
```python
sandbox = await client.create(
@@ -434,62 +434,62 @@ finally:
await sandbox.aclose()
```
-`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 저장하며, 샌드박스를 해제하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. pre-stop 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 의존성을 닫습니다.
+`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 저장합니다. 샌드박스를 해체하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. 중지 전 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
## `SandboxRunConfig` 옵션
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디서 오는지, 새 세션이 어떻게 초기화되어야 하는지를 결정하는 실행별 옵션을 담습니다.
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디에서 오는지, 새 세션을 어떻게 초기화할지 결정하는 실행별 옵션을 담습니다.
### 샌드박스 소스
-다음 옵션은 러너가 샌드박스 세션을 재사용, 재개, 생성할지 결정합니다.
+이 옵션들은 runner가 샌드박스 세션을 재사용, 재개 또는 생성해야 하는지 결정합니다.
| 옵션 | 사용 시점 | 참고 |
| --- | --- | --- |
-| `client` | 러너가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 실제 샌드박스 `session`을 제공하지 않는 한 필수입니다 |
-| `session` | 이미 실제 샌드박스 세션을 직접 만든 경우 | 수명주기는 호출자 소유이며, 러너는 해당 실제 샌드박스 세션을 재사용합니다 |
-| `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 실제 샌드박스 세션 객체는 없을 때 | `client`가 필요하며, 러너는 해당 명시적 상태에서 소유 세션으로 재개합니다 |
+| `client` | runner가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 라이브 샌드박스 `session`을 제공하지 않는 한 필수입니다. |
+| `session` | 라이브 샌드박스 세션을 이미 직접 생성했을 때 | 호출자가 라이프사이클을 소유합니다. runner는 해당 라이브 샌드박스 세션을 재사용합니다. |
+| `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 라이브 샌드박스 세션 객체는 없을 때 | `client`가 필요합니다. runner는 해당 명시적 상태에서 소유 세션으로 재개합니다. |
-실제로 러너는 다음 순서로 샌드박스 세션을 확인합니다.
+실제로 runner는 다음 순서로 샌드박스 세션을 해석합니다.
-1. `run_config.sandbox.session`을 주입하면 해당 실제 샌드박스 세션을 직접 재사용합니다
-2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우 저장된 샌드박스 세션 상태를 재개합니다
-3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면 러너는 해당 명시적 직렬화 샌드박스 세션 상태에서 재개합니다
-4. 그렇지 않으면 러너가 새로운 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를, 그렇지 않으면 `agent.default_manifest`를 사용합니다
+1. `run_config.sandbox.session`을 주입하면 해당 라이브 샌드박스 세션이 직접 재사용됩니다.
+2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우, 저장된 샌드박스 세션 상태가 재개됩니다.
+3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면, runner는 해당 명시적으로 직렬화된 샌드박스 세션 상태에서 재개합니다.
+4. 그렇지 않으면 runner가 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 그렇지 않으면 `agent.default_manifest`를 사용합니다.
### 새 세션 입력
-다음 옵션은 러너가 새로운 샌드박스 세션을 생성할 때만 중요합니다.
+이 옵션들은 runner가 새 샌드박스 세션을 생성할 때만 중요합니다.
| 옵션 | 사용 시점 | 참고 |
| --- | --- | --- |
-| `manifest` | 일회성 새 세션 워크스페이스 재정의가 필요할 때 | 생략 시 `agent.default_manifest`로 대체됩니다 |
-| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시드되어야 할 때 | 재개 유사 흐름이나 원격 스냅샷 클라이언트에 유용합니다 |
-| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 등 클라이언트별 설정에 흔히 사용됩니다 |
+| `manifest` | 일회성 새 세션 워크스페이스 재정의를 원할 때 | 생략하면 `agent.default_manifest`로 폴백합니다. |
+| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시작해야 할 때 | 재개와 유사한 흐름 또는 원격 스냅샷 클라이언트에 유용합니다. |
+| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 및 유사한 클라이언트별 설정에 일반적입니다. |
### 구체화 제어
-`concurrency_limits`는 얼마나 많은 샌드박스 구체화 작업을 병렬로 실행할 수 있는지 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
+`concurrency_limits`는 병렬로 실행할 수 있는 샌드박스 구체화 작업의 양을 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
-기억해 둘 만한 몇 가지 의미는 다음과 같습니다.
+유의할 몇 가지 영향은 다음과 같습니다.
-- 새로운 세션: `manifest=`와 `snapshot=`은 러너가 새로운 샌드박스 세션을 만들 때만 적용됩니다
-- 재개 vs 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 재연결하고, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새로운 샌드박스 세션을 시드합니다
-- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 다르며, Docker와 많은 호스티드 클라이언트는 이를 요구합니다
-- 주입된 실제 세션: 실행 중인 샌드박스 `session`을 전달하면 capability 기반 manifest 업데이트는 호환 가능한 비마운트 항목을 추가할 수 있습니다. 하지만 `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다
-- 러너 API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다
+- 새 세션: `manifest=`와 `snapshot=`은 runner가 새 샌드박스 세션을 생성할 때만 적용됩니다.
+- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 다시 연결하는 반면, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새 샌드박스 세션을 시작합니다.
+- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라집니다. Docker와 많은 호스티드 클라이언트에는 이것이 필요합니다.
+- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 manifest 업데이트가 호환되는 비마운트 항목을 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 바꾸거나, 마운트 항목을 추가 또는 변경할 수는 없습니다.
+- Runner API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다.
## 전체 예시: 코딩 작업
-이 코딩 스타일 예시는 시작점으로 적합한 기본 예시입니다.
+이 코딩 스타일 예시는 좋은 기본 시작점입니다.
```python
import asyncio
@@ -559,7 +559,7 @@ async def main(model: str, prompt: str) -> None:
if __name__ == "__main__":
asyncio.run(
main(
- model="gpt-5.4",
+ model="gpt-5.5",
prompt=(
"Open `repo/task.md`, use the `$credit-note-fixer` skill, fix the bug, "
f"run `{TARGET_TEST_CMD}`, and summarize the change."
@@ -568,19 +568,19 @@ if __name__ == "__main__":
)
```
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 예시를 Unix 로컬 실행 전반에서 결정론적으로 검증할 수 있도록 작은 셸 기반 리포지토리를 사용합니다. 물론 실제 작업 리포지토리는 Python, JavaScript, 또는 다른 어떤 것이어도 괜찮습니다.
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예시는 작은 셸 기반 저장소를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다. 실제 작업 저장소는 물론 Python, JavaScript 또는 무엇이든 될 수 있습니다.
-## 일반 패턴
+## 일반적인 패턴
-위의 전체 예시에서 시작하세요. 많은 경우 동일한 `SandboxAgent`는 그대로 유지하고, 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 워크스페이스 소스만 변경하면 됩니다.
+위의 전체 예시에서 시작하세요. 많은 경우 동일한 `SandboxAgent`는 그대로 두고 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 워크스페이스 소스만 변경할 수 있습니다.
### 샌드박스 클라이언트 전환
-에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리나 이미지 일치성이 필요하면 Docker를 사용하고, 제공업체 관리 실행이 필요하면 호스티드 제공업체를 사용하세요. 예시와 제공업체 옵션은 [Sandbox clients](clients.md)를 참고하세요.
+에이전트 정의를 그대로 유지하고 실행 구성만 변경하세요. 컨테이너 격리 또는 이미지 동등성이 필요하면 Docker를 사용하고, 제공자 관리 실행을 원하면 호스티드 제공자를 사용하세요. 예시와 제공자 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
### 워크스페이스 재정의
-에이전트 정의는 그대로 두고 새로운 세션 manifest만 교체하세요.
+에이전트 정의를 그대로 유지하고 새 세션 manifest만 교체하세요.
```python
from agents.run import RunConfig
@@ -600,11 +600,11 @@ run_config = RunConfig(
)
```
-동일한 에이전트 역할을 다른 리포지토리, 패킷, 또는 작업 번들에 대해 실행하되 에이전트를 다시 만들고 싶지 않을 때 사용하세요. 위의 검증된 코딩 예시는 일회성 재정의 대신 `default_manifest`로 같은 패턴을 보여줍니다.
+동일한 에이전트 역할을 에이전트를 다시 빌드하지 않고 서로 다른 저장소, 패킷, 작업 번들에 대해 실행해야 할 때 사용하세요. 위의 검증된 코딩 예시는 일회성 재정의 대신 `default_manifest`로 같은 패턴을 보여줍니다.
### 샌드박스 세션 주입
-명시적인 수명주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 실제 샌드박스 세션을 주입하세요.
+명시적 라이프사이클 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 라이브 샌드박스 세션을 주입하세요.
```python
from agents import Runner
@@ -625,11 +625,11 @@ async with sandbox:
)
```
-실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에 대해 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
+실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하려는 경우 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참조하세요.
### 세션 상태에서 재개
-이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면, 러너가 해당 상태에서 재연결하도록 하세요.
+이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면, runner가 해당 상태에서 다시 연결하도록 하세요.
```python
from agents.run import RunConfig
@@ -646,11 +646,11 @@ run_config = RunConfig(
)
```
-샌드박스 상태가 자체 스토리지나 작업 시스템에 있고, `Runner`가 그 상태에서 직접 재개하기를 원할 때 사용하세요. serialize/deserialize 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참고하세요.
+샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 여기서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참조하세요.
### 스냅샷에서 시작
-저장된 파일과 아티팩트에서 새로운 샌드박스를 시드하세요.
+저장된 파일과 아티팩트에서 새 샌드박스를 시작하세요.
```python
from pathlib import Path
@@ -667,11 +667,11 @@ run_config = RunConfig(
)
```
-새 실행이 `agent.default_manifest`만이 아니라 저장된 워크스페이스 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py), 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참고하세요.
+새 실행이 `agent.default_manifest`만이 아니라 저장된 워크스페이스 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를, 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참조하세요.
### Git에서 스킬 로드
-로컬 스킬 소스를 리포지토리 기반 소스로 교체하세요.
+로컬 스킬 소스를 저장소 기반 소스로 교체하세요.
```python
from agents.sandbox.capabilities import Capabilities, Skills
@@ -682,11 +682,11 @@ capabilities = Capabilities.default() + [
]
```
-스킬 번들이 자체 릴리스 주기를 가지거나 샌드박스 간 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참고하세요.
+스킬 번들에 자체 릴리스 주기가 있거나 샌드박스 전반에서 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참조하세요.
### 도구로 노출
-도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고, 부모 실행의 실제 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 구체화, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있기 때문입니다.
+도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 부모 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있습니다.
```python
from agents import Runner
@@ -768,7 +768,7 @@ async with sandbox:
)
```
-여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 동일한 실제 샌드박스 세션 내부에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기는 이를 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로 부모는 최종 아티팩트를 쓸 수 있고 탐색기는 읽기 전용으로 유지됩니다.
+여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색 도구 에이전트는 같은 라이브 샌드박스 세션 내부에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색자는 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 코디네이터의 사용자/그룹에만 제공되므로, 부모는 최종 아티팩트를 쓸 수 있고 탐색자는 읽기 전용으로 유지됩니다.
도구 에이전트에 실제 격리가 필요하다면 대신 자체 샌드박스 `RunConfig`를 제공하세요.
@@ -791,7 +791,7 @@ rollout_agent.as_tool(
)
```
-도구 에이전트가 자유롭게 변경해야 하거나, 신뢰할 수 없는 명령을 실행해야 하거나, 다른 백엔드/이미지를 사용해야 할 때는 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
+도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요.
### 로컬 도구 및 MCP와 결합
@@ -810,46 +810,46 @@ agent = SandboxAgent(
)
```
-워크스페이스 검사가 에이전트 작업의 일부에 불과할 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참고하세요.
+워크스페이스 검사가 에이전트 작업의 일부일 뿐일 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참조하세요.
## 메모리
-향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 한다면 `Memory` capability를 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와는 별개입니다. 샌드박스 워크스페이스 내부의 파일로 교훈을 추출하고, 이후 실행에서 해당 파일을 읽을 수 있습니다.
+향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 할 때 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 학습 내용을 샌드박스 워크스페이스 내부 파일로 추출하고, 이후 실행이 해당 파일을 읽을 수 있습니다.
-설정, 읽기/생성 동작, 다중 턴 대화, 레이아웃 격리는 [Agent memory](memory.md)를 참고하세요.
+설정, 읽기/생성 동작, 다중 턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참조하세요.
## 구성 패턴
-단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘지입니다.
+단일 에이전트 패턴이 명확해지면, 더 큰 시스템에서 샌드박스 경계를 어디에 둘지가 다음 설계 질문입니다.
-샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합할 수 있습니다.
+샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합됩니다.
-- [Handoffs](../handoffs.md): 샌드박스가 아닌 접수 에이전트에서 문서 중심 작업을 샌드박스 리뷰어로 넘깁니다
-- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 보통 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달해 각 도구가 자체 샌드박스 경계를 갖도록 합니다
-- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 capability는 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다
-- [Running agents](../running_agents.md): 샌드박스 실행도 여전히 일반 `Runner` API를 사용합니다
+- [핸드오프](../handoffs.md): 문서가 많은 작업을 비샌드박스 접수 에이전트에서 샌드박스 리뷰어로 핸드오프합니다.
+- [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달하여 각 도구가 자체 샌드박스 경계를 갖도록 합니다.
+- [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다.
+- [에이전트 실행](../running_agents.md): 샌드박스 실행은 여전히 일반 `Runner` API를 사용합니다.
-특히 흔한 패턴은 두 가지입니다.
+특히 흔한 두 가지 패턴은 다음과 같습니다.
-- 샌드박스가 아닌 에이전트가 워크스페이스 격리가 필요한 워크플로의 일부에 대해서만 샌드박스 에이전트로 핸드오프하는 패턴
-- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하는 패턴. 보통 각 `Agent.as_tool(...)` 호출에 별도의 샌드박스 `RunConfig`를 두어 각 도구가 자체 격리 워크스페이스를 갖게 합니다
+- 워크스페이스 격리가 필요한 워크플로 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프
+- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출. 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용하여 각 도구가 자체 격리 워크스페이스를 갖도록 함
### 턴과 샌드박스 실행
핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다.
-핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 샌드박스가 아닌 접수 에이전트가 샌드박스 리뷰어로 핸드오프하면, 같은 실행 안의 다음 모델 호출은 샌드박스 에이전트용으로 준비되고, 그 샌드박스 에이전트가 다음 턴을 맡게 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 어떤 에이전트가 담당할지만 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참고하세요.
+핸드오프의 경우, 여전히 하나의 최상위 실행과 하나의 최상위 turn 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 리뷰어에게 핸드오프하면, 같은 실행의 다음 모델 호출은 샌드박스 에이전트용으로 준비되며 해당 샌드박스 에이전트가 다음 turn을 수행하는 에이전트가 됩니다. 즉, 핸드오프는 같은 실행의 다음 turn을 어느 에이전트가 소유하는지 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참조하세요.
-`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 하나의 외부 턴을 사용해 도구 호출을 결정하고, 그 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행은 자체 턴 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`를 가집니다. 한 번의 중첩 턴으로 끝날 수도 있고 여러 턴이 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 턴은 외부 실행의 턴 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
+`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구 호출을 결정하는 데 하나의 외부 turn을 사용하고, 해당 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행에는 자체 turn 루프, `max_turns`, 승인, 그리고 일반적으로 자체 샌드박스 `RunConfig`가 있습니다. 한 번의 중첩 turn으로 끝날 수도 있고 여러 번 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 turn은 외부 실행의 turn 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요.
-승인 동작도 같은 방식으로 나뉩니다.
+승인 동작도 같은 구분을 따릅니다.
-- 핸드오프에서는 샌드박스 에이전트가 같은 실행의 활성 에이전트가 되므로 승인이 동일한 최상위 실행에 유지됩니다
-- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 여전히 외부 실행에 표시되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다
+- 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인은 같은 최상위 실행에 유지됩니다.
+- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 표면화되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다.
## 추가 자료
-- [Quickstart](quickstart.md): 샌드박스 에이전트 하나를 실행해 보기
-- [Sandbox clients](clients.md): 로컬, Docker, 호스티드, 마운트 옵션 선택
-- [Agent memory](memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용하기
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 조합 패턴
\ No newline at end of file
+- [빠른 시작](quickstart.md): 샌드박스 에이전트 하나를 실행합니다.
+- [샌드박스 클라이언트](clients.md): 로컬, Docker, 호스티드, 마운트 옵션을 선택합니다.
+- [에이전트 메모리](memory.md): 이전 샌드박스 실행의 학습 내용을 보존하고 재사용합니다.
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 실행 가능한 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴.
\ No newline at end of file
diff --git a/docs/ko/sandbox_agents.md b/docs/ko/sandbox_agents.md
index 2382de1bfa..79875c221f 100644
--- a/docs/ko/sandbox_agents.md
+++ b/docs/ko/sandbox_agents.md
@@ -6,21 +6,21 @@ search:
!!! warning "베타 기능"
- 샌드박스 에이전트는 베타입니다. 정식 출시 전에 API 의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+ 샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다.
-현대적인 에이전트는 파일시스템의 실제 파일에서 작업할 수 있을 때 가장 잘 동작합니다. Agents SDK 의 **Sandbox Agents** 는 모델에 지속적인 작업 공간을 제공하여, 대규모 문서 집합을 검색하고, 파일을 편집하고, 명령을 실행하고, 아티팩트를 생성하고, 저장된 샌드박스 상태에서 작업을 다시 이어갈 수 있게 합니다.
+최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. Agents SDK의 **샌드박스 에이전트**는 모델에 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 저장된 샌드박스 상태에서 작업 재개를 수행할 수 있는 지속적인 워크스페이스를 제공합니다.
-SDK 는 파일 스테이징, 파일시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 공급자별 연결 코드를 직접 조합하지 않아도 되는 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름은 그대로 유지하면서, 작업 공간용 `Manifest`, 샌드박스 네이티브 도구를 위한 capabilities, 그리고 작업 실행 위치를 지정하는 `SandboxRunConfig` 를 추가하면 됩니다.
+SDK는 파일 스테이징, 파일 시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 제공자별 글루 코드를 직접 연결하지 않아도 이러한 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지한 다음, 워크스페이스용 `Manifest`, 샌드박스 네이티브 도구용 기능, 작업이 실행될 위치를 위한 `SandboxRunConfig`를 추가하면 됩니다.
-## 사전 준비
+## 사전 요구 사항
- Python 3.10 이상
-- OpenAI Agents SDK 에 대한 기본적인 이해
-- 샌드박스 클라이언트. 로컬 개발에는 `UnixLocalSandboxClient` 로 시작하세요.
+- OpenAI Agents SDK에 대한 기본 이해
+- 샌드박스 클라이언트. 로컬 개발의 경우 `UnixLocalSandboxClient`로 시작하세요.
## 설치
-아직 SDK 를 설치하지 않았다면:
+아직 SDK를 설치하지 않았다면:
```bash
pip install openai-agents
@@ -34,7 +34,7 @@ pip install "openai-agents[docker]"
## 로컬 샌드박스 에이전트 생성
-이 예제는 로컬 리포지토리를 `repo/` 아래에 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위해 Unix 로컬 샌드박스 세션을 생성하도록 합니다.
+이 예제는 `repo/` 아래에 로컬 저장소를 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위한 Unix 로컬 샌드박스 세션을 만들도록 합니다.
```python
import asyncio
@@ -80,7 +80,7 @@ def build_agent(model: str) -> SandboxAgent[None]:
async def main() -> None:
result = await Runner.run(
- build_agent("gpt-5.4"),
+ build_agent("gpt-5.5"),
"Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.",
run_config=RunConfig(
sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
@@ -94,24 +94,24 @@ if __name__ == "__main__":
asyncio.run(main())
```
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 리포지토리를 사용하므로, Unix 로컬 실행 전반에서 예제를 결정적으로 검증할 수 있습니다.
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 저장소를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다.
## 주요 선택 사항
-기본 실행이 동작하기 시작하면, 대부분의 사용자가 다음으로 고려하는 선택지는 다음과 같습니다:
+기본 실행이 작동한 뒤 대부분의 사람이 다음으로 고려하는 선택 사항은 다음과 같습니다.
-- `default_manifest`: 새 샌드박스 세션을 위한 파일, 리포지토리, 디렉터리 및 마운트
+- `default_manifest`: 새 샌드박스 세션을 위한 파일, 저장소, 디렉터리, 마운트
- `instructions`: 프롬프트 전반에 적용되어야 하는 짧은 워크플로 규칙
- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 이스케이프 해치
-- `capabilities`: 파일시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축(compaction)과 같은 샌드박스 네이티브 도구
-- `run_as`: 모델 대면 도구에 대한 샌드박스 사용자 ID
+- `capabilities`: 파일 시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축과 같은 샌드박스 네이티브 도구
+- `run_as`: 모델이 사용하는 도구의 샌드박스 사용자 ID
- `SandboxRunConfig.client`: 샌드박스 백엔드
-- `SandboxRunConfig.session`, `session_state`, 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결되는 방식
+- `SandboxRunConfig.session`, `session_state` 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결하는 방식
## 다음 단계
-- [개념](sandbox/guide.md): 매니페스트, capabilities, 권한, 스냅샷, 실행 구성, 조합 패턴을 이해합니다
-- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 공급자, 마운트 전략 중에서 선택합니다
-- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행의 교훈을 보존하고 재사용합니다
+- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 구성 패턴을 이해합니다.
+- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 제공자, 마운트 전략을 선택합니다.
+- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행에서 얻은 교훈을 보존하고 재사용합니다.
-셸 접근이 가끔 사용하는 도구 중 하나일 뿐이라면, [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
\ No newline at end of file
+셸 접근이 가끔 사용하는 도구 중 하나에 불과하다면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
\ No newline at end of file
diff --git a/docs/ko/streaming.md b/docs/ko/streaming.md
index ef140fbdd1..5ed07259df 100644
--- a/docs/ko/streaming.md
+++ b/docs/ko/streaming.md
@@ -4,19 +4,19 @@ search:
---
# 스트리밍
-스트리밍을 사용하면 에이전트 실행이 진행되는 동안 업데이트를 구독할 수 있습니다. 이는 최종 사용자에게 진행 상황 업데이트와 부분 응답을 보여주는 데 유용합니다
+스트리밍을 사용하면 에이전트 실행이 진행되는 동안 업데이트를 구독할 수 있습니다. 이는 최종 사용자에게 진행 상황 업데이트와 부분 응답을 보여줄 때 유용할 수 있습니다.
-스트리밍하려면 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 호출하면 되며, 그러면 [`RunResultStreaming`][agents.result.RunResultStreaming]이 반환됩니다. `result.stream_events()`를 호출하면 아래에서 설명하는 [`StreamEvent`][agents.stream_events.StreamEvent] 객체의 비동기 스트림을 받을 수 있습니다
+스트리밍하려면 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 호출하면 되며, 그러면 [`RunResultStreaming`][agents.result.RunResultStreaming]을 받습니다. `result.stream_events()`를 호출하면 아래에 설명된 [`StreamEvent`][agents.stream_events.StreamEvent] 객체의 비동기 스트림을 얻을 수 있습니다.
-비동기 이터레이터가 끝날 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 종료될 때까지 완료되지 않으며, 세션 영속성, 승인 기록 관리, 히스토리 압축 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 완료될 수 있습니다. 루프가 종료되면 `result.is_complete`에 최종 실행 상태가 반영됩니다
+비동기 이터레이터가 끝날 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 종료될 때까지 완료된 것이 아니며, 세션 영속화, 승인 장부 처리, 히스토리 압축 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 끝날 수 있습니다. 루프가 종료되면 `result.is_complete`가 최종 실행 상태를 반영합니다.
## 원시 응답 이벤트
-[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원시 이벤트입니다. OpenAI Responses API 형식이므로, 각 이벤트에는 타입(`response.created`, `response.output_text.delta` 등)과 데이터가 있습니다. 이 이벤트는 생성되는 즉시 응답 메시지를 사용자에게 스트리밍하고 싶을 때 유용합니다
+[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원시 이벤트입니다. OpenAI Responses API 형식이므로 각 이벤트에는 타입(예: `response.created`, `response.output_text.delta` 등)과 데이터가 있습니다. 이러한 이벤트는 생성되는 즉시 사용자에게 응답 메시지를 스트리밍하려는 경우에 유용합니다.
-컴퓨터 도구 원시 이벤트는 저장된 결과와 동일하게 preview 대 GA 구분을 유지합니다. Preview 흐름은 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하고, `gpt-5.4`는 배치된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 상위 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면에서는 이를 위한 컴퓨터 전용 특별 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 표면화되며, 스크린샷 결과는 `computer_call_output` 항목을 감싼 `tool_output`으로 반환됩니다
+컴퓨터 도구 원시 이벤트는 저장된 결과와 동일한 프리뷰-vs-GA 구분을 유지합니다. 프리뷰 플로는 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하는 반면, `gpt-5.5`는 일괄 처리된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 더 높은 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면은 이를 위해 컴퓨터 전용 특별 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 노출되며, 스크린샷 결과는 `computer_call_output` 항목을 감싼 `tool_output`으로 반환됩니다.
-예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다
+예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다.
```python
import asyncio
@@ -41,7 +41,7 @@ if __name__ == "__main__":
## 스트리밍과 승인
-스트리밍은 도구 승인을 위해 일시 중지되는 실행과도 호환됩니다. 도구에 승인이 필요하면 `result.stream_events()`가 종료되고, 대기 중인 승인 항목은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`로 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인 또는 거부한 뒤 `Runner.run_streamed(...)`로 재개하세요
+스트리밍은 도구 승인을 위해 일시 중지되는 실행과 호환됩니다. 도구에 승인이 필요한 경우 `result.stream_events()`가 종료되고 보류 중인 승인은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`로 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인하거나 거부한 다음 `Runner.run_streamed(...)`로 재개하세요.
```python
result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.")
@@ -57,43 +57,43 @@ if result.interruptions:
pass
```
-전체 일시 중지/재개 흐름은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참고하세요
+전체 일시 중지/재개 절차는 [휴먼인더루프 가이드](human_in_the_loop.md)를 참조하세요.
## 현재 턴 이후 스트리밍 취소
-중간에 스트리밍 실행을 중지해야 한다면 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로는 즉시 실행을 중지합니다. 중지 전에 현재 턴을 깔끔하게 마무리하려면 대신 `result.cancel(mode="after_turn")`를 호출하세요
+스트리밍 실행을 중간에 중지해야 하는 경우 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로 이는 실행을 즉시 중지합니다. 중지하기 전에 현재 턴이 깔끔하게 완료되도록 하려면 대신 `result.cancel(mode="after_turn")`을 호출하세요.
-스트리밍 실행은 `result.stream_events()`가 끝날 때까지 완료되지 않습니다. SDK는 마지막으로 보이는 토큰 이후에도 세션 항목 영속화, 승인 상태 마무리, 히스토리 압축을 계속 수행할 수 있습니다
+스트리밍된 실행은 `result.stream_events()`가 끝날 때까지 완료되지 않습니다. 마지막으로 보이는 토큰 이후에도 SDK가 세션 항목을 영속화하거나, 승인 상태를 마무리하거나, 히스토리를 압축하고 있을 수 있습니다.
-[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 이어서 진행하는 경우, `cancel(mode="after_turn")`가 도구 턴 이후 중지되었다면 새로운 사용자 턴을 바로 추가하지 말고 해당 정규화 입력으로 `result.last_agent`를 다시 실행해 미완료 턴을 이어가세요
-- 스트리밍 실행이 도구 승인 때문에 중지되었다면 이를 새 턴으로 처리하지 마세요. 스트림 소비를 끝까지 완료하고 `result.interruptions`를 확인한 뒤 `result.to_state()`에서 재개하세요
-- 다음 모델 호출 전에 조회된 세션 히스토리와 새 사용자 입력을 어떻게 병합할지 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 그곳에서 새 턴 항목을 다시 작성하면, 해당 턴에는 다시 작성된 버전이 영속화됩니다
+[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 계속 진행하고 있으며 `cancel(mode="after_turn")`이 도구 턴 이후 중지되는 경우, 즉시 새 사용자 턴을 추가하는 대신 해당 정규화된 입력으로 `result.last_agent`를 다시 실행하여 완료되지 않은 턴을 계속하세요.
+- 스트리밍 실행이 도구 승인 때문에 중지된 경우, 이를 새 턴으로 취급하지 마세요. 스트림을 끝까지 소진하고 `result.interruptions`를 검사한 다음 `result.to_state()`에서 재개하세요.
+- 다음 모델 호출 전에 가져온 세션 히스토리와 새 사용자 입력을 병합하는 방식을 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 그곳에서 새 턴 항목을 다시 작성하면, 다시 작성된 버전이 해당 턴에 대해 영속화됩니다.
-## 실행 항목 이벤트와 에이전트 이벤트
+## 실행 항목 이벤트 및 에이전트 이벤트
-[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 상위 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰이 아니라 "메시지 생성됨", "도구 실행됨" 수준으로 진행 업데이트를 푸시할 수 있습니다. 마찬가지로, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프로 인한 경우) 업데이트를 제공합니다
+[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰이 아니라 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황 업데이트를 푸시할 수 있습니다. 마찬가지로 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과) 업데이트를 제공합니다.
### 실행 항목 이벤트 이름
-`RunItemStreamEvent.name`은 고정된 의미론적 이벤트 이름 집합을 사용합니다
+`RunItemStreamEvent.name`은 고정된 의미론적 이벤트 이름 집합을 사용합니다.
-- `message_output_created`
-- `handoff_requested`
-- `handoff_occured`
-- `tool_called`
-- `tool_search_called`
-- `tool_search_output_created`
-- `tool_output`
-- `reasoning_item_created`
-- `mcp_approval_requested`
-- `mcp_approval_response`
-- `mcp_list_tools`
+- `message_output_created`
+- `handoff_requested`
+- `handoff_occured`
+- `tool_called`
+- `tool_search_called`
+- `tool_search_output_created`
+- `tool_output`
+- `reasoning_item_created`
+- `mcp_approval_requested`
+- `mcp_approval_response`
+- `mcp_list_tools`
-`handoff_occured`는 하위 호환성을 위해 의도적으로 철자가 잘못되어 있습니다
+`handoff_occured`는 하위 호환성을 위해 의도적으로 철자가 잘못되어 있습니다.
-호스티드 툴 검색을 사용할 때, 모델이 도구 검색 요청을 발행하면 `tool_search_called`이 발생하고 Responses API가 로드된 하위 집합을 반환하면 `tool_search_output_created`이 발생합니다
+호스티드 툴 검색을 사용할 때는 모델이 도구 검색 요청을 발행하면 `tool_search_called`가 내보내지고, Responses API가 로드된 하위 집합을 반환하면 `tool_search_output_created`가 내보내집니다.
-예를 들어, 다음은 원시 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다
+예를 들어, 다음은 원시 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다.
```python
import asyncio
diff --git a/docs/ko/tools.md b/docs/ko/tools.md
index 10748a768a..41ff1af3fb 100644
--- a/docs/ko/tools.md
+++ b/docs/ko/tools.md
@@ -4,42 +4,42 @@ search:
---
# 도구
-도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용과 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다:
+도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용과 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다.
-- OpenAI 호스티드 도구: OpenAI 서버에서 모델과 함께 실행됩니다
-- 로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다
-- 함수 호출: 임의의 Python 함수를 도구로 래핑합니다
-- Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다
-- 실험적 기능: Codex 도구: 도구 호출에서 워크스페이스 범위의 Codex 작업을 실행합니다
+- 호스티드 OpenAI 도구: OpenAI 서버에서 모델과 함께 실행됩니다.
+- 로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다.
+- Function Calling: 모든 Python 함수를 도구로 래핑합니다.
+- Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다.
+- 실험적: Codex 도구: 도구 호출에서 워크스페이스 범위의 Codex 작업을 실행합니다.
## 도구 유형 선택
이 페이지를 카탈로그로 사용한 다음, 제어하는 런타임에 맞는 섹션으로 이동하세요.
-| 원하시는 작업 | 시작 위치 |
+| 원하는 작업 | 시작 위치 |
| --- | --- |
-| OpenAI 관리형 도구 사용(web search, file search, code interpreter, hosted MCP, image generation) | [호스티드 도구](#hosted-tools) |
-| tool search로 런타임까지 대규모 도구 표면 지연 | [호스티드 도구 검색](#hosted-tool-search) |
+| OpenAI가 관리하는 도구 사용(웹 검색, 파일 검색, code interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 도구](#hosted-tools) |
+| 도구 검색으로 큰 도구 표면을 런타임까지 지연 | [호스티드 도구 검색](#hosted-tool-search) |
| 자체 프로세스 또는 환경에서 도구 실행 | [로컬 런타임 도구](#local-runtime-tools) |
| Python 함수를 도구로 래핑 | [함수 도구](#function-tools) |
-| 핸드오프 없이 한 에이전트가 다른 에이전트를 호출 | [Agents as tools](#agents-as-tools) |
-| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적 기능: Codex 도구](#experimental-codex-tool) |
+| 한 에이전트가 핸드오프 없이 다른 에이전트를 호출하도록 허용 | [Agents as tools](#agents-as-tools) |
+| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적: Codex 도구](#experimental-codex-tool) |
## 호스티드 도구
-OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 사용 시 몇 가지 내장 도구를 제공합니다:
+OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]을 사용할 때 몇 가지 기본 제공 도구를 제공합니다.
-- [`WebSearchTool`][agents.tool.WebSearchTool]은 에이전트가 웹을 검색할 수 있게 합니다
-- [`FileSearchTool`][agents.tool.FileSearchTool]은 OpenAI 벡터 스토어에서 정보를 검색할 수 있게 합니다
-- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]은 LLM이 샌드박스 환경에서 코드를 실행할 수 있게 합니다
-- [`HostedMCPTool`][agents.tool.HostedMCPTool]은 원격 MCP 서버의 도구를 모델에 노출합니다
-- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]은 프롬프트로부터 이미지를 생성합니다
-- [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 지연된 도구, 네임스페이스 또는 호스티드 MCP 서버를 필요 시 로드할 수 있게 합니다
+- [`WebSearchTool`][agents.tool.WebSearchTool]을 사용하면 에이전트가 웹을 검색할 수 있습니다.
+- [`FileSearchTool`][agents.tool.FileSearchTool]은 OpenAI 벡터 스토어에서 정보를 검색할 수 있게 합니다.
+- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]은 LLM이 샌드박스 환경에서 코드를 실행할 수 있게 합니다.
+- [`HostedMCPTool`][agents.tool.HostedMCPTool]은 원격 MCP 서버의 도구를 모델에 노출합니다.
+- [`ImageGenerationTool`][agents.tool.ImageGenerationTool]은 프롬프트에서 이미지를 생성합니다.
+- [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 필요할 때 지연된 도구, 네임스페이스 또는 호스티드 MCP 서버를 로드할 수 있게 합니다.
고급 호스티드 검색 옵션:
-- `FileSearchTool`은 `vector_store_ids` 및 `max_num_results` 외에 `filters`, `ranking_options`, `include_search_results`를 지원합니다
-- `WebSearchTool`은 `filters`, `user_location`, `search_context_size`를 지원합니다
+- `FileSearchTool`은 `vector_store_ids` 및 `max_num_results` 외에도 `filters`, `ranking_options`, `include_search_results`를 지원합니다.
+- `WebSearchTool`은 `filters`, `user_location`, `search_context_size`를 지원합니다.
```python
from agents import Agent, FileSearchTool, Runner, WebSearchTool
@@ -62,9 +62,9 @@ async def main():
### 호스티드 도구 검색
-도구 검색을 사용하면 OpenAI Responses 모델이 대규모 도구 표면을 런타임까지 지연할 수 있어, 현재 턴에 필요한 하위 집합만 모델이 로드합니다. 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 미리 노출하지 않으면서 도구 스키마 토큰을 줄이고 싶을 때 유용합니다.
+도구 검색을 사용하면 OpenAI Responses 모델이 큰 도구 표면을 런타임까지 지연시켜, 모델이 현재 턴에 필요한 하위 집합만 로드할 수 있습니다. 이는 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 미리 노출하지 않으면서 도구 스키마 토큰을 줄이고 싶을 때 유용합니다.
-후보 도구를 에이전트 구축 시점에 이미 알고 있다면 호스티드 도구 검색으로 시작하세요. 애플리케이션에서 동적으로 로드 대상을 결정해야 한다면 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동 실행하지 않습니다.
+후보 도구를 에이전트를 빌드할 때 이미 알고 있다면 호스티드 도구 검색부터 시작하세요. 애플리케이션이 무엇을 로드할지 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동 실행하지 않습니다.
```python
from typing import Annotated
@@ -97,7 +97,7 @@ crm_tools = tool_namespace(
agent = Agent(
name="Operations assistant",
- model="gpt-5.4",
+ model="gpt-5.5",
instructions="Load the crm namespace before using CRM tools.",
tools=[*crm_tools, ToolSearchTool()],
)
@@ -106,21 +106,21 @@ result = await Runner.run(agent, "Look up customer_42 and list their open orders
print(result.final_output)
```
-알아둘 점:
-
-- 호스티드 도구 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다
-- 에이전트에 지연 로드 표면을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요
-- 검색 가능한 표면에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다
-- 지연 로드 함수 도구는 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스 전용 구성도 모델이 필요 시 올바른 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다
-- `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름 및 설명 아래로 그룹화합니다. `crm`, `billing`, `shipping`처럼 관련 도구가 많을 때 일반적으로 가장 적합합니다
-- OpenAI의 공식 모범 사례 가이드는 [가능하면 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다
-- 가능하면 개별 지연 함수 다수보다 네임스페이스 또는 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 고수준 검색 표면과 더 나은 토큰 절감을 제공합니다
-- 네임스페이스는 즉시 도구와 지연 도구를 혼합할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능하며, 같은 네임스페이스의 지연 도구는 도구 검색을 통해 로드됩니다
-- 경험칙으로 각 네임스페이스는 비교적 작게 유지하고, 이상적으로 함수 10개 미만으로 유지하세요
-- 이름 지정된 `tool_choice`는 순수 네임스페이스 이름이나 지연 전용 도구를 대상으로 할 수 없습니다. `auto`, `required`, 또는 실제 최상위 호출 가능 도구 이름을 선호하세요
-- `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 대신 실행하지 않고 예외를 발생시킵니다
-- 도구 검색 활동은 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에서 전용 항목 및 이벤트 유형으로 표시됩니다
-- 네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 전체 실행 가능 예제는 `examples/tools/tool_search.py`를 참조하세요
+알아둘 사항:
+
+- 호스티드 도구 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다.
+- 에이전트에서 지연 로딩 표면을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요.
+- 검색 가능한 표면에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다.
+- 지연 로딩 함수 도구는 반드시 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스만 사용하는 구성에서도 모델이 필요할 때 적절한 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다.
+- `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름과 설명 아래에 그룹화합니다. 이는 보통 `crm`, `billing`, `shipping`처럼 관련 도구가 많을 때 가장 적합합니다.
+- OpenAI의 공식 모범 사례 가이드는 [가능한 경우 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다.
+- 가능하면 개별적으로 지연된 많은 함수보다 네임스페이스나 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 상위 수준 검색 표면과 더 나은 토큰 절감을 제공합니다.
+- 네임스페이스는 즉시 사용 가능한 도구와 지연된 도구를 함께 포함할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능한 상태로 유지되며, 같은 네임스페이스의 지연된 도구는 도구 검색을 통해 로드됩니다.
+- 경험상 각 네임스페이스는 비교적 작게 유지하되, 이상적으로는 함수 10개 미만으로 유지하세요.
+- 이름이 지정된 `tool_choice`는 단독 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없습니다. `auto`, `required` 또는 실제 최상위 호출 가능 도구 이름을 선호하세요.
+- `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 이를 실행하는 대신 예외를 발생시킵니다.
+- 도구 검색 활동은 전용 항목 및 이벤트 유형과 함께 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에 나타납니다.
+- 네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 완전한 실행 가능 예제는 `examples/tools/tool_search.py`를 참조하세요.
- 공식 플랫폼 가이드: [도구 검색](https://developers.openai.com/api/docs/guides/tools-tool-search)
### 호스티드 컨테이너 셸 + 스킬
@@ -138,7 +138,7 @@ csv_skill: ShellToolSkillReference = {
agent = Agent(
name="Container shell agent",
- model="gpt-5.4",
+ model="gpt-5.5",
instructions="Use the mounted skill when helpful.",
tools=[
ShellTool(
@@ -158,52 +158,52 @@ result = await Runner.run(
print(result.final_output)
```
-나중 실행에서 기존 컨테이너를 재사용하려면 `environment={"type": "container_reference", "container_id": "cntr_..."}`를 설정하세요.
+이후 실행에서 기존 컨테이너를 재사용하려면 `environment={"type": "container_reference", "container_id": "cntr_..."}`를 설정하세요.
-알아둘 점:
+알아둘 사항:
-- 호스티드 셸은 Responses API shell 도구를 통해 사용할 수 있습니다
-- `container_auto`는 요청용 컨테이너를 프로비저닝하며, `container_reference`는 기존 컨테이너를 재사용합니다
-- `container_auto`에는 `file_ids`와 `memory_limit`도 포함할 수 있습니다
-- `environment.skills`는 스킬 참조와 인라인 스킬 번들을 허용합니다
-- 호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval`, `on_approval`를 설정하지 마세요
-- `network_policy`는 `disabled` 및 `allowlist` 모드를 지원합니다
-- allowlist 모드에서 `network_policy.domain_secrets`는 이름으로 도메인 범위 시크릿을 주입할 수 있습니다
-- 전체 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요
+- 호스티드 셸은 Responses API 셸 도구를 통해 사용할 수 있습니다.
+- `container_auto`는 요청에 대한 컨테이너를 프로비저닝하며, `container_reference`는 기존 컨테이너를 재사용합니다.
+- `container_auto`는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다.
+- `environment.skills`는 스킬 참조와 인라인 스킬 번들을 허용합니다.
+- 호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval` 또는 `on_approval`을 설정하지 마세요.
+- `network_policy`는 `disabled` 및 `allowlist` 모드를 지원합니다.
+- 허용 목록 모드에서 `network_policy.domain_secrets`는 이름으로 도메인 범위의 시크릿을 주입할 수 있습니다.
+- 완전한 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요.
- OpenAI 플랫폼 가이드: [Shell](https://platform.openai.com/docs/guides/tools-shell) 및 [Skills](https://platform.openai.com/docs/guides/tools-skills)
## 로컬 런타임 도구
-로컬 런타임 도구는 모델 응답 자체 외부에서 실행됩니다. 모델이 호출 시점을 결정하지만 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다.
+로컬 런타임 도구는 모델 응답 자체 외부에서 실행됩니다. 모델은 여전히 언제 호출할지 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다.
-`ComputerTool` 및 `ApplyPatchTool`은 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 지원합니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을, 자체 프로세스에서 명령 실행을 원하면 아래 로컬 런타임 구성을 사용하세요.
+`ComputerTool` 및 `ApplyPatchTool`에는 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 포괄합니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을 사용하고, 명령이 자체 프로세스에서 실행되기를 원하면 아래 로컬 런타임 구성을 사용하세요.
-로컬 런타임 도구는 구현 제공이 필요합니다:
+로컬 런타임 도구에는 구현을 제공해야 합니다.
-- [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 활성화하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현합니다
-- [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행 모두를 위한 최신 shell 도구
-- [`LocalShellTool`][agents.tool.LocalShellTool]: 레거시 로컬 shell 통합
-- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: diff를 로컬에 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현합니다
-- 로컬 shell 스킬은 `ShellTool(environment={"type": "local", "skills": [...]})`로 사용할 수 있습니다
+- [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 활성화하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현하세요.
+- [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행 모두를 위한 최신 셸 도구입니다.
+- [`LocalShellTool`][agents.tool.LocalShellTool]: 레거시 로컬 셸 통합입니다.
+- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: 로컬에서 diff를 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요.
+- 로컬 셸 스킬은 `ShellTool(environment={"type": "local", "skills": [...]})`와 함께 사용할 수 있습니다.
-### ComputerTool 및 Responses computer 도구
+### ComputerTool 및 Responses 컴퓨터 도구
-`ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면 SDK가 해당 하네스를 OpenAI Responses API computer 표면에 매핑합니다.
+`ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면, SDK가 해당 하네스를 OpenAI Responses API 컴퓨터 표면에 매핑합니다.
-명시적 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 요청의 경우 SDK는 GA 내장 도구 페이로드 `{"type": "computer"}`를 전송합니다. 이전 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [Computer use 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다:
+명시적 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA 기본 제공 도구 페이로드 `{"type": "computer"}`를 보냅니다. 더 오래된 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다.
-- 모델: `computer-use-preview` -> `gpt-5.4`
-- 도구 선택자: `computer_use_preview` -> `computer`
-- 컴퓨터 호출 형태: `computer_call`당 단일 `action` -> `computer_call`의 배치 `actions[]`
-- 잘림: 프리뷰 경로에서 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 필요 없음
+- 모델: `computer-use-preview` -> `gpt-5.5`
+- 도구 선택기: `computer_use_preview` -> `computer`
+- 컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 일괄 처리된 `actions[]`
+- 잘림: 프리뷰 경로에서는 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 필요하지 않음
-SDK는 실제 Responses 요청의 유효 모델에서 해당 wire 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 `model`을 소유해 요청에 `model`이 생략된 경우, SDK는 `model="gpt-5.4"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하지 않는 한 프리뷰 호환 computer 페이로드를 유지합니다.
+SDK는 실제 Responses 요청의 유효 모델에서 해당 wire 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하고 있어 요청에서 `model`을 생략하는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다.
-[`ComputerTool`][agents.tool.ComputerTool]이 있을 때 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 모두 허용되며 유효 요청 모델에 맞는 내장 선택자로 정규화됩니다. `ComputerTool`이 없으면 해당 문자열은 일반 함수 이름처럼 동작합니다.
+[`ComputerTool`][agents.tool.ComputerTool]이 있을 때는 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. `ComputerTool`이 없으면 이 문자열들은 여전히 일반 함수 이름처럼 동작합니다.
-이 구분은 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 통해 백업될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment`나 dimensions가 필요 없으므로 미해결 팩토리도 괜찮습니다. 프리뷰 호환 직렬화는 SDK가 `environment`, `display_width`, `display_height`를 전송할 수 있도록 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 여전히 필요합니다.
+이 차이는 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리로 뒷받침될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기가 필요하지 않으므로, 해결되지 않은 팩토리도 괜찮습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 보낼 수 있도록 여전히 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 필요합니다.
-런타임에서는 두 경로 모두 동일한 로컬 하네스를 사용합니다. 프리뷰 응답은 단일 `action`이 있는 `computer_call` 항목을 내보내고, `gpt-5.4`는 배치 `actions[]`를 내보낼 수 있으며 SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요.
+런타임에는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 있는 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 일괄 처리된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요.
```python
from agents import Agent, ApplyPatchTool, ShellTool
@@ -247,16 +247,16 @@ agent = Agent(
## 함수 도구
-임의의 Python 함수를 도구로 사용할 수 있습니다. Agents SDK가 도구를 자동으로 설정합니다:
+모든 Python 함수를 도구로 사용할 수 있습니다. Agents SDK가 도구를 자동으로 설정합니다.
-- 도구 이름은 Python 함수 이름이 됩니다(또는 이름을 제공할 수 있음)
-- 도구 설명은 함수의 docstring에서 가져옵니다(또는 설명을 제공할 수 있음)
-- 함수 입력용 스키마는 함수 인수에서 자동 생성됩니다
-- 각 입력 설명은 비활성화하지 않는 한 함수의 docstring에서 가져옵니다
+- 도구 이름은 Python 함수의 이름이 됩니다(또는 이름을 제공할 수 있습니다)
+- 도구 설명은 함수의 docstring에서 가져옵니다(또는 설명을 제공할 수 있습니다)
+- 함수 입력의 스키마는 함수의 인수에서 자동으로 생성됩니다
+- 비활성화하지 않는 한 각 입력에 대한 설명은 함수의 docstring에서 가져옵니다
-함수 시그니처 추출에는 Python의 `inspect` 모듈을 사용하고, docstring 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성에는 `pydantic`을 사용합니다.
+함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring을 파싱하기 위해 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성을 위해 `pydantic`을 사용합니다.
-OpenAI Responses 모델을 사용할 때 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. [`tool_namespace()`][agents.tool.tool_namespace]로 관련 함수 도구를 그룹화할 수도 있습니다. 전체 설정 및 제약은 [호스티드 도구 검색](#hosted-tool-search)을 참조하세요.
+OpenAI Responses 모델을 사용할 때 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. 관련 함수 도구를 [`tool_namespace()`][agents.tool.tool_namespace]로 그룹화할 수도 있습니다. 전체 설정과 제약 사항은 [호스티드 도구 검색](#hosted-tool-search)을 참조하세요.
```python
import json
@@ -308,12 +308,12 @@ for tool in agent.tools:
```
-1. 함수 인수로 모든 Python 타입을 사용할 수 있으며, 함수는 sync 또는 async일 수 있습니다
-2. docstring이 있으면 설명과 인수 설명을 수집하는 데 사용됩니다
-3. 함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 함). 도구 이름, 설명, 사용할 docstring 스타일 등 재정의도 설정할 수 있습니다
-4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다
+1. 함수 인수로 모든 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다.
+2. Docstring이 있으면 설명과 인수 설명을 캡처하는 데 사용됩니다
+3. 함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 함). 도구 이름, 설명, 사용할 docstring 스타일 등과 같은 재정의도 설정할 수 있습니다.
+4. 데코레이트된 함수를 도구 목록에 전달할 수 있습니다.
-??? note "출력 펼쳐보기"
+??? note "출력을 보려면 펼치기"
```
fetch_weather
@@ -385,20 +385,20 @@ for tool in agent.tools:
### 함수 도구에서 이미지 또는 파일 반환
-텍스트 출력 반환 외에도 함수 도구 출력으로 하나 이상의 이미지나 파일을 반환할 수 있습니다. 이를 위해 다음 중 하나를 반환할 수 있습니다:
+텍스트 출력 반환 외에도 함수 도구의 출력으로 하나 이상의 이미지 또는 파일을 반환할 수 있습니다. 이를 위해 다음 중 하나를 반환할 수 있습니다.
-- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage](또는 TypedDict 버전 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict])
-- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent](또는 TypedDict 버전 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict])
-- 텍스트: 문자열 또는 문자열화 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText](또는 TypedDict 버전 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict])
+- 이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict])
+- 파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict])
+- 텍스트: 문자열 또는 문자열화 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText] (또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict])
### 사용자 지정 함수 도구
-때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원하면 [`FunctionTool`][agents.tool.FunctionTool]을 직접 생성할 수 있습니다. 다음을 제공해야 합니다:
+때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool]을 직접 만들 수 있습니다. 다음을 제공해야 합니다.
- `name`
- `description`
-- `params_json_schema`: 인수용 JSON 스키마
-- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 JSON 문자열 형태의 인수를 받아 도구 출력을 반환하는 async 함수(예: 텍스트, 구조화된 도구 출력 객체, 또는 출력 목록)
+- `params_json_schema`: 인수에 대한 JSON 스키마
+- `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 인수를 JSON 문자열로 받고 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 async 함수
```python
from typing import Any
@@ -433,16 +433,16 @@ tool = FunctionTool(
### 자동 인수 및 docstring 파싱
-앞서 언급했듯이 도구 스키마를 추출하기 위해 함수 시그니처를 자동 파싱하고, 도구 및 개별 인수 설명을 추출하기 위해 docstring을 파싱합니다. 참고 사항:
+앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 이에 대한 몇 가지 참고 사항은 다음과 같습니다.
-1. 시그니처 파싱은 `inspect` 모듈로 수행됩니다. 인수 타입을 이해하기 위해 타입 어노테이션을 사용하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다
-2. docstring 파싱에는 `griffe`를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동 감지하려고 시도하지만 최선의 노력(best-effort)이며, `function_tool` 호출 시 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정해 docstring 파싱을 비활성화할 수도 있습니다
+1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 어노테이션을 사용하여 인수의 타입을 이해하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다.
+2. `griffe`를 사용하여 docstring을 파싱합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동으로 감지하려고 시도하지만 이는 최선의 노력이며, `function_tool`을 호출할 때 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 docstring 파싱을 비활성화할 수도 있습니다.
스키마 추출 코드는 [`agents.function_schema`][]에 있습니다.
-### Pydantic Field로 인수 제약 및 설명 추가
+### Pydantic Field로 인수 제한 및 설명
-Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용해 도구 인수에 제약(예: 숫자의 최솟값/최댓값, 문자열 길이/패턴)과 설명을 추가할 수 있습니다. Pydantic과 마찬가지로 기본값 기반(`arg: int = Field(..., ge=1)`)과 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`) 두 형식을 모두 지원합니다. 생성되는 JSON 스키마와 검증에 이러한 제약이 포함됩니다.
+Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용하여 도구 인수에 제약(예: 숫자의 최소/최대, 문자열의 길이 또는 패턴)과 설명을 추가할 수 있습니다. Pydantic에서처럼 두 형식이 모두 지원됩니다. 기본값 기반(`arg: int = Field(..., ge=1)`) 및 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`). 생성된 JSON 스키마와 유효성 검사에는 이러한 제약이 포함됩니다.
```python
from typing import Annotated
@@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr
### 함수 도구 타임아웃
-`@function_tool(timeout=...)`으로 async 함수 도구의 호출별 타임아웃을 설정할 수 있습니다.
+`@function_tool(timeout=...)`으로 async 함수 도구에 호출별 타임아웃을 설정할 수 있습니다.
```python
import asyncio
@@ -482,13 +482,13 @@ agent = Agent(
)
```
-타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델에 표시되는 타임아웃 메시지를 보냅니다(예: `Tool 'slow_lookup' timed out after 2 seconds.`).
+타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델이 볼 수 있는 타임아웃 메시지(예: `Tool 'slow_lookup' timed out after 2 seconds.`)를 보냅니다.
-타임아웃 처리를 제어할 수 있습니다:
+타임아웃 처리를 제어할 수 있습니다.
-- `timeout_behavior="error_as_result"`(기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 반환
-- `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]를 발생시키고 실행 실패 처리
-- `timeout_error_function=...`: `error_as_result` 사용 시 타임아웃 메시지 사용자 지정
+- `timeout_behavior="error_as_result"` (기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 반환합니다.
+- `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]를 발생시키고 실행을 실패시킵니다.
+- `timeout_error_function=...`: `error_as_result`를 사용할 때 타임아웃 메시지를 사용자 지정합니다.
```python
import asyncio
@@ -511,15 +511,15 @@ except ToolTimeoutError as e:
!!! note
- 타임아웃 구성은 async `@function_tool` 핸들러에서만 지원됩니다
+ 타임아웃 구성은 async `@function_tool` 핸들러에만 지원됩니다.
### 함수 도구의 오류 처리
-`@function_tool`로 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 크래시될 때 LLM에 오류 응답을 제공하는 함수입니다.
+`@function_tool`을 통해 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 충돌하는 경우 LLM에 오류 응답을 제공하는 함수입니다.
-- 기본값(즉, 아무것도 전달하지 않음)에서는 오류가 발생했음을 LLM에 알리는 `default_tool_error_function`을 실행합니다
-- 사용자 지정 오류 함수를 전달하면 대신 이를 실행하고 응답을 LLM으로 보냅니다
-- 명시적으로 `None`을 전달하면 모든 도구 호출 오류가 재발생되어 사용자가 처리할 수 있습니다. 모델이 잘못된 JSON을 생성했다면 `ModelBehaviorError`, 코드가 크래시했다면 `UserError` 등이 될 수 있습니다
+- 기본적으로(즉, 아무것도 전달하지 않으면) LLM에 오류가 발생했음을 알리는 `default_tool_error_function`이 실행됩니다.
+- 자체 오류 함수를 전달하면 대신 그것이 실행되고 응답이 LLM에 전송됩니다.
+- 명시적으로 `None`을 전달하면 모든 도구 호출 오류가 다시 발생하여 직접 처리할 수 있습니다. 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`일 수 있고, 코드가 충돌한 경우 `UserError`일 수 있습니다.
```python
from agents import function_tool, RunContextWrapper
@@ -542,11 +542,11 @@ def get_user_profile(user_id: str) -> str:
```
-`FunctionTool` 객체를 수동으로 생성하는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다.
+`FunctionTool` 객체를 수동으로 만드는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다.
## Agents as tools
-일부 워크플로에서는 제어를 핸드오프하는 대신, 중앙 에이전트가 특화된 에이전트 네트워크를 에이전트 오케스트레이션하도록 하고 싶을 수 있습니다. 에이전트를 도구로 모델링하면 이를 수행할 수 있습니다.
+일부 워크플로에서는 제어를 핸드오프하는 대신, 중앙 에이전트가 전문화된 에이전트 네트워크를 오케스트레이션하도록 하고 싶을 수 있습니다. 에이전트를 도구로 모델링하여 이를 수행할 수 있습니다.
```python
from agents import Agent, Runner
@@ -587,7 +587,7 @@ async def main():
### 도구 에이전트 사용자 지정
-`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환할 수 있도록 하는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 통한 구조화된 입력도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, 폴백 동작, 다중 에이전트 호출 체이닝)의 경우 도구 구현에서 `Runner.run`을 직접 사용하세요:
+`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환할 수 있게 해주는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 통한 structured input도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, fallback 동작 또는 여러 에이전트 호출 체이닝)의 경우 도구 구현에서 `Runner.run`을 직접 사용하세요.
```python
@function_tool
@@ -606,15 +606,15 @@ async def run_my_agent() -> str:
return str(result.final_output)
```
-### 도구 에이전트용 구조화된 입력
+### 도구 에이전트의 구조화된 입력
-기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달해 구조화된 스키마를 노출할 수 있습니다.
+기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달하여 구조화된 스키마를 노출할 수 있습니다.
추가 옵션:
-- `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON Schema를 포함합니다
-- `input_builder=...`는 구조화된 도구 인수가 중첩 에이전트 입력으로 변환되는 방식을 완전히 사용자 지정할 수 있게 합니다
-- `RunContextWrapper.tool_input`에는 중첩 실행 컨텍스트 내부의 파싱된 구조화 페이로드가 포함됩니다
+- `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON Schema를 포함합니다.
+- `input_builder=...`를 사용하면 구조화된 도구 인수가 중첩 에이전트 입력이 되는 방식을 완전히 사용자 지정할 수 있습니다.
+- `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 안에 파싱된 구조화 페이로드를 포함합니다.
```python
from pydantic import BaseModel, Field
@@ -636,19 +636,19 @@ translator_tool = translator_agent.as_tool(
완전한 실행 가능 예제는 `examples/agent_patterns/agents_as_tools_structured.py`를 참조하세요.
-### 도구 에이전트용 승인 게이트
+### 도구 에이전트의 승인 게이트
-`Agent.as_tool(..., needs_approval=...)`는 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요하면 실행이 일시 중지되고 대기 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)` 호출 후 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요.
+`Agent.as_tool(..., needs_approval=...)`은 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요한 경우 실행이 일시 중지되고 보류 중인 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요.
### 사용자 지정 출력 추출
-특정 경우에는 중앙 에이전트로 반환하기 전에 도구 에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우에 유용합니다:
+특정 경우에는 중앙 에이전트에 반환하기 전에 도구 에이전트의 출력을 수정하고 싶을 수 있습니다. 이는 다음을 원할 때 유용할 수 있습니다.
-- 하위 에이전트 채팅 기록에서 특정 정보(예: JSON 페이로드) 추출
-- 에이전트 최종 답변 변환 또는 재포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환)
-- 출력 검증 또는 에이전트 응답 누락/손상 시 폴백 값 제공
+- 하위 에이전트의 채팅 기록에서 특정 정보 조각(예: JSON 페이로드)을 추출
+- 에이전트의 최종 답변을 변환하거나 다시 포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환)
+- 출력을 검증하거나 에이전트의 응답이 누락되었거나 잘못된 형식일 때 fallback 값 제공
-`as_tool` 메서드에 `custom_output_extractor` 인수를 제공해 이를 수행할 수 있습니다:
+`as_tool` 메서드에 `custom_output_extractor` 인수를 제공하여 이를 수행할 수 있습니다.
```python
async def extract_json_payload(run_result: RunResult) -> str:
@@ -667,9 +667,9 @@ json_tool = data_agent.as_tool(
)
```
-사용자 지정 추출기 내부에서 중첩된 [`RunResult`][agents.result.RunResult]는
-[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는
-중첩 결과 후처리 중 외부 도구 이름, 호출 ID, 원문 인수가 필요할 때 유용합니다.
+사용자 지정 추출기 안에서 중첩 [`RunResult`][agents.result.RunResult]는
+[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는 중첩 결과를 후처리하는 동안
+외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다.
[결과 가이드](results.md#agent-as-tool-metadata)를 참조하세요.
### 중첩 에이전트 실행 스트리밍
@@ -694,15 +694,15 @@ billing_agent_tool = billing_agent.as_tool(
예상 동작:
-- 이벤트 유형은 `StreamEvent["type"]`을 반영합니다: `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`
-- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드로 실행되고, 최종 출력 반환 전에 스트림을 소진합니다
-- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착 순서대로 전달됩니다
-- 도구가 모델 도구 호출로 호출될 때 `tool_call`이 존재하며, 직접 호출에서는 `None`일 수 있습니다
-- 전체 실행 가능 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요
+- 이벤트 유형은 `StreamEvent["type"]`를 반영합니다. `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`
+- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드로 실행되고 최종 출력을 반환하기 전에 스트림을 모두 소비합니다.
+- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착하는 순서대로 전달됩니다.
+- `tool_call`은 도구가 모델 도구 호출을 통해 호출될 때 존재합니다. 직접 호출에서는 `None`으로 남을 수 있습니다.
+- 완전한 실행 가능 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요.
### 조건부 도구 활성화
-`is_enabled` 매개변수를 사용해 런타임에서 에이전트 도구를 조건부로 활성화 또는 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에서 사용할 수 있는 도구를 동적으로 필터링할 수 있습니다.
+`is_enabled` 매개변수를 사용하여 런타임에 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에 사용 가능한 도구를 동적으로 필터링할 수 있습니다.
```python
import asyncio
@@ -757,24 +757,24 @@ async def main():
asyncio.run(main())
```
-`is_enabled` 매개변수는 다음을 허용합니다:
+`is_enabled` 매개변수는 다음을 허용합니다.
-- **불리언 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화)
-- **호출 가능한 함수**: `(context, agent)`를 받아 불리언을 반환하는 함수
-- **비동기 함수**: 복잡한 조건 로직을 위한 async 함수
+- **Boolean 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화)
+- **호출 가능한 함수**: `(context, agent)`를 받아 boolean을 반환하는 함수
+- **Async 함수**: 복잡한 조건부 로직을 위한 async 함수
-비활성화된 도구는 런타임에서 LLM에 완전히 숨겨지므로 다음에 유용합니다:
+비활성화된 도구는 런타임에 LLM으로부터 완전히 숨겨지므로, 다음에 유용합니다.
-- 사용자 권한 기반 기능 게이팅
-- 환경별 도구 가용성(dev vs prod)
+- 사용자 권한에 기반한 기능 게이팅
+- 환경별 도구 사용 가능성(dev vs prod)
- 서로 다른 도구 구성의 A/B 테스트
-- 런타임 상태 기반 동적 도구 필터링
+- 런타임 상태에 기반한 동적 도구 필터링
-## 실험적 기능: Codex 도구
+## 실험적: Codex 도구
-`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중 워크스페이스 범위 작업(shell, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다.
+`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중에 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다.
-현재 실행을 벗어나지 않고 메인 에이전트가 제한된 워크스페이스 작업을 Codex에 위임하길 원할 때 사용하세요. 기본 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구를 포함할 때는 각각 고유한 이름을 사용해야 합니다.
+메인 에이전트가 현재 실행을 벗어나지 않고 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 사용하세요. 기본적으로 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다.
```python
from agents import Agent
@@ -788,7 +788,7 @@ agent = Agent(
sandbox_mode="workspace-write",
working_directory="/path/to/repo",
default_thread_options=ThreadOptions(
- model="gpt-5.4",
+ model="gpt-5.5",
model_reasoning_effort="low",
network_access_enabled=True,
web_search_mode="disabled",
@@ -803,33 +803,33 @@ agent = Agent(
)
```
-다음 옵션 그룹으로 시작하세요:
+다음 옵션 그룹부터 시작하세요.
-- 실행 표면: `sandbox_mode`와 `working_directory`는 Codex가 작동할 위치를 정의합니다. 함께 사용하고, 작업 디렉터리가 Git 저장소 내부가 아니면 `skip_git_repo_check=True`를 설정하세요
-- 스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, reasoning effort, 승인 정책, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요
-- 턴 기본값: `default_turn_options=TurnOptions(...)`는 `idle_timeout_seconds` 및 선택적 취소 `signal` 같은 턴별 동작을 구성합니다
-- 도구 I/O: 도구 호출에는 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 포함된 `inputs` 항목이 최소 하나 필요합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다
+- 실행 표면: `sandbox_mode` 및 `working_directory`는 Codex가 작동할 수 있는 위치를 정의합니다. 둘을 함께 사용하고, 작업 디렉터리가 Git 저장소 안에 있지 않으면 `skip_git_repo_check=True`를 설정하세요.
+- 스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, reasoning effort, approval policy, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요.
+- 턴 기본값: `default_turn_options=TurnOptions(...)`는 `idle_timeout_seconds` 및 선택적 취소 `signal` 같은 턴별 동작을 구성합니다.
+- 도구 I/O: 도구 호출은 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 있는 `inputs` 항목을 최소 하나 포함해야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다.
-스레드 재사용과 영속성은 별도의 제어입니다:
+스레드 재사용과 지속성은 별도의 제어입니다.
-- `persist_session=True`는 동일 도구 인스턴스의 반복 호출에서 하나의 Codex 스레드를 재사용합니다
-- `use_run_context_thread_id=True`는 동일한 가변 컨텍스트 객체를 공유하는 실행 간에 run context에 스레드 ID를 저장하고 재사용합니다
-- 스레드 ID 우선순위는 호출별 `thread_id`, 그다음 run-context 스레드 ID(활성화된 경우), 그다음 구성된 `thread_id` 옵션입니다
-- 기본 run-context 키는 `name="codex"`일 때 `codex_thread_id`, `name="codex_"`일 때 `codex_thread_id_`입니다. `run_context_thread_id_key`로 재정의하세요
+- `persist_session=True`는 같은 도구 인스턴스에 반복적으로 호출할 때 하나의 Codex 스레드를 재사용합니다.
+- `use_run_context_thread_id=True`는 동일한 변경 가능한 컨텍스트 객체를 공유하는 실행 전반에서 실행 컨텍스트에 스레드 ID를 저장하고 재사용합니다.
+- 스레드 ID 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 구성된 `thread_id` 옵션 순입니다.
+- 기본 실행 컨텍스트 키는 `name="codex"`의 경우 `codex_thread_id`이고, `name="codex_"`의 경우 `codex_thread_id_`입니다. `run_context_thread_id_key`로 재정의하세요.
런타임 구성:
-- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나, `codex_options={"api_key": "..."}`를 전달하세요
-- 런타임: `codex_options.base_url`은 CLI base URL을 재정의합니다
-- 바이너리 확인: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 확인한 뒤 번들된 vendor 바이너리로 폴백합니다
-- 환경: `codex_options.env`는 서브프로세스 환경을 완전히 제어합니다. 제공되면 서브프로세스는 `os.environ`을 상속하지 않습니다
-- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536`~`67108864`이며 기본값은 `8388608`입니다
-- 스트리밍: `on_stream`은 스레드/턴 라이프사이클 이벤트와 항목 이벤트(`reasoning`, `command_execution`, `mcp_tool_call`, `file_change`, `web_search`, `todo_list`, `error` 항목 업데이트)를 수신합니다
-- 출력: 결과에는 `response`, `usage`, `thread_id`가 포함되며, usage는 `RunContextWrapper.usage`에 추가됩니다
+- 인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나 `codex_options={"api_key": "..."}`를 전달하세요.
+- 런타임: `codex_options.base_url`은 CLI 기본 URL을 재정의합니다.
+- 바이너리 해석: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 해석한 뒤, 번들된 벤더 바이너리로 fallback합니다.
+- 환경: `codex_options.env`는 서브프로세스 환경을 완전히 제어합니다. 이 값이 제공되면 서브프로세스는 `os.environ`을 상속하지 않습니다.
+- 스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr reader 제한을 제어합니다. 유효 범위는 `65536`부터 `67108864`까지이며, 기본값은 `8388608`입니다.
+- 스트리밍: `on_stream`은 스레드/턴 수명 주기 이벤트와 항목 이벤트(`reasoning`, `command_execution`, `mcp_tool_call`, `file_change`, `web_search`, `todo_list`, `error` 항목 업데이트)를 수신합니다.
+- 출력: 결과에는 `response`, `usage`, `thread_id`가 포함되며, usage는 `RunContextWrapper.usage`에 추가됩니다.
-참고 자료:
+참조:
-- [Codex 도구 API 레퍼런스](ref/extensions/experimental/codex/codex_tool.md)
-- [ThreadOptions 레퍼런스](ref/extensions/experimental/codex/thread_options.md)
-- [TurnOptions 레퍼런스](ref/extensions/experimental/codex/turn_options.md)
-- 전체 실행 가능 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참조하세요
\ No newline at end of file
+- [Codex 도구 API 참조](ref/extensions/experimental/codex/codex_tool.md)
+- [ThreadOptions 참조](ref/extensions/experimental/codex/thread_options.md)
+- [TurnOptions 참조](ref/extensions/experimental/codex/turn_options.md)
+- 완전한 실행 가능 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참조하세요.
\ No newline at end of file
diff --git a/docs/ko/voice/quickstart.md b/docs/ko/voice/quickstart.md
index 9b8ee8c0ed..a1244ab025 100644
--- a/docs/ko/voice/quickstart.md
+++ b/docs/ko/voice/quickstart.md
@@ -4,9 +4,9 @@ search:
---
# 빠른 시작
-## 사전 요구사항
+## 사전 요구 사항
-Agents SDK의 기본 [빠른 시작 안내](../quickstart.md)를 따랐는지 확인하고 가상 환경을 설정하세요. 그런 다음 SDK에서 선택적 음성 의존성을 설치하세요
+Agents SDK에 대한 기본 [빠른 시작 지침](../quickstart.md)을 따르고 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택적 음성 종속성을 설치하세요.
```bash
pip install 'openai-agents[voice]'
@@ -14,11 +14,11 @@ pip install 'openai-agents[voice]'
## 개념
-알아두어야 할 핵심 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다
+알아야 할 주요 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다.
-1. 오디오를 텍스트로 변환하기 위해 speech-to-text 모델을 실행합니다
-2. 결과를 생성하기 위해 코드(보통 에이전트 워크플로)를 실행합니다
-3. 결과 텍스트를 다시 오디오로 변환하기 위해 text-to-speech 모델을 실행합니다
+1. 음성을 텍스트로 변환하기 위해 speech-to-text 모델을 실행합니다.
+2. 결과를 생성하기 위해 일반적으로 에이전트형 워크플로인 코드를 실행합니다.
+3. 결과 텍스트를 다시 음성으로 변환하기 위해 text-to-speech 모델을 실행합니다.
```mermaid
graph LR
@@ -48,7 +48,7 @@ graph LR
## 에이전트
-먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 에이전트 몇 개, 핸드오프, 그리고 도구 하나를 사용할 것입니다
+먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 몇 개의 에이전트, 핸드오프, 도구를 사용하겠습니다.
```python
import asyncio
@@ -76,7 +76,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -84,7 +84,7 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
@@ -92,7 +92,7 @@ agent = Agent(
## 음성 파이프라인
-워크플로로 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 사용해 간단한 음성 파이프라인을 설정하겠습니다
+워크플로로 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow]를 사용하여 간단한 음성 파이프라인을 설정하겠습니다.
```python
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
@@ -160,7 +160,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -168,7 +168,7 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
@@ -195,4 +195,4 @@ if __name__ == "__main__":
asyncio.run(main())
```
-이 예제를 실행하면 에이전트가 사용자에게 말합니다! 사용자가 직접 에이전트에게 말할 수 있는 데모를 보려면 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인해 보세요
\ No newline at end of file
+이 예제를 실행하면 에이전트가 사용자에게 말을 합니다! 직접 에이전트에게 말해 볼 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인하세요.
\ No newline at end of file
diff --git a/docs/zh/agents.md b/docs/zh/agents.md
index ff8e67ad35..64e9b5fc80 100644
--- a/docs/zh/agents.md
+++ b/docs/zh/agents.md
@@ -4,49 +4,49 @@ search:
---
# 智能体
-智能体是你应用中的核心构建模块。智能体是一个大型语言模型（LLM），通过 instructions、tools，以及可选的运行时行为（如任务转移、安全防护措施和 structured outputs）进行配置。
+智能体是应用中的核心构建块。智能体是一个大语言模型（LLM），配置了 instructions、工具，以及可选的运行时行为，例如任务转移、安全防护措施和 structured outputs。
-当你想要定义或自定义单个普通 `Agent` 时，请使用本页。如果你在决定多个智能体应如何协作，请阅读[智能体编排](multi_agent.md)。如果智能体应在隔离工作区中运行，并使用由清单定义的文件和沙箱原生能力，请阅读[Sandbox 智能体概念](sandbox/guide.md)。
+当你想定义或自定义单个普通 `Agent` 时，请使用本页。如果你正在决定多个智能体应如何协作，请阅读[智能体编排](multi_agent.md)。如果智能体应在包含清单定义文件和沙箱原生能力的隔离工作区内运行，请阅读[沙箱智能体概念](sandbox/guide.md)。
-SDK 默认对 OpenAI 模型使用 Responses API，但这里的区别在于编排：`Agent` 加 `Runner` 让 SDK 为你管理轮次、tools、安全防护措施、任务转移和会话。如果你希望自行掌控该循环，请直接使用 Responses API。
+SDK 对 OpenAI 模型默认使用 Responses API，但这里的区别在于编排：`Agent` 加 `Runner` 让 SDK 为你管理轮次、工具、安全防护措施、任务转移和会话。如果你想自己掌控这个循环，请直接使用 Responses API。
-## 下一指南选择
+## 下一篇指南的选择
-将本页作为智能体定义的中心。跳转到与你下一步决策相匹配的相邻指南。
+使用本页作为智能体定义的中心。跳转到与你接下来需要做出的决定相匹配的相邻指南。
-| 如果你想要... | 下一步阅读 |
+| 如果你想要... | 接下来阅读 |
| --- | --- |
-| 选择模型或提供商配置 | [模型](models/index.md) |
+| 选择模型或服务商设置 | [模型](models/index.md) |
| 为智能体添加能力 | [工具](tools.md) |
-| 让智能体在真实代码仓库、文档包或隔离工作区上运行 | [Sandbox 智能体快速开始](sandbox_agents.md) |
-| 在管理者式编排与任务转移之间做选择 | [智能体编排](multi_agent.md) |
+| 针对真实代码仓库、文档包或隔离工作区运行智能体 | [沙箱智能体快速入门](sandbox_agents.md) |
+| 在管理器风格的编排与任务转移之间做决定 | [智能体编排](multi_agent.md) |
| 配置任务转移行为 | [任务转移](handoffs.md) |
| 运行轮次、流式传输事件或管理对话状态 | [运行智能体](running_agents.md) |
| 检查最终输出、运行项或可恢复状态 | [结果](results.md) |
| 共享本地依赖和运行时状态 | [上下文管理](context.md) |
-## 基础配置
+## 基本配置
-智能体最常见的属性有：
+智能体最常见的属性包括：
| 属性 | 必需 | 描述 |
| --- | --- | --- |
| `name` | 是 | 人类可读的智能体名称。 |
-| `instructions` | 是 | 系统提示词或动态 instructions 回调。参见[动态 instructions](#dynamic-instructions)。 |
-| `prompt` | 否 | OpenAI Responses API 的提示词配置。接受静态 prompt 对象或函数。参见[提示词模板](#prompt-templates)。 |
-| `handoff_description` | 否 | 当该智能体作为任务转移目标提供时展示的简短描述。 |
-| `handoffs` | 否 | 将对话委派给专用智能体。参见[任务转移](handoffs.md)。 |
-| `model` | 否 | 使用哪个 LLM。参见[模型](models/index.md)。 |
-| `model_settings` | 否 | 模型调优参数，如 `temperature`、`top_p` 和 `tool_choice`。 |
-| `tools` | 否 | 智能体可调用的工具。参见[工具](tools.md)。 |
-| `mcp_servers` | 否 | 智能体的 MCP 支持工具。参见 [MCP 指南](mcp.md)。 |
-| `mcp_config` | 否 | 微调 MCP 工具准备方式，如严格 schema 转换和 MCP 失败格式化。参见 [MCP 指南](mcp.md#agent-level-mcp-configuration)。 |
-| `input_guardrails` | 否 | 在此智能体链的第一条用户输入上运行的安全防护措施。参见[安全防护措施](guardrails.md)。 |
-| `output_guardrails` | 否 | 在该智能体最终输出上运行的安全防护措施。参见[安全防护措施](guardrails.md)。 |
-| `output_type` | 否 | 使用结构化输出类型而非纯文本。参见[输出类型](#output-types)。 |
-| `hooks` | 否 | 智能体作用域的生命周期回调。参见[生命周期事件（hooks）](#lifecycle-events-hooks)。 |
-| `tool_use_behavior` | 否 | 控制工具结果是回传模型还是结束运行。参见[工具使用行为](#tool-use-behavior)。 |
-| `reset_tool_choice` | 否 | 工具调用后重置 `tool_choice`（默认：`True`）以避免工具使用循环。参见[强制工具使用](#forcing-tool-use)。 |
+| `instructions` | 是 | 系统提示词或动态 instructions 回调。请参阅[动态 instructions](#dynamic-instructions)。 |
+| `prompt` | 否 | OpenAI Responses API prompt 配置。接受静态 prompt 对象或函数。请参阅[提示词模板](#prompt-templates)。 |
+| `handoff_description` | 否 | 当此智能体作为任务转移目标提供时展示的简短描述。 |
+| `handoffs` | 否 | 将对话委托给专家智能体。请参阅[任务转移](handoffs.md)。 |
+| `model` | 否 | 使用哪个 LLM。请参阅[模型](models/index.md)。 |
+| `model_settings` | 否 | 模型调优参数，例如 `temperature`、`top_p` 和 `tool_choice`。 |
+| `tools` | 否 | 智能体可以调用的工具。请参阅[工具](tools.md)。 |
+| `mcp_servers` | 否 | 面向智能体、由 MCP 支持的工具。请参阅 [MCP 指南](mcp.md)。 |
+| `mcp_config` | 否 | 微调 MCP 工具的准备方式，例如严格 schema 转换和 MCP 失败格式化。请参阅 [MCP 指南](mcp.md#agent-level-mcp-configuration)。 |
+| `input_guardrails` | 否 | 在此智能体链的第一个用户输入上运行的安全防护措施。请参阅[安全防护措施](guardrails.md)。 |
+| `output_guardrails` | 否 | 在此智能体最终输出上运行的安全防护措施。请参阅[安全防护措施](guardrails.md)。 |
+| `output_type` | 否 | 使用结构化输出类型而非纯文本。请参阅[输出类型](#output-types)。 |
+| `hooks` | 否 | 作用于智能体范围的生命周期回调。请参阅[生命周期事件（hooks）](#lifecycle-events-hooks)。 |
+| `tool_use_behavior` | 否 | 控制工具结果是回传给模型还是结束运行。请参阅[工具使用行为](#tool-use-behavior)。 |
+| `reset_tool_choice` | 否 | 在工具调用后重置 `tool_choice`（默认：`True`），以避免工具使用循环。请参阅[强制使用工具](#forcing-tool-use)。 |
```python
from agents import Agent, ModelSettings, function_tool
@@ -64,17 +64,17 @@ agent = Agent(
)
```
-本节所有内容都适用于 `Agent`。`SandboxAgent` 基于相同理念，并额外增加 `default_manifest`、`base_instructions`、`capabilities` 和 `run_as` 以支持工作区作用域运行。参见[Sandbox 智能体概念](sandbox/guide.md)。
+本节中的所有内容都适用于 `Agent`。`SandboxAgent` 基于相同理念构建，并额外添加了 `default_manifest`、`base_instructions`、`capabilities` 和 `run_as`，用于工作区范围的运行。请参阅[沙箱智能体概念](sandbox/guide.md)。
## 提示词模板
-你可以通过设置 `prompt` 引用在 OpenAI 平台中创建的提示词模板。这适用于使用 Responses API 的 OpenAI 模型。
+你可以通过设置 `prompt` 来引用在 OpenAI 平台中创建的提示词模板。这适用于使用 Responses API 的 OpenAI 模型。
-使用方法如下：
+要使用它，请：
1. 前往 https://platform.openai.com/playground/prompts
-2. 创建一个新的提示词变量 `poem_style`。
-3. 创建一个系统提示词，内容为：
+2. 创建新的 prompt 变量 `poem_style`。
+3. 创建一个包含以下内容的系统提示词：
```
Write a poem in {{poem_style}}
@@ -127,9 +127,9 @@ result = await Runner.run(
## 上下文
-智能体在其 `context` 类型上是泛型的。上下文是依赖注入工具：它是你创建并传给 `Runner.run()` 的对象，会传递给每个智能体、工具、任务转移等，并作为智能体运行期间依赖和状态的集合。你可以提供任何 Python 对象作为上下文。
+智能体在其 `context` 类型上是泛型的。上下文是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会被传递给每个智能体、工具、任务转移等，并作为智能体运行所需依赖和状态的集合。你可以提供任何 Python 对象作为上下文。
-阅读[上下文指南](context.md)了解完整的 `RunContextWrapper` 接口、共享使用量追踪、嵌套 `tool_input` 以及序列化注意事项。
+阅读[上下文指南](context.md)，了解完整的 `RunContextWrapper` 接口、共享用量跟踪、嵌套 `tool_input` 以及序列化注意事项。
```python
@dataclass
@@ -148,7 +148,7 @@ agent = Agent[UserContext](
## 输出类型
-默认情况下，智能体产生纯文本（即 `str`）输出。如果你希望智能体产生特定类型输出，可以使用 `output_type` 参数。常见选择是使用 [Pydantic](https://docs.pydantic.dev/) 对象，但我们支持任何可被 Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 包装的类型——dataclasses、lists、TypedDict 等。
+默认情况下，智能体生成纯文本（即 `str`）输出。如果你希望智能体生成特定类型的输出，可以使用 `output_type` 参数。常见选择是使用 [Pydantic](https://docs.pydantic.dev/) 对象，但我们支持任何可以包装在 Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 中的类型——dataclasses、列表、TypedDict 等。
```python
from pydantic import BaseModel
@@ -169,20 +169,20 @@ agent = Agent(
!!! note
- 当你传入 `output_type` 时，这会告知模型使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) 而非常规纯文本响应。
+ 当你传入 `output_type` 时，这会告诉模型使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而不是常规纯文本响应。
## 多智能体系统设计模式
-设计多智能体系统的方法有很多，但我们常见两种广泛适用的模式：
+设计多智能体系统有许多方式，但我们通常看到两种广泛适用的模式：
-1. 管理者（Agents as tools）：中心管理者/编排器将专用子智能体作为工具调用，并保留对对话的控制。
-2. 任务转移：对等智能体将控制权交给接管对话的专用智能体。这是去中心化模式。
+1. 管理器（agents as tools）：中央管理器/编排器将专用子智能体作为工具调用，并保留对对话的控制权。
+2. 任务转移：对等智能体将控制权转交给接管对话的专用智能体。这是去中心化的。
-更多细节请参见[我们构建智能体的实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。
+更多详情，请参阅[我们的智能体构建实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。
-### 管理者（Agents as tools）
+### 管理器（agents as tools）
-`customer_facing_agent` 负责所有用户交互，并调用作为工具暴露的专用子智能体。更多内容见[工具](tools.md#agents-as-tools)文档。
+`customer_facing_agent` 处理所有用户交互，并调用作为工具暴露的专用子智能体。请在[工具](tools.md#agents-as-tools)文档中阅读更多内容。
```python
from agents import Agent
@@ -211,7 +211,7 @@ customer_facing_agent = Agent(
### 任务转移
-任务转移是智能体可委派给的子智能体。发生任务转移时，被委派的智能体会接收对话历史并接管对话。该模式支持模块化、专精于单一任务的智能体。更多内容见[任务转移](handoffs.md)文档。
+任务转移是智能体可以委托给的子智能体。当发生任务转移时，被委托的智能体会接收对话历史并接管对话。此模式支持模块化的专用智能体，使其在单一任务上表现出色。请在[任务转移](handoffs.md)文档中阅读更多内容。
```python
from agents import Agent
@@ -232,7 +232,7 @@ triage_agent = Agent(
## 动态 instructions
-在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过函数提供动态 instructions。该函数将接收智能体和上下文，并且必须返回提示词。支持普通函数和 `async` 函数。
+在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过函数提供动态 instructions。该函数将接收智能体和上下文，并且必须返回 prompt。普通函数和 `async` 函数都受支持。
```python
def dynamic_instructions(
@@ -249,27 +249,27 @@ agent = Agent[UserContext](
## 生命周期事件（hooks）
-有时你会希望观察智能体的生命周期。例如，你可能希望在某些事件发生时记录日志、预取数据或记录使用量。
+有时，你希望观察智能体的生命周期。例如，你可能希望在某些事件发生时记录事件、预取数据或记录用量。
有两个 hook 作用域：
-- [`RunHooks`][agents.lifecycle.RunHooks] 观察整个 `Runner.run(...)` 调用，包括向其他智能体的任务转移。
+- [`RunHooks`][agents.lifecycle.RunHooks] 观察整个 `Runner.run(...)` 调用，包括到其他智能体的任务转移。
- [`AgentHooks`][agents.lifecycle.AgentHooks] 通过 `agent.hooks` 附加到特定智能体实例。
-回调上下文也会因事件而变化：
+回调上下文也会根据事件变化：
-- 智能体开始/结束 hooks 接收 [`AgentHookContext`][agents.run_context.AgentHookContext]，它包装你的原始上下文并携带共享的运行使用状态。
+- 智能体开始/结束 hooks 接收 [`AgentHookContext`][agents.run_context.AgentHookContext]，它包装你的原始上下文并携带共享的运行用量状态。
- LLM、工具和任务转移 hooks 接收 [`RunContextWrapper`][agents.run_context.RunContextWrapper]。
典型 hook 时机：
- `on_agent_start` / `on_agent_end`：当特定智能体开始或完成生成最终输出时。
-- `on_llm_start` / `on_llm_end`：每次模型调用的前后。
-- `on_tool_start` / `on_tool_end`：每次本地工具调用前后。
- 对于函数工具，hook 的 `context` 通常是 `ToolContext`，因此你可以检查诸如 `tool_call_id` 的工具调用元数据。
+- `on_llm_start` / `on_llm_end`：紧邻每次模型调用前后。
+- `on_tool_start` / `on_tool_end`：围绕每次本地工具调用。
+ 对于工具调用，hook `context` 通常是 `ToolContext`，因此你可以检查工具调用元数据，例如 `tool_call_id`。
- `on_handoff`：当控制权从一个智能体转移到另一个智能体时。
-当你希望整个工作流只有一个观察者时，使用 `RunHooks`；当某个智能体需要自定义副作用时，使用 `AgentHooks`。
+当你希望为整个工作流设置一个观察者时使用 `RunHooks`；当某个智能体需要自定义副作用时使用 `AgentHooks`。
```python
from agents import Agent, RunHooks, Runner
@@ -291,21 +291,21 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
print(result.final_output)
```
-完整回调接口请参见[生命周期 API 参考](ref/lifecycle.md)。
+完整的回调接口请参阅[生命周期 API 参考](ref/lifecycle.md)。
## 安全防护措施
-安全防护措施允许你在智能体运行的同时并行对用户输入进行检查/验证，并在智能体输出生成后对其输出进行检查/验证。例如，你可以筛查用户输入和智能体输出的相关性。更多内容见[安全防护措施](guardrails.md)文档。
+安全防护措施允许你在智能体运行的同时并行对用户输入进行检查/验证，并在智能体输出生成后对其进行检查/验证。例如，你可以筛查用户输入和智能体输出的相关性。请在[安全防护措施](guardrails.md)文档中阅读更多内容。
-## 克隆/复制智能体
+## 智能体的克隆/复制
-通过在智能体上使用 `clone()` 方法，你可以复制一个 Agent，并可选择修改任意属性。
+通过在智能体上使用 `clone()` 方法，你可以复制一个 Agent，并可选择更改任何你想要的属性。
```python
pirate_agent = Agent(
name="Pirate",
instructions="Write like a pirate",
- model="gpt-5.4",
+ model="gpt-5.5",
)
robot_agent = pirate_agent.clone(
@@ -314,16 +314,16 @@ robot_agent = pirate_agent.clone(
)
```
-## 强制工具使用
+## 强制使用工具
-提供工具列表并不总意味着 LLM 会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制工具使用。有效值包括：
+提供工具列表并不总意味着 LLM 会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制使用工具。有效值包括：
-1. `auto`：允许 LLM 自行决定是否使用工具。
-2. `required`：要求 LLM 必须使用工具（但它可以智能决定使用哪个工具）。
-3. `none`：要求 LLM _不_ 使用工具。
-4. 设置特定字符串，例如 `my_tool`：要求 LLM 使用该特定工具。
+1. `auto`，允许 LLM 决定是否使用工具。
+2. `required`，要求 LLM 使用工具（但它可以智能地决定使用哪个工具）。
+3. `none`，要求 LLM _不_ 使用工具。
+4. 设置特定字符串，例如 `my_tool`，要求 LLM 使用该特定工具。
-当你使用 OpenAI Responses 工具搜索时，具名工具选择更受限制：你不能通过 `tool_choice` 指向裸命名空间名称或仅延迟工具，且 `tool_choice="tool_search"` 不会指向 [`ToolSearchTool`][agents.tool.ToolSearchTool]。在这些情况下，优先使用 `auto` 或 `required`。有关 Responses 特定约束，参见[托管工具搜索](tools.md#hosted-tool-search)。
+当你使用 OpenAI Responses 工具搜索时，命名工具选择受到更多限制：你不能用 `tool_choice` 指向裸命名空间名称或仅延迟的工具，并且 `tool_choice="tool_search"` 不会指向 [`ToolSearchTool`][agents.tool.ToolSearchTool]。在这些情况下，优先使用 `auto` 或 `required`。有关 Responses 特有的约束，请参阅[托管工具搜索](tools.md#hosted-tool-search)。
```python
from agents import Agent, Runner, function_tool, ModelSettings
@@ -345,8 +345,8 @@ agent = Agent(
`Agent` 配置中的 `tool_use_behavior` 参数控制如何处理工具输出：
-- `"run_llm_again"`：默认值。运行工具后，由 LLM 处理结果以生成最终响应。
-- `"stop_on_first_tool"`：将第一次工具调用的输出直接作为最终响应，不再经过后续 LLM 处理。
+- `"run_llm_again"`：默认值。运行工具，并由 LLM 处理结果以生成最终响应。
+- `"stop_on_first_tool"`：将第一次工具调用的输出用作最终响应，而不再进行 LLM 处理。
```python
from agents import Agent, Runner, function_tool, ModelSettings
@@ -364,7 +364,7 @@ agent = Agent(
)
```
-- `StopAtTools(stop_at_tool_names=[...])`：如果调用了任一指定工具，则停止，并将其输出作为最终响应。
+- `StopAtTools(stop_at_tool_names=[...])`：如果调用了任何指定工具，则停止，并将其输出用作最终响应。
```python
from agents import Agent, Runner, function_tool
@@ -388,7 +388,7 @@ agent = Agent(
)
```
-- `ToolsToFinalOutputFunction`：自定义函数，用于处理工具结果并决定是停止还是继续由 LLM 处理。
+- `ToolsToFinalOutputFunction`：自定义函数，用于处理工具结果并决定是停止还是继续使用 LLM。
```python
from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -426,4 +426,4 @@ agent = Agent(
!!! note
- 为防止无限循环，框架会在工具调用后自动将 `tool_choice` 重置为 "auto"。此行为可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 配置。出现无限循环的原因是工具结果会发送给 LLM，而 LLM 又因为 `tool_choice` 生成新的工具调用，如此无限重复。
\ No newline at end of file
+ 为防止无限循环，框架会在工具调用后自动将 `tool_choice` 重置为 "auto"。此行为可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 配置。无限循环的原因是工具结果会发送给 LLM，而 LLM 随后又会因为 `tool_choice` 生成另一个工具调用，如此反复。
\ No newline at end of file
diff --git a/docs/zh/models/index.md b/docs/zh/models/index.md
index 6d60163e62..5b3939fe6e 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) |
+| 在智能体之间混用模型或 provider | 按每次运行或每个智能体选择 provider，并检查功能差异 | [在一个工作流中混用模型](#mixing-models-in-one-workflow) 和 [跨 provider 混用模型](#mixing-models-across-providers) |
| 调整高级 OpenAI Responses 请求设置 | 在 OpenAI Responses 路径上使用 `ModelSettings` | [高级 OpenAI Responses 设置](#advanced-openai-responses-settings) |
-| 使用第三方适配器进行非 OpenAI 或混合 provider 路由 | 比较受支持的 beta 适配器并验证你计划上线的 provider 路径 | [第三方适配器](#third-party-adapters) |
+| 为非 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.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，以在保持显式 `model_settings` 的同时获得更高质量。
-如果你想切换到其他模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)），有两种方式可配置智能体。
+如果你想切换到其他模型，例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)，有两种方式可以配置你的智能体。
### 默认模型
-首先，如果你希望所有未设置自定义模型的智能体都稳定使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
+首先，如果你想让所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置 `OPENAI_DEFAULT_MODEL` 环境变量。
```bash
-export OPENAI_DEFAULT_MODEL=gpt-5.4
+export OPENAI_DEFAULT_MODEL=gpt-5.5
python3 my_awesome_agent.py
```
-其次，你可以通过 `RunConfig` 为一次 run 设置默认模型。如果未为智能体设置模型，将使用该 run 的模型。
+其次，你可以通过 `RunConfig` 为一次运行设置默认模型。如果没有为某个智能体设置模型，将使用这次运行的模型。
```python
from agents import Agent, RunConfig, Runner
@@ -52,13 +52,13 @@ agent = Agent(
result = await Runner.run(
agent,
"Hello",
- run_config=RunConfig(model="gpt-5.4"),
+ run_config=RunConfig(model="gpt-5.5"),
)
```
#### GPT-5 模型
-当你以这种方式使用任意 GPT-5 模型（如 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4)）时，SDK 会应用默认 `ModelSettings`。它会设置在大多数用例中表现最佳的项。若要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
+当你以这种方式使用任何 GPT-5 模型（例如 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)）时，SDK 会应用默认 `ModelSettings`。它会设置最适合大多数用例的选项。要调整默认模型的推理强度，请传入你自己的 `ModelSettings`：
```python
from openai.types.shared import Reasoning
@@ -67,44 +67,44 @@ from agents import Agent, ModelSettings
my_agent = Agent(
name="My Agent",
instructions="You're a helpful agent.",
- # If OPENAI_DEFAULT_MODEL=gpt-5.4 is set, passing only model_settings works.
+ # If OPENAI_DEFAULT_MODEL=gpt-5.5 is set, passing only model_settings works.
# It's also fine to pass a GPT-5 model name explicitly:
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(reasoning=Reasoning(effort="high"), verbosity="low")
)
```
-为了更低延迟，推荐在 `gpt-5.4` 上使用 `reasoning.effort="none"`。gpt-4.1 系列（包括 mini 和 nano 变体）同样是构建交互式智能体应用的可靠选择。
+为降低延迟，建议将 `reasoning.effort="none"` 与 `gpt-5.5` 搭配使用。gpt-4.1 系列（包括 mini 和 nano 变体）仍然是构建交互式智能体应用的可靠选择。
#### ComputerTool 模型选择
-如果某个智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求中的有效模型会决定 SDK 发送哪种 computer-tool payload。显式的 `gpt-5.4` 请求会使用 GA 内置 `computer` 工具，而显式的 `computer-use-preview` 请求会保留旧版 `computer_use_preview` payload。
+如果智能体包含 [`ComputerTool`][agents.tool.ComputerTool]，实际 Responses 请求上的有效模型将决定 SDK 发送哪种 computer-tool 载荷。显式的 `gpt-5.5` 请求会使用 GA 内置 `computer` 工具，而显式的 `computer-use-preview` 请求会继续使用较旧的 `computer_use_preview` 载荷。
-提示词托管调用是主要例外。如果提示词模板控制模型且 SDK 在请求中省略 `model`，SDK 会默认使用与 preview 兼容的 computer payload，以避免猜测提示词绑定了哪个模型。要在该流程中保持 GA 路径，可在请求中显式设置 `model="gpt-5.4"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制 GA 选择器。
+由提示词管理的调用是主要例外。如果提示词模板拥有模型，并且 SDK 在请求中省略 `model`，SDK 会默认使用与预览版兼容的计算机载荷，这样它就不会猜测提示词绑定的是哪个模型。要在该流程中保持 GA 路径，请在请求上显式设置 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。
-在已注册 [`ComputerTool`][agents.tool.ComputerTool] 的情况下，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 会被标准化为与有效请求模型匹配的内置选择器。如果未注册 `ComputerTool`，这些字符串仍按普通函数名处理。
+注册了 [`ComputerTool`][agents.tool.ComputerTool] 后，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 会被规范化为与有效请求模型匹配的内置选择器。如果未注册 `ComputerTool`，这些字符串会继续像普通函数名一样运行。
-与 preview 兼容的请求必须预先序列化 `environment` 和显示尺寸，因此在使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的提示词托管流程中，应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制 GA 选择器。完整迁移细节见 [Tools](../tools.md#computertool-and-the-responses-computer-tool)。
+与预览版兼容的请求必须预先序列化 `environment` 和显示尺寸，因此使用 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂的由提示词管理的流程应传入具体的 `Computer` 或 `AsyncComputer` 实例，或在发送请求前强制使用 GA 选择器。完整迁移详情请参阅 [工具](../tools.md#computertool-and-the-responses-computer-tool)。
#### 非 GPT-5 模型
-如果你传入非 GPT-5 模型名且未提供自定义 `model_settings`，SDK 会回退到与任意模型兼容的通用 `ModelSettings`。
+如果你传入非 GPT-5 模型名称且没有自定义 `model_settings`，SDK 会回退到与任何模型兼容的通用 `ModelSettings`。
-### 仅 Responses 的工具检索功能
+### 仅 Responses 支持的工具搜索功能
-以下工具功能仅在 OpenAI Responses 模型中受支持：
+以下工具功能仅受 OpenAI Responses 模型支持：
- [`ToolSearchTool`][agents.tool.ToolSearchTool]
- [`tool_namespace()`][agents.tool.tool_namespace]
-- `@function_tool(defer_loading=True)` 及其他延迟加载的 Responses 工具接口
+- `@function_tool(defer_loading=True)` 以及其他延迟加载的 Responses 工具接口
-这些功能在 Chat Completions 模型和非 Responses 后端上会被拒绝。使用延迟加载工具时，请将 `ToolSearchTool()` 添加到智能体，并让模型通过 `auto` 或 `required` 的工具选择来加载工具，而不是强制使用裸命名空间名称或仅延迟加载函数名。设置细节和当前限制见 [Tools](../tools.md#hosted-tool-search)。
+这些功能会在 Chat Completions 模型和非 Responses 后端上被拒绝。当使用延迟加载工具时，请向智能体添加 `ToolSearchTool()`，并让模型通过 `auto` 或 `required` 工具选择来加载工具，而不是强制使用裸命名空间名称或仅延迟加载的函数名称。设置详情和当前限制请参阅 [工具](../tools.md#hosted-tool-search)。
### Responses WebSocket 传输
默认情况下，OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI 支持的模型时，你可以选择启用 websocket 传输。
-#### 基础设置
+#### 基本设置
```python
from agents import set_default_openai_responses_transport
@@ -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.5"`）。
-传输方式选择发生在 SDK 将模型名解析为模型实例时。如果你传入具体的 [`Model`][agents.models.interface.Model] 对象，其传输方式已固定：[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 websocket，[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP，[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 保持在 Chat Completions。若你传入 `RunConfig(model_provider=...)`，则由该 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
@@ -137,7 +137,7 @@ result = await Runner.run(
)
```
-OpenAI 支持的 provider 还接受可选的智能体注册配置。这是高级选项，用于你的 OpenAI 设置需要 provider 级注册元数据（例如 harness ID）的场景。
+由 OpenAI 支持的 provider 还接受可选的智能体注册配置。这是一个高级选项，适用于你的 OpenAI 设置需要 provider 级注册元数据（例如 harness ID）的情况。
```python
from agents import (
@@ -163,14 +163,14 @@ result = await Runner.run(
#### 使用 `MultiProvider` 的高级路由
-如果你需要基于前缀的模型路由（例如在一次 run 中混用 `openai/...` 与 `any-llm/...` 模型名），请使用 [`MultiProvider`][agents.MultiProvider] 并在其中设置 `openai_use_responses_websocket=True`。
+如果你需要基于前缀的模型路由（例如在一次运行中混合 `openai/...` 和 `any-llm/...` 模型名称），请使用 [`MultiProvider`][agents.MultiProvider]，并在那里设置 `openai_use_responses_websocket=True`。
-`MultiProvider` 保留两个历史默认行为：
+`MultiProvider` 保留了两个历史默认行为：
-- `openai/...` 被视为 OpenAI provider 的别名，因此 `openai/gpt-4.1` 会被路由为模型 `gpt-4.1`。
-- 未知前缀会抛出 `UserError`，而不是透传。
+- `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
@@ -196,38 +196,38 @@ result = await Runner.run(
)
```
-当后端期望字面 `openai/...` 字符串时，使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（如 `openrouter/openai/gpt-4.1-mini`）时，使用 `unknown_prefix_mode="model_id"`。这些选项在非 websocket 传输的 `MultiProvider` 上同样可用；此示例保持 websocket 启用，因为本节描述的是传输设置。这些选项同样可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。
+当后端期望字面量 `openai/...` 字符串时，使用 `openai_prefix_mode="model_id"`。当后端期望其他命名空间模型 ID（例如 `openrouter/openai/gpt-4.1-mini`）时，使用 `unknown_prefix_mode="model_id"`。这些选项也可在 websocket 传输之外的 `MultiProvider` 上使用；本示例保持启用 websocket，因为它是本节所述传输设置的一部分。相同选项也可用于 [`responses_websocket_session()`][agents.responses_websocket_session]。
-如果你在通过 `MultiProvider` 路由时也需要相同的 provider 级注册元数据，可传入 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`，它会被转发到底层 OpenAI provider。
+如果你在通过 `MultiProvider` 路由时需要相同的 provider 级注册元数据，请传入 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`，它会被转发给底层 OpenAI provider。
-如果你使用自定义 OpenAI 兼容端点或代理，websocket 传输还要求兼容的 websocket `/responses` 端点。在这些设置中，你可能需要显式设置 `websocket_base_url`。
+如果你使用自定义 OpenAI 兼容端点或代理，websocket 传输还需要兼容的 websocket `/responses` 端点。在这些设置中，你可能需要显式设置 `websocket_base_url`。
-#### 说明
+#### 注意事项
-- 这是基于 websocket 传输的 Responses API，不是 [Realtime API](../realtime/guide.md)。除非它们支持 Responses websocket `/responses` 端点，否则不适用于 Chat Completions 或非 OpenAI provider。
-- 如果你的环境中尚未安装，请安装 `websockets` 包。
-- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮工作流（及嵌套 Agents-as-tools 调用）中复用同一 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 传输的 Responses API，不是 [Realtime API](../realtime/guide.md)。除非 Chat Completions 或非 OpenAI provider 支持 Responses websocket `/responses` 端点，否则它不适用于它们。
+- 如果你的环境中尚未提供 `websockets` 包，请安装它。
+- 启用 websocket 传输后，你可以直接使用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]。对于希望在多轮之间（以及嵌套的 agent-as-tool 调用之间）复用同一个 websocket 连接的多轮工作流，建议使用 [`responses_websocket_session()`][agents.responses_websocket_session] 辅助函数。请参阅 [运行智能体](../running_agents.md) 指南和 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)。
## 非 OpenAI 模型
-如果你需要非 OpenAI provider，请先从 SDK 内置的 provider 集成点开始。很多场景下无需引入第三方适配器。每种模式的示例见 [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 或具体模型对象 | 每个智能体 |
-| 第三方适配器 | 你需要内置路径无法提供的适配器托管 provider 覆盖或路由 | 见[第三方适配器](#third-party-adapters) |
+| 第三方适配器 | 你需要适配器管理的 provider 覆盖或路由，而内置路径无法提供 | 参见 [第三方适配器](#third-party-adapters) |
你可以通过这些内置路径集成其他 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` 层级。可用于声明“本次 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 实例上指定模型。这使你可以为不同智能体混合搭配不同 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 key 时，我们建议通过 `set_tracing_disabled()` 禁用追踪，或配置[不同的追踪进程](../tracing.md)。
+如果你没有来自 `platform.openai.com` 的 API key，我们建议通过 `set_tracing_disabled()` 禁用追踪，或设置一个[不同的追踪进程](../tracing.md)。
``` python
from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
@@ -242,19 +242,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model
!!! note
- 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM provider 仍不支持 Responses API。如果你的 LLM provider 支持，我们建议使用 Responses。
+ 在这些示例中，我们使用 Chat Completions API/模型，因为许多 LLM provider 仍不支持 Responses API。如果你的 LLM provider 支持 Responses API，我们建议使用 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
@@ -279,7 +279,7 @@ triage_agent = Agent(
name="Triage agent",
instructions="Handoff to the appropriate agent based on the language of the request.",
handoffs=[spanish_agent, english_agent],
- model="gpt-5.4",
+ model="gpt-5.5",
)
async def main():
@@ -287,10 +287,10 @@ async def main():
print(result.final_output)
```
-1. 直接设置 OpenAI 模型名称。
-2. 提供 [`Model`][agents.models.interface.Model] 实现。
+1. 直接设置 OpenAI 模型的名称。
+2. 提供一个 [`Model`][agents.models.interface.Model] 实现。
-当你希望进一步配置智能体所用模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供诸如 temperature 等可选模型配置参数。
+当你想进一步配置智能体使用的模型时，可以传入 [`ModelSettings`][agents.models.interface.ModelSettings]，它提供可选模型配置参数，例如 temperature。
```python
from agents import Agent, ModelSettings
@@ -305,26 +305,26 @@ 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`：控制是否将生成的响应存储在服务端以供后续检索。这会影响依赖响应 ID 的后续工作流，以及在 `store=False` 时可能需要回退到本地输入的会话压缩流程。
-- `prompt_cache_retention`：更长时间保留缓存的提示词前缀，例如 `"24h"`。
-- `response_include`：请求更丰富的响应 payload，例如 `web_search_call.action.sources`、`file_search_call.results` 或 `reasoning.encrypted_content`。
-- `top_logprobs`：为输出文本请求 top-token logprobs。SDK 还会自动添加 `message.output_text.logprobs`。
-- `retry`：为模型调用启用由 runner 管理的重试设置。参见[Runner 管理的重试](#runner-managed-retries)。
+- `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)。
```python
from agents import Agent, ModelSettings
research_agent = Agent(
name="Research agent",
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(
parallel_tool_calls=False,
truncation="auto",
@@ -336,13 +336,13 @@ research_agent = Agent(
)
```
-当你设置 `store=False` 时，Responses API 不会保留该响应供后续服务端检索。这对无状态或零数据保留风格流程很有用，但也意味着原本可复用响应 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`
+### 传递 `extra_args`
-当你需要 SDK 尚未在顶层直接暴露的 provider 特定字段或更新请求字段时，请使用 `extra_args`。
+当你需要 provider 特定的或更新的请求字段，而 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
@@ -360,14 +360,14 @@ english_agent = Agent(
## Runner 管理的重试
-重试仅在运行时生效且为显式启用。除非你设置 `ModelSettings(retry=...)` 且重试策略选择重试，否则 SDK 不会重试一般模型请求。
+重试仅在运行时生效，且需要显式启用。除非你设置 `ModelSettings(retry=...)` 且你的重试策略选择重试，否则 SDK 不会重试一般模型请求。
```python
from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
agent = Agent(
name="Assistant",
- model="gpt-5.4",
+ model="gpt-5.5",
model_settings=ModelSettings(
retry=ModelRetrySettings(
max_retries=4,
@@ -395,78 +395,78 @@ agent = Agent(
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `max_retries` | `int | None` | 初始请求之后允许的重试次数。 |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试但未返回显式延迟时使用的默认延迟策略。 |
-| `policy` | `RetryPolicy | None` | 决定是否重试的回调。此字段仅运行时有效，不会被序列化。 |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | 当策略重试且没有返回显式延迟时使用的默认延迟策略。 |
+| `policy` | `RetryPolicy | None` | 决定是否重试的回调。此字段仅在运行时有效，不会被序列化。 |
-重试策略会收到一个包含以下内容的 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]：
+重试策略会接收一个 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]，其中包含：
-- `attempt` 和 `max_retries`，用于按尝试次数做决策。
-- `stream`，用于区分流式与非流式行为分支。
+- `attempt` 和 `max_retries`，以便你做出感知尝试次数的决策。
+- `stream`，以便你在流式和非流式行为之间分支。
- `error`，用于原始检查。
-- `normalized` 事实，如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。
-- 当底层模型适配器可提供重试指导时的 `provider_advice`。
+- `normalized` 事实，例如 `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout` 和 `is_abort`。
+- 当底层模型适配器可以提供重试指导时的 `provider_advice`。
-策略可返回：
+策略可以返回以下任一项：
-- `True` / `False`，用于简单重试决策。
-- [`RetryDecision`][agents.retry.RetryDecision]，当你想覆盖延迟或附加诊断原因时。
+- `True` / `False`，用于简单的重试决策。
+- 当你想覆盖延迟或附加诊断原因时，返回 [`RetryDecision`][agents.retry.RetryDecision]。
-SDK 在 `retry_policies` 中提供现成辅助函数：
+SDK 在 `retry_policies` 上导出开箱即用的辅助函数：
| 辅助函数 | 行为 |
| --- | --- |
-| `retry_policies.never()` | 始终不重试。 |
+| `retry_policies.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.all(...)` | 仅当所有嵌套策略都选择重试时才重试。 |
+| `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 与智能体合并行为
-`retry` 会在 runner 级与智能体级 `ModelSettings` 间进行深度合并：
+`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) 和[基于适配器的重试示例](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 示例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)。
-## 非 OpenAI provider 故障排查
+## 非 OpenAI provider 故障排除
### 追踪客户端错误 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 provider 仍不支持它。因此你可能会看到 404 或类似问题。要解决此问题，你有两个选项：
-1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。当你通过环境变量设置 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL` 时可用。
-2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例见[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
+1. 调用 [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]。如果你通过环境变量设置 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`，这会生效。
+2. 使用 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。示例在[这里](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)。
### structured outputs 支持
-某些模型 provider 不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似如下错误：
+一些模型 provider 不支持 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)。这有时会导致类似以下的错误：
```
@@ -474,34 +474,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 混用模型
-你需要了解不同模型 provider 的功能差异，否则可能遇到错误。例如，OpenAI 支持 structured outputs、多模态输入，以及托管的文件检索和网络检索，但许多其他 provider 不支持这些功能。请注意以下限制：
+你需要了解模型 provider 之间的功能差异，否则可能会遇到错误。例如，OpenAI 支持 structured outputs、多模态输入以及托管的文件检索和网络检索，但许多其他 provider 不支持这些功能。请注意以下限制：
-- 不要向不支持的 provider 发送它们无法理解的 `tools`
-- 在调用纯文本模型前过滤掉多模态输入
-- 注意不支持结构化 JSON 输出的 provider 会偶尔产生无效 JSON
+- 不要向不理解这些 `tools` 的 provider 发送不受支持的 `tools`
+- 在调用仅文本模型前过滤掉多模态输入
+- 注意，不支持结构化 JSON 输出的 provider 偶尔会生成无效 JSON。
## 第三方适配器
-仅当 SDK 内置 provider 集成点不足时，才使用第三方适配器。如果你在本 SDK 中只使用 OpenAI 模型，优先选择内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于需要将 OpenAI 模型与非 OpenAI provider 组合使用，或需要内置路径无法提供的适配器托管 provider 覆盖或路由的场景。适配器在 SDK 与上游模型 provider 之间增加了一层兼容层，因此功能支持与请求语义可能因 provider 而异。SDK 当前以尽力而为的 beta 集成方式包含 Any-LLM 和 LiteLLM。
+只有当 SDK 的内置 provider 集成点不够用时，才考虑使用第三方适配器。如果你在此 SDK 中仅使用 OpenAI 模型，请优先使用内置 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 路径，而不是 Any-LLM 或 LiteLLM。第三方适配器适用于你需要将 OpenAI 模型与非 OpenAI provider 组合，或需要适配器管理的 provider 覆盖或路由，而内置路径无法提供的情况。适配器会在 SDK 与上游模型 provider 之间增加另一层兼容层，因此功能支持和请求语义可能因 provider 而异。SDK 目前包含 Any-LLM 和 LiteLLM，作为尽力而为的 beta 适配器集成。
### Any-LLM
-Any-LLM 支持以尽力而为的 beta 形式提供，适用于你需要 Any-LLM 托管的 provider 覆盖或路由的场景。
+Any-LLM 支持以尽力而为的 beta 形式提供，适用于你需要 Any-LLM 管理的 provider 覆盖或路由的情况。
根据上游 provider 路径，Any-LLM 可能使用 Responses API、Chat Completions 兼容 API，或 provider 特定兼容层。
-如果你需要 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`，或在 run 范围使用 `AnyLLMProvider`。如果你需要显式固定模型接口，构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。
+如果你需要 Any-LLM，请安装 `openai-agents[any-llm]`，然后从 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 或 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) 开始。你可以将 `any-llm/...` 模型名称与 [`MultiProvider`][agents.MultiProvider] 搭配使用，直接实例化 `AnyLLMModel`，或在运行范围内使用 `AnyLLMProvider`。如果你需要显式固定模型接口，请在构造 `AnyLLMModel` 时传入 `api="responses"` 或 `api="chat_completions"`。
-Any-LLM 仍是第三方适配器层，因此 provider 依赖与能力缺口由 Any-LLM 上游定义，而非由 SDK 定义。当上游 provider 返回用量指标时会自动透传，但流式 Chat Completions 后端可能需要先设置 `ModelSettings(include_usage=True)` 才会输出 usage 块。如果你依赖 structured outputs、工具调用、用量上报或 Responses 特定行为，请验证计划部署的具体 provider 后端。
+Any-LLM 仍是第三方适配器层，因此 provider 依赖和能力差距由上游 Any-LLM 定义，而不是由 SDK 定义。当上游 provider 返回使用量指标时，它们会自动传播，但流式 Chat Completions 后端可能需要先设置 `ModelSettings(include_usage=True)` 才会发出使用量数据块。如果你依赖 structured outputs、工具调用、使用量报告或 Responses 特定行为，请验证你计划部署的确切 provider 后端。
### LiteLLM
-LiteLLM 支持以尽力而为的 beta 形式提供，适用于你需要 LiteLLM 特定 provider 覆盖或路由的场景。
+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，请安装 `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、工具调用、用量上报或适配器特定路由行为，请验证计划部署的具体 provider 后端。
\ No newline at end of file
+一些由 LiteLLM 支持的 provider 默认不会填充 SDK 使用量指标。如果你需要使用量报告，请传入 `ModelSettings(include_usage=True)`，并在依赖 structured outputs、工具调用、使用量报告或适配器特定路由行为时，验证你计划部署的确切 provider 后端。
\ No newline at end of file
diff --git a/docs/zh/results.md b/docs/zh/results.md
index e3e599b6bc..ea1d1af298 100644
--- a/docs/zh/results.md
+++ b/docs/zh/results.md
@@ -4,95 +4,95 @@ search:
---
# 结果
-当你调用 `Runner.run` 方法时，会收到两种结果类型之一：
+当你调用 `Runner.run` 方法时，会收到以下两种结果类型之一：
- 来自 `Runner.run(...)` 或 `Runner.run_sync(...)` 的 [`RunResult`][agents.result.RunResult]
- 来自 `Runner.run_streamed(...)` 的 [`RunResultStreaming`][agents.result.RunResultStreaming]
-两者都继承自 [`RunResultBase`][agents.result.RunResultBase]，后者提供共享的结果接口，例如 `final_output`、`new_items`、`last_agent`、`raw_responses` 和 `to_state()`。
+二者都继承自 [`RunResultBase`][agents.result.RunResultBase]，后者暴露共享的结果表面，例如 `final_output`、`new_items`、`last_agent`、`raw_responses` 和 `to_state()`。
-`RunResultStreaming` 增加了流式传输专用控制项，例如 [`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete] 和 [`cancel(...)`][agents.result.RunResultStreaming.cancel]。
+`RunResultStreaming` 添加了特定于流式传输的控制项，例如 [`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete] 和 [`cancel(...)`][agents.result.RunResultStreaming.cancel]。
-## 结果接口选择
+## 正确结果表面的选择
-大多数应用只需要少量结果属性或辅助方法：
+大多数应用只需要少数结果属性或辅助方法：
| 如果你需要... | 使用 |
| --- | --- |
| 展示给用户的最终答案 | `final_output` |
-| 可重放下一轮输入列表，包含完整本地转录 | `to_input_list()` |
-| 包含智能体、工具调用、任务转移和审批元数据的丰富运行项 | `new_items` |
+| 带有完整本地转录、可用于重放的下一轮输入列表 | `to_input_list()` |
+| 包含智能体、工具、任务转移和审批元数据的丰富运行项 | `new_items` |
| 通常应处理下一轮用户输入的智能体 | `last_agent` |
-| 使用 `previous_response_id` 进行 OpenAI Responses API 链式调用 | `last_response_id` |
-| 待处理审批和可恢复快照 | `interruptions` 和 `to_state()` |
-| 当前嵌套 `Agent.as_tool()` 调用的元数据 | `agent_tool_invocation` |
-| 原始模型调用或安全防护措施诊断 | `raw_responses` 和安全防护措施结果数组 |
+| 使用 `previous_response_id` 的 OpenAI Responses API 链接 | `last_response_id` |
+| 待审批项和可恢复快照 | `interruptions` 和 `to_state()` |
+| 关于当前嵌套 `Agent.as_tool()` 调用的元数据 | `agent_tool_invocation` |
+| 原始模型调用或安全防护措施诊断信息 | `raw_responses` 和安全防护措施结果数组 |
## 最终输出
-[`final_output`][agents.result.RunResultBase.final_output] 属性包含最后一个运行的智能体的最终输出。它可能是：
+[`final_output`][agents.result.RunResultBase.final_output] 属性包含最后运行的智能体的最终输出。它可能是：
-- `str`，如果最后一个智能体未定义 `output_type`
-- `last_agent.output_type` 类型的对象，如果最后一个智能体定义了输出类型
-- `None`，如果运行在产生最终输出前停止，例如因审批中断而暂停
+- `str`，如果最后的智能体没有定义 `output_type`
+- `last_agent.output_type` 类型的对象，如果最后的智能体定义了输出类型
+- `None`，如果运行在生成最终输出之前停止，例如因为在审批中断处暂停
!!! note
- `final_output` 的类型是 `Any`。任务转移可能改变哪个智能体完成运行，因此 SDK 无法在静态层面知道所有可能的输出类型集合。
+ `final_output` 的类型为 `Any`。任务转移可能会改变哪个智能体结束运行，因此 SDK 无法静态获知所有可能的输出类型。
-在流式模式下，`final_output` 在流处理完成前会一直保持为 `None`。事件级流程请参见 [流式传输](streaming.md)。
+在流式传输模式下，`final_output` 会保持为 `None`，直到流处理完成。有关逐事件流程，请参阅[流式传输](streaming.md)。
-## 输入、下一轮历史与新项
+## 输入、下一轮历史和新项
-这些接口回答的是不同问题：
+这些表面回答不同的问题：
-| 属性或辅助方法 | 包含内容 | 最适用场景 |
+| 属性或辅助方法 | 包含内容 | 最适合 |
| --- | --- | --- |
-| [`input`][agents.result.RunResultBase.input] | 此运行片段的基础输入。如果任务转移输入过滤器重写了历史，这里反映的是运行继续使用的过滤后输入。 | 审计本次运行实际使用的输入 |
-| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 运行的输入项视图。默认 `mode="preserve_all"` 会保留来自 `new_items` 的完整转换历史；`mode="normalized"` 在任务转移过滤重写模型历史时优先使用规范化续接输入。 | 手动聊天循环、客户端管理会话状态、纯输入项历史检查 |
-| [`new_items`][agents.result.RunResultBase.new_items] | 带智能体、工具调用、任务转移和审批元数据的丰富 [`RunItem`][agents.items.RunItem] 包装器。 | 日志、UI、审计与调试 |
-| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 本次运行中每次模型调用的原始 [`ModelResponse`][agents.items.ModelResponse] 对象。 | 提供方级诊断或原始响应检查 |
+| [`input`][agents.result.RunResultBase.input] | 此运行片段的基础输入。如果任务转移输入过滤器重写了历史，则这里反映运行继续使用的已过滤输入。 | 审计此运行实际使用的输入 |
+| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 运行的输入项视图。默认的 `mode="preserve_all"` 会保留从 `new_items` 转换而来的完整历史；`mode="normalized"` 会在任务转移过滤重写模型历史时优先使用规范的延续输入。 | 手动聊天循环、客户端管理的对话状态，以及普通项历史检查 |
+| [`new_items`][agents.result.RunResultBase.new_items] | 带有智能体、工具、任务转移和审批元数据的丰富 [`RunItem`][agents.items.RunItem] 包装器。 | 日志、UI、审计和调试 |
+| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 运行中每次模型调用产生的原始 [`ModelResponse`][agents.items.ModelResponse] 对象。 | 提供方级诊断或原始响应检查 |
-在实践中：
+实际使用中：
-- 当你需要运行的纯输入项视图时，使用 `to_input_list()`。
-- 当你在任务转移过滤或嵌套任务转移历史重写后，希望获得下一次 `Runner.run(..., input=...)` 调用的规范本地输入时，使用 `to_input_list(mode="normalized")`。
+- 当你想要运行的普通输入项视图时，使用 `to_input_list()`。
+- 当你想要在任务转移过滤或嵌套任务转移历史重写之后，用于下一次 `Runner.run(..., input=...)` 调用的规范本地输入时，使用 `to_input_list(mode="normalized")`。
- 当你希望 SDK 为你加载和保存历史时，使用 [`session=...`](sessions/index.md)。
-- 如果你在使用基于 `conversation_id` 或 `previous_response_id` 的 OpenAI 服务端托管状态，通常只需传入新的用户输入并复用已存储 ID，而不是重新发送 `to_input_list()`。
-- 当你需要用于日志、UI 或审计的完整转换历史时，使用默认 `to_input_list()` 模式或 `new_items`。
+- 如果你使用 OpenAI 服务端管理状态以及 `conversation_id` 或 `previous_response_id`，通常只传递新的用户输入并复用已存储的 ID，而不是重新发送 `to_input_list()`。
+- 当你需要用于日志、UI 或审计的完整转换历史时，使用默认的 `to_input_list()` 模式或 `new_items`。
-不同于 JavaScript SDK，Python 不会单独暴露仅包含模型形态增量的 `output` 属性。需要 SDK 元数据时使用 `new_items`，需要原始模型负载时检查 `raw_responses`。
+与 JavaScript SDK 不同，Python 不会为仅按模型形状表示的增量暴露单独的 `output` 属性。当你需要 SDK 元数据时使用 `new_items`，当你需要原始模型载荷时检查 `raw_responses`。
-计算机工具重放遵循原始 Responses 负载结构。预览模型的 `computer_call` 项会保留单个 `action`，而 `gpt-5.4` 计算机调用可保留批量 `actions[]`。[`to_input_list()`][agents.result.RunResultBase.to_input_list] 和 [`RunState`][agents.run_state.RunState] 会保留模型产生的任一结构，因此手动重放、暂停/恢复流程与存储转录在预览版和 GA 计算机工具调用之间都可持续工作。本地执行结果仍会作为 `computer_call_output` 项出现在 `new_items` 中。
+计算机工具重放遵循原始 Responses 载荷形状。预览模型的 `computer_call` 项会保留单个 `action`，而 `gpt-5.5` 计算机调用可以保留批量的 `actions[]`。[`to_input_list()`][agents.result.RunResultBase.to_input_list] 和 [`RunState`][agents.run_state.RunState] 会保留模型生成的任一形状，因此手动重放、暂停/恢复流程和已存储的转录可在预览版和 GA 计算机工具调用中继续工作。本地执行结果仍会在 `new_items` 中显示为 `computer_call_output` 项。
### 新项
-[`new_items`][agents.result.RunResultBase.new_items] 可为你提供此次运行中发生内容的最丰富视图。常见项类型包括：
+[`new_items`][agents.result.RunResultBase.new_items] 为你提供运行期间所发生事情的最丰富视图。常见项类型包括：
-- 助手消息的 [`MessageOutputItem`][agents.items.MessageOutputItem]
-- 推理项的 [`ReasoningItem`][agents.items.ReasoningItem]
-- Responses 工具检索请求与已加载工具检索结果的 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 和 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
-- 工具调用及其结果的 [`ToolCallItem`][agents.items.ToolCallItem] 和 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
-- 因审批而暂停的工具调用的 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
-- 任务转移请求与已完成转移的 [`HandoffCallItem`][agents.items.HandoffCallItem] 和 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
+- 用于助手消息的 [`MessageOutputItem`][agents.items.MessageOutputItem]
+- 用于推理项的 [`ReasoningItem`][agents.items.ReasoningItem]
+- 用于 Responses 工具检索请求和已加载工具检索结果的 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 和 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
+- 用于工具调用及其结果的 [`ToolCallItem`][agents.items.ToolCallItem] 和 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
+- 用于因审批而暂停的工具调用的 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
+- 用于任务转移请求和已完成转移的 [`HandoffCallItem`][agents.items.HandoffCallItem] 和 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
-当你需要智能体关联、工具输出、任务转移边界或审批边界时，应优先选择 `new_items` 而不是 `to_input_list()`。
+每当你需要智能体关联、工具输出、任务转移边界或审批边界时，请选择 `new_items`，而不是 `to_input_list()`。
-当你使用托管工具检索时，检查 `ToolSearchCallItem.raw_item` 可查看模型发出的检索请求，检查 `ToolSearchOutputItem.raw_item` 可查看该轮加载了哪些命名空间、函数或托管 MCP 服务。
+当你使用托管工具检索时，检查 `ToolSearchCallItem.raw_item` 可查看模型发出的检索请求，检查 `ToolSearchOutputItem.raw_item` 可查看本轮加载了哪些命名空间、函数或托管 MCP 服务。
-## 会话续接或恢复
+## 对话的继续或恢复
### 下一轮智能体
-[`last_agent`][agents.result.RunResultBase.last_agent] 包含最后一个运行的智能体。在任务转移之后，这通常是下一轮用户输入最适合复用的智能体。
+[`last_agent`][agents.result.RunResultBase.last_agent] 包含最后运行的智能体。在任务转移之后，这通常是下一轮用户输入中最适合复用的智能体。
-在流式模式下，[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] 会随着运行进展更新，因此你可以在流结束前观察任务转移。
+在流式传输模式下，[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] 会随着运行推进而更新，因此你可以在流结束之前观察任务转移。
-### 中断与运行状态
+### 中断和运行状态
-如果某个工具需要审批，待处理审批会暴露在 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 或 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 中。这可能包括由直接工具、任务转移后到达的工具，或嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行触发的审批。
+如果工具需要审批，待审批项会通过 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 或 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 暴露出来。这可能包括由直接工具、任务转移后到达的工具，或嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行提出的审批。
-调用 [`to_state()`][agents.result.RunResult.to_state] 可捕获可恢复的 [`RunState`][agents.run_state.RunState]，对待处理项执行批准或拒绝，然后通过 `Runner.run(...)` 或 `Runner.run_streamed(...)` 恢复运行。
+调用 [`to_state()`][agents.result.RunResult.to_state] 以捕获可恢复的 [`RunState`][agents.run_state.RunState]，批准或拒绝待处理项，然后使用 `Runner.run(...)` 或 `Runner.run_streamed(...)` 恢复。
```python
from agents import Agent, Runner
@@ -107,59 +107,59 @@ if result.interruptions:
result = await Runner.run(agent, state)
```
-对于流式运行，先完成对 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 的消费，再检查 `result.interruptions` 并从 `result.to_state()` 恢复。完整审批流程请参见 [Human-in-the-loop](human_in_the_loop.md)。
+对于流式传输运行，请先消费完 [`stream_events()`][agents.result.RunResultStreaming.stream_events]，然后检查 `result.interruptions` 并从 `result.to_state()` 恢复。完整审批流程请参阅[人在环路](human_in_the_loop.md)。
-### 服务端托管续接
+### 服务端管理的延续
-[`last_response_id`][agents.result.RunResultBase.last_response_id] 是此次运行中最新的模型响应 ID。当你希望续接 OpenAI Responses API 链时，在下一轮将其作为 `previous_response_id` 传回。
+[`last_response_id`][agents.result.RunResultBase.last_response_id] 是运行中的最新模型响应 ID。当你想继续 OpenAI Responses API 链时，在下一轮将它作为 `previous_response_id` 传回。
-如果你已经通过 `to_input_list()`、`session` 或 `conversation_id` 续接会话，通常不需要 `last_response_id`。如果你需要多步骤运行中的每个模型响应，请改为检查 `raw_responses`。
+如果你已经通过 `to_input_list()`、`session` 或 `conversation_id` 继续对话，通常不需要 `last_response_id`。如果你需要多步骤运行中的每个模型响应，请改为检查 `raw_responses`。
## Agent-as-tool 元数据
-当结果来自嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行时，[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] 会暴露外层工具调用的不可变元数据：
+当结果来自嵌套 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 运行时，[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] 会暴露关于外层工具调用的不可变元数据：
- `tool_name`
- `tool_call_id`
- `tool_arguments`
-对于普通顶层运行，`agent_tool_invocation` 为 `None`。
+对于普通的顶层运行，`agent_tool_invocation` 为 `None`。
-这在 `custom_output_extractor` 中尤其有用，你可能需要在后处理嵌套结果时访问外层工具名、调用 ID 或原始参数。有关周边 `Agent.as_tool()` 模式，请参见 [工具](tools.md)。
+这在 `custom_output_extractor` 内尤其有用，你可能需要在对嵌套结果进行后处理时使用外层工具名称、调用 ID 或原始参数。有关周边的 `Agent.as_tool()` 模式，请参阅[工具](tools.md)。
-如果你还需要该嵌套运行已解析的结构化输入，请读取 `context_wrapper.tool_input`。这是 [`RunState`][agents.run_state.RunState] 用于泛化序列化嵌套工具输入的字段，而 `agent_tool_invocation` 是当前嵌套调用的实时结果访问器。
+如果你还需要该嵌套运行的已解析结构化输入，请读取 `context_wrapper.tool_input`。这是 [`RunState`][agents.run_state.RunState] 用于通用序列化嵌套工具输入的字段，而 `agent_tool_invocation` 是当前嵌套调用的实时结果访问器。
-## 流式传输生命周期与诊断
+## 流式传输生命周期和诊断
-[`RunResultStreaming`][agents.result.RunResultStreaming] 继承了上述相同结果接口，并增加流式传输专用控制项：
+[`RunResultStreaming`][agents.result.RunResultStreaming] 继承上文相同的结果表面，但添加了特定于流式传输的控制项：
-- 使用 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 消费语义流事件
-- 使用 [`current_agent`][agents.result.RunResultStreaming.current_agent] 在运行中跟踪当前活跃智能体
-- 使用 [`is_complete`][agents.result.RunResultStreaming.is_complete] 查看流式运行是否已完全结束
-- 使用 [`cancel(...)`][agents.result.RunResultStreaming.cancel] 立即停止运行或在当前轮次后停止
+- [`stream_events()`][agents.result.RunResultStreaming.stream_events] 用于消费语义流事件
+- [`current_agent`][agents.result.RunResultStreaming.current_agent] 用于在运行中途跟踪活动智能体
+- [`is_complete`][agents.result.RunResultStreaming.is_complete] 用于查看流式运行是否已完全结束
+- [`cancel(...)`][agents.result.RunResultStreaming.cancel] 用于立即停止运行，或在当前轮次后停止运行
-持续消费 `stream_events()`，直到异步迭代器结束。只有当该迭代器结束时，流式运行才算完成；像 `final_output`、`interruptions`、`raw_responses` 以及会话持久化副作用等汇总属性，在最后一个可见 token 到达后仍可能处于收敛过程中。
+持续消费 `stream_events()`，直到异步迭代器结束。流式传输运行只有在该迭代器结束后才算完成，并且在最后一个可见 token 到达后，`final_output`、`interruptions`、`raw_responses` 等摘要属性以及会话持久化副作用可能仍在收尾。
-如果你调用了 `cancel()`，请继续消费 `stream_events()`，以便取消与清理流程正确完成。
+如果你调用 `cancel()`，请继续消费 `stream_events()`，以便取消和清理能够正确完成。
-Python 不会单独暴露流式 `completed` promise 或 `error` 属性。终态流式失败会通过 `stream_events()` 抛出异常，`is_complete` 则反映运行是否已到达终态。
+Python 不会暴露单独的流式 `completed` promise 或 `error` 属性。终止性流式传输失败会通过 `stream_events()` 抛出异常来呈现，而 `is_complete` 反映运行是否已达到其终止状态。
### 原始响应
-[`raw_responses`][agents.result.RunResultBase.raw_responses] 包含运行期间收集的原始模型响应。多步骤运行可能产生多个响应，例如在任务转移或重复的模型/工具/模型循环中。
+[`raw_responses`][agents.result.RunResultBase.raw_responses] 包含运行期间收集的原始模型响应。多步骤运行可能会产生多个响应，例如跨任务转移或重复的模型/工具/模型循环。
-[`last_response_id`][agents.result.RunResultBase.last_response_id] 仅是 `raw_responses` 最后一项的 ID。
+[`last_response_id`][agents.result.RunResultBase.last_response_id] 只是 `raw_responses` 中最后一个条目的 ID。
### 安全防护措施结果
智能体级安全防护措施通过 [`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] 和 [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] 暴露。
-工具级安全防护措施则通过 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 和 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] 单独暴露。
+工具安全防护措施则分别通过 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 和 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] 暴露。
-这些数组会在整个运行中持续累积，因此适合用于记录决策、存储额外的安全防护措施元数据，或调试运行被阻止的原因。
+这些数组会在整个运行过程中累积，因此它们对记录决策、存储额外的安全防护措施元数据，或调试运行为何被阻止很有用。
-### 上下文与用量
+### 上下文和用量
-[`context_wrapper`][agents.result.RunResultBase.context_wrapper] 会暴露你的应用上下文，以及由 SDK 管理的运行时元数据（如审批、用量和嵌套 `tool_input`）。
+[`context_wrapper`][agents.result.RunResultBase.context_wrapper] 会将你的应用上下文与 SDK 管理的运行时元数据一起暴露，例如审批、用量和嵌套 `tool_input`。
-用量记录在 `context_wrapper.usage` 上。对于流式运行，用量总计可能会滞后，直到流的最终分块处理完毕。完整包装器结构及持久化注意事项请参见 [上下文管理](context.md)。
\ No newline at end of file
+用量会在 `context_wrapper.usage` 上跟踪。对于流式传输运行，在流的最终分块处理完成之前，用量总计可能会滞后。有关完整包装器形状和持久化注意事项，请参阅[上下文管理](context.md)。
\ No newline at end of file
diff --git a/docs/zh/sandbox/guide.md b/docs/zh/sandbox/guide.md
index 3532a82a42..6b7702f13e 100644
--- a/docs/zh/sandbox/guide.md
+++ b/docs/zh/sandbox/guide.md
@@ -6,35 +6,35 @@ search:
!!! warning "Beta 功能"
- Sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认值和支持的能力在正式可用之前都会发生变化，并且功能也会随着时间推移变得更高级。
+ 沙盒智能体处于 beta 阶段。在正式可用之前，API、默认设置和受支持能力的细节预计会发生变化，并且会随着时间推移提供更高级的功能。
-现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。**Sandbox 智能体**可以使用专门的工具和 shell 命令，在大型文档集合上执行检索和操作、编辑文件、生成产物以及运行命令。sandbox 为模型提供了一个持久化工作区，智能体可以利用它代表你执行工作。Agents SDK 中的 Sandbox 智能体可帮助你轻松运行与 sandbox 环境配对的智能体，从而更方便地将正确的文件放入文件系统，并编排 sandboxes，以便大规模地轻松启动、停止和恢复任务。
+现代智能体在能够操作文件系统中的真实文件时效果最佳。**沙盒智能体**可以使用专门的工具和 shell 命令来搜索和操作大型文档集、编辑文件、生成产物以及运行命令。沙盒为模型提供了一个持久化工作区，智能体可以用它代表你完成工作。Agents SDK 中的沙盒智能体可帮助你轻松运行与沙盒环境配对的智能体，从而轻松将正确的文件放到文件系统中，并编排沙盒，使大规模启动、停止和恢复任务变得简单。
-你可以围绕智能体所需的数据来定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、诸如 S3 或 Azure Blob Storage 之类的远程文件系统，以及你提供的其他 sandbox 输入开始。
+你围绕智能体所需的数据来定义工作区。它可以从 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及你提供的其他沙盒输入开始。
-
+
-`SandboxAgent` 仍然是一个 `Agent`。它保留了常规的智能体接口，例如 `instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍然通过常规的 `Runner` API 运行。变化之处在于执行边界：
+`SandboxAgent` 仍然是一个 `Agent`。它保留了常规智能体表面，例如 `instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、安全防护措施和 hooks，并且仍通过常规 `Runner` API 运行。变化的是执行边界：
-- `SandboxAgent` 定义智能体本身：常规的智能体配置，加上 sandbox 专属默认值，例如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、skills、memory 或 compaction 等能力。
-- `Manifest` 声明一个全新 sandbox 工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。
-- sandbox session 是命令运行和文件发生变化的实时隔离环境。
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定该次运行如何获得该 sandbox session，例如直接注入一个 session、从序列化的 sandbox session 状态重连，或通过 sandbox client 创建一个新的 sandbox session。
-- 已保存的 sandbox 状态和快照允许后续运行重新连接到先前的工作，或用保存的内容为新的 sandbox session 提供初始内容。
+- `SandboxAgent` 定义智能体本身：常规智能体配置，加上沙盒特定的默认值，例如 `default_manifest`、`base_instructions`、`run_as`，以及文件系统工具、shell 访问、技能、内存或压缩等能力。
+- `Manifest` 声明全新沙盒工作区所需的起始内容和布局，包括文件、仓库、挂载和环境。
+- 沙盒会话是运行命令并发生文件变更的实时隔离环境。
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 决定本次运行如何获取该沙盒会话，例如直接注入一个会话、从序列化的沙盒会话状态重新连接，或通过沙盒客户端创建一个新的沙盒会话。
+- 保存的沙盒状态和快照允许后续运行重新连接到之前的工作，或从保存的内容为新的沙盒会话播种。
-`Manifest` 是全新 session 工作区的契约，而不是每个实时 sandbox 的完整事实来源。一次运行的实际工作区也可能来自复用的 sandbox session、序列化的 sandbox session 状态，或在运行时选择的快照。
+`Manifest` 是全新会话的工作区契约，而不是每个实时沙盒完整的事实来源。一次运行的有效工作区也可以来自复用的沙盒会话、序列化的沙盒会话状态，或运行时选择的快照。
-在本页中，“sandbox session”指的是由 sandbox client 管理的实时执行环境。它不同于 [Sessions](../sessions/index.md) 中描述的 SDK 对话式 [`Session`][agents.memory.session.Session] 接口。
+在本页中，“沙盒会话”指由沙盒客户端管理的实时执行环境。它不同于[会话](../sessions/index.md)中描述的 SDK 会话式 [`Session`][agents.memory.session.Session] 接口。
-外层运行时仍然负责 approvals、追踪、任务转移和恢复记录。sandbox session 负责命令、文件变更和环境隔离。这种划分是该模型的核心部分。
+外层运行时仍然拥有审批、追踪、任务转移和恢复簿记。沙盒会话拥有命令、文件变更和环境隔离。这种拆分是该模型的核心部分。
-### 组件协作方式
+### 组件关系
-一次 sandbox 运行将智能体定义与每次运行的 sandbox 配置结合起来。runner 会准备智能体，将其绑定到一个实时 sandbox session，并且可以为后续运行保存状态。
+沙盒运行会将智能体定义与每次运行的沙盒配置组合起来。运行器准备智能体，将其绑定到实时沙盒会话，并且可以保存状态以供后续运行使用。
```mermaid
flowchart LR
@@ -50,33 +50,33 @@ flowchart LR
sandbox --> saved
```
-sandbox 专属默认值保留在 `SandboxAgent` 上。每次运行的 sandbox-session 选择保留在 `SandboxRunConfig` 中。
+沙盒特定的默认值保留在 `SandboxAgent` 上。每次运行的沙盒会话选择保留在 `SandboxRunConfig` 中。
-可以将生命周期理解为三个阶段：
+可以把生命周期看作三个阶段：
-1. 使用 `SandboxAgent`、`Manifest` 和能力来定义智能体及全新工作区契约。
-2. 通过向 `Runner` 提供一个 `SandboxRunConfig` 来执行运行，以注入、恢复或创建 sandbox session。
-3. 稍后从 runner 管理的 `RunState`、显式的 sandbox `session_state` 或已保存的工作区快照继续。
+1. 使用 `SandboxAgent`、`Manifest` 和能力定义智能体以及全新工作区契约。
+2. 通过向 `Runner` 提供一个会注入、恢复或创建沙盒会话的 `SandboxRunConfig` 来执行运行。
+3. 之后从运行器管理的 `RunState`、显式沙盒 `session_state`，或保存的工作区快照继续。
-如果 shell 访问只是一个偶尔使用的工具，请从 [工具指南](../tools.md) 中的 hosted shell 开始。当工作区隔离、sandbox client 选择或 sandbox-session 恢复行为本身就是设计的一部分时，再使用 sandbox 智能体。
+如果 shell 访问只是一个偶尔使用的工具，请从[工具指南](../tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。
-## 适用场景
+## 使用场景
-Sandbox 智能体非常适合以工作区为中心的工作流，例如：
+沙盒智能体非常适合以工作区为中心的工作流，例如：
-- 编码和调试，例如在 GitHub 仓库中编排针对 issue 报告的自动修复并运行有针对性的测试
-- 文档处理与编辑，例如从用户的财务文件中提取信息并创建一份填写完成的税表草稿
-- 基于文件的审查或分析，例如在回答之前检查入职材料包、生成的报告或产物包
-- 隔离的多智能体模式，例如为每个审查员或编码子智能体分配各自的工作区
-- 多步骤工作区任务，例如在一次运行中修复 bug，稍后再添加回归测试，或从快照或 sandbox session 状态恢复
+- 编码和调试，例如为 GitHub 仓库中的问题报告编排自动修复并运行定向测试
+- 文档处理和编辑，例如从用户的财务文档中提取信息并创建已填写的税务表单草稿
+- 基于文件的审查或分析，例如在回答前检查入职资料包、生成的报告或产物包
+- 隔离的多智能体模式，例如为每个审阅者或编码子智能体提供自己的工作区
+- 多步骤工作区任务，例如在一次运行中修复 bug，稍后添加回归测试，或从快照或沙盒会话状态恢复
-如果你不需要访问文件或一个活动中的文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加 hosted shell；如果工作区边界本身就是功能的一部分，请使用 sandbox 智能体。
+如果你不需要访问文件或实时文件系统，请继续使用 `Agent`。如果 shell 访问只是偶尔需要的一项能力，请添加托管 shell；如果工作区边界本身就是功能的一部分，请使用沙盒智能体。
-## sandbox client 选择
+## 沙盒客户端选择
-本地开发时从 `UnixLocalSandboxClient` 开始。当你需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当你需要由提供方管理执行环境时，切换到托管提供方。
+本地开发从 `UnixLocalSandboxClient` 开始。当需要容器隔离或镜像一致性时，切换到 `DockerSandboxClient`。当需要由提供商管理的执行时，切换到托管提供商。
-在大多数情况下，`SandboxAgent` 定义保持不变，而 sandbox client 及其选项在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参见 [Sandbox clients](clients.md)。
+在大多数情况下，`SandboxAgent` 定义保持不变，而沙盒客户端及其选项会在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中变化。有关本地、Docker、托管和远程挂载选项，请参阅[沙盒客户端](clients.md)。
## 核心组件
@@ -84,167 +84,167 @@ Sandbox 智能体非常适合以工作区为中心的工作流，例如：
| 层级 | 主要 SDK 组件 | 回答的问题 |
| --- | --- | --- |
-| 智能体定义 | `SandboxAgent`、`Manifest`、capabilities | 将运行什么智能体，以及它应从什么样的全新 session 工作区契约开始？ |
-| Sandbox 执行 | `SandboxRunConfig`、sandbox client 和实时 sandbox session | 此次运行如何获得一个实时 sandbox session，工作在哪里执行？ |
-| 已保存的 sandbox 状态 | `RunState` sandbox payload、`session_state` 和 snapshots | 此工作流如何重新连接到之前的 sandbox 工作，或从已保存内容为新的 sandbox session 提供初始内容？ |
+| 智能体定义 | `SandboxAgent`、`Manifest`、能力 | 将运行什么智能体，它应该从什么全新会话工作区契约开始？ |
+| 沙盒执行 | `SandboxRunConfig`、沙盒客户端和实时沙盒会话 | 本次运行如何获得实时沙盒会话，工作在哪里执行？ |
+| 保存的沙盒状态 | `RunState` 沙盒载荷、`session_state` 和快照 | 此工作流如何重新连接到之前的沙盒工作，或从保存的内容为新的沙盒会话播种？ |
-主要 SDK 组件与这些层级的对应关系如下：
+主要 SDK 组件对应这些层级如下：
-| 组件 | 负责内容 | 请问这个问题 |
+| 组件 | 拥有的内容 | 要问的问题 |
| --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应随其一同携带？ |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新 session 工作区文件和文件夹 | 运行开始时，文件系统中应存在哪些文件和文件夹？ |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | sandbox 原生行为 | 哪些工具、instruction 片段或运行时行为应附加到此智能体？ |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 每次运行的 sandbox client 和 sandbox-session 来源 | 此次运行应注入、恢复，还是创建一个 sandbox session？ |
-| [`RunState`][agents.run_state.RunState] | runner 管理的已保存 sandbox 状态 | 我是否正在恢复一个先前由 runner 管理的工作流，并自动延续其 sandbox 状态？ |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的 sandbox session 状态 | 我是否希望从已经在 `RunState` 之外序列化的 sandbox 状态恢复？ |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新 sandbox sessions 的已保存工作区内容 | 新的 sandbox session 是否应从已保存文件和产物开始？ |
+| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 智能体定义 | 这个智能体应该做什么，哪些默认值应该随它一起传递？ |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 全新会话工作区文件和文件夹 | 运行开始时，文件系统上应该有哪些文件和文件夹？ |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 沙盒原生行为 | 哪些工具、指令片段或运行时行为应该附加到这个智能体？ |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 每次运行的沙盒客户端和沙盒会话来源 | 本次运行应该注入、恢复还是创建沙盒会话？ |
+| [`RunState`][agents.run_state.RunState] | 运行器管理的已保存沙盒状态 | 我是否正在恢复之前由运行器管理的工作流，并自动延续其沙盒状态？ |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 显式序列化的沙盒会话状态 | 我是否想从已经在 `RunState` 之外序列化的沙盒状态恢复？ |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 用于全新沙盒会话的已保存工作区内容 | 新的沙盒会话是否应该从保存的文件和产物开始？ |
-一个实用的设计顺序是：
+实用的设计顺序是：
-1. 用 `Manifest` 定义全新 session 工作区契约。
-2. 用 `SandboxAgent` 定义智能体。
+1. 使用 `Manifest` 定义全新会话工作区契约。
+2. 使用 `SandboxAgent` 定义智能体。
3. 添加内置或自定义能力。
-4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其 sandbox session。
+4. 在 `RunConfig(sandbox=SandboxRunConfig(...))` 中决定每次运行应如何获取其沙盒会话。
-## sandbox 运行的准备方式
+## 沙盒运行的准备方式
-在运行时，runner 会将该定义转换为一次具体的、由 sandbox 支持的运行：
+运行时，运行器会将该定义转化为具体的沙盒支持运行：
-1. 它从 `SandboxRunConfig` 解析 sandbox session。
- 如果你传入 `session=...`，它会复用该实时 sandbox session。
- 否则，它会使用 `client=...` 来创建或恢复一个。
-2. 它确定该次运行的实际工作区输入。
- 如果运行注入或恢复了一个 sandbox session，则现有的 sandbox 状态优先生效。
- 否则，runner 会从一次性的 manifest 覆盖或 `agent.default_manifest` 开始。
- 这就是为什么仅有 `Manifest` 并不能定义每次运行的最终实时工作区。
-3. 它让 capabilities 处理生成的 manifest。
- 这样 capabilities 就可以在最终智能体准备完成之前，添加文件、挂载或其他作用于工作区范围的行为。
+1. 它从 `SandboxRunConfig` 解析沙盒会话。
+ 如果你传入 `session=...`，它会复用该实时沙盒会话。
+ 否则它会使用 `client=...` 创建或恢复一个会话。
+2. 它确定本次运行的有效工作区输入。
+ 如果运行注入或恢复了沙盒会话，则现有沙盒状态优先。
+ 否则运行器会从一次性的 manifest 覆盖或 `agent.default_manifest` 开始。
+ 这就是为什么仅靠 `Manifest` 并不能定义每次运行最终的实时工作区。
+3. 它让能力处理生成的 manifest。
+ 这使能力能够在最终智能体准备好之前添加文件、挂载或其他工作区范围的行为。
4. 它按固定顺序构建最终 instructions：
- SDK 的默认 sandbox 提示词，或如果你显式覆盖则使用 `base_instructions`，然后是 `instructions`，接着是 capability instruction 片段，再是任何远程挂载策略文本，最后是渲染后的文件系统树。
-5. 它将 capability 工具绑定到实时 sandbox session，并通过常规 `Runner` API 运行已准备好的智能体。
+ SDK 默认沙盒提示词，或你显式覆盖时的 `base_instructions`，然后是 `instructions`，再是能力指令片段，然后是任何远程挂载策略文本，最后是渲染后的文件系统树。
+5. 它将能力工具绑定到实时沙盒会话，并通过常规 `Runner` API 运行已准备好的智能体。
-Sandboxing 不会改变一个 turn 的含义。turn 仍然是一个模型步骤，而不是单个 shell 命令或 sandbox 动作。sandbox 侧操作与 turn 之间并不存在固定的一对一映射：有些工作可能停留在 sandbox 执行层内部，而其他动作会返回工具结果、approvals 或其他需要再进行一次模型步骤的状态。实践上，只有当智能体运行时在 sandbox 工作发生后还需要另一个模型响应时，才会消耗另一个 turn。
+沙盒化不会改变一个轮次的含义。轮次仍然是一个模型步骤，而不是单个 shell 命令或沙盒操作。沙盒侧操作和轮次之间没有固定的 1:1 映射：有些工作可能留在沙盒执行层内，而其他操作会返回工具结果、审批或其他需要另一个模型步骤的状态。作为实用规则，只有当智能体运行时在沙盒工作发生后需要另一个模型响应时，才会消耗另一个轮次。
-这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是主要需要考虑的 sandbox 专属选项。
+这些准备步骤说明了为什么在设计 `SandboxAgent` 时，`default_manifest`、`instructions`、`base_instructions`、`capabilities` 和 `run_as` 是需要考虑的主要沙盒特定选项。
## `SandboxAgent` 选项
-这些是在常规 `Agent` 字段之外的 sandbox 专属选项：
+这些是在常规 `Agent` 字段之上的沙盒特定选项：
| 选项 | 最佳用途 |
| --- | --- |
-| `default_manifest` | 由 runner 创建的全新 sandbox sessions 的默认工作区。 |
-| `instructions` | 追加在 SDK sandbox 提示词之后的额外角色、工作流和成功标准。 |
-| `base_instructions` | 用于替换 SDK sandbox 提示词的高级逃生舱口。 |
-| `capabilities` | 应随此智能体携带的 sandbox 原生工具和行为。 |
-| `run_as` | 面向模型的 sandbox 工具（如 shell 命令、文件读取和 patch）所使用的用户身份。 |
+| `default_manifest` | 由运行器创建的全新沙盒会话的默认工作区。 |
+| `instructions` | 附加在 SDK 沙盒提示词之后的额外角色、工作流和成功标准。 |
+| `base_instructions` | 替换 SDK 沙盒提示词的高级逃生舱。 |
+| `capabilities` | 应随此智能体一起传递的沙盒原生工具和行为。 |
+| `run_as` | 面向模型的沙盒工具（例如 shell 命令、文件读取和补丁）的用户身份。 |
-sandbox client 选择、sandbox-session 复用、manifest 覆盖和快照选择属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体本身。
+沙盒客户端选择、沙盒会话复用、manifest 覆盖和快照选择属于 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]，而不是智能体。
### `default_manifest`
-`default_manifest` 是当 runner 为此智能体创建一个全新 sandbox session 时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。应将它用于智能体通常应具备的文件、仓库、辅助材料、输出目录和挂载。
+`default_manifest` 是运行器为此智能体创建全新沙盒会话时使用的默认 [`Manifest`][agents.sandbox.manifest.Manifest]。将它用于智能体通常应从中开始的文件、仓库、辅助材料、输出目录和挂载。
-这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而一个复用或恢复的 sandbox session 会保留其现有工作区状态。
+这只是默认值。一次运行可以通过 `SandboxRunConfig(manifest=...)` 覆盖它，而复用或恢复的沙盒会话会保留其现有工作区状态。
### `instructions` 和 `base_instructions`
-将 `instructions` 用于应跨不同提示词保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会追加在 SDK 的 sandbox 基础提示词之后，因此你可以保留内置的 sandbox 指引，并添加自己的角色、工作流和成功标准。
+将 `instructions` 用于应在不同提示词中保留的简短规则。在 `SandboxAgent` 中，这些 instructions 会附加在 SDK 的沙盒基础提示词之后，因此你会保留内置沙盒指导，并添加自己的角色、工作流和成功标准。
-只有当你想替换 SDK sandbox 基础提示词时，才使用 `base_instructions`。大多数智能体都不应设置它。
+仅当你想替换 SDK 沙盒基础提示词时，才使用 `base_instructions`。大多数智能体不应设置它。
-| 放在...中 | 用途 | 示例 |
+| 放在... | 用途 | 示例 |
| --- | --- | --- |
-| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后执行任务转移。”, “将最终文件写入 `output/`。” |
-| `base_instructions` | 完整替换 SDK sandbox 基础提示词。 | 自定义的底层 sandbox 包装提示词。 |
-| 用户提示词 | 此次运行的一次性请求。 | “总结这个工作区。” |
-| manifest 中的工作区文件 | 更长的任务规范、仓库本地 instructions 或有界的参考材料。 | `repo/task.md`、文档包、示例材料包。 |
+| `instructions` | 智能体的稳定角色、工作流规则和成功标准。 | “检查入职文档，然后任务转移。”、“将最终文件写入 `output/`。” |
+| `base_instructions` | SDK 沙盒基础提示词的完整替换。 | 自定义低层沙盒包装提示词。 |
+| 用户提示词 | 本次运行的一次性请求。 | “总结此工作区。” |
+| manifest 中的工作区文件 | 更长的任务规范、仓库本地指令或有边界的参考材料。 | `repo/task.md`、文档包、示例资料包。 |
`instructions` 的良好用法包括：
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态很重要时，让智能体保持在单个交互式进程中。
-- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) 禁止 sandbox 审查智能体在检查后直接回答用户。
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写完成的文件实际落在 `output/` 中。
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定了精确的验证命令，并澄清了相对于工作区根目录的 patch 路径。
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) 在 PTY 状态重要时，让智能体保持在一个交互式进程中。
+- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) 禁止沙盒审阅者在检查后直接回答用户。
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) 要求最终填写好的文件实际落在 `output/` 中。
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 固定精确的验证命令，并明确相对于工作区根目录的补丁路径。
-避免将用户的一次性任务复制到 `instructions` 中、嵌入应放在 manifest 中的长参考材料、重复内置 capabilities 已经注入的工具文档，或混入模型在运行时并不需要的本地安装说明。
+避免将用户的一次性任务复制到 `instructions` 中，避免嵌入应属于 manifest 的长参考材料，避免重述内置能力已经注入的工具文档，也避免混入模型在运行时不需要的本地安装说明。
-如果你省略 `instructions`，SDK 仍会包含默认 sandbox 提示词。对于低层封装器来说这已经足够，但大多数面向用户的智能体仍应提供明确的 `instructions`。
+如果省略 `instructions`，SDK 仍会包含默认沙盒提示词。这对于低层包装器已经足够，但大多数面向用户的智能体仍应提供显式 `instructions`。
### `capabilities`
-Capabilities 会将 sandbox 原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区、追加 sandbox 专属 instructions、暴露绑定到实时 sandbox session 的工具，并为该智能体调整模型行为或输入处理方式。
+能力会将沙盒原生行为附加到 `SandboxAgent`。它们可以在运行开始前塑造工作区，附加沙盒特定指令，公开绑定到实时沙盒会话的工具，并调整该智能体的模型行为或输入处理。
-内置 capabilities 包括：
+内置能力包括：
-| Capability | 适用场景 | 说明 |
+| 能力 | 添加时机 | 备注 |
| --- | --- | --- |
-| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，并在 sandbox client 支持 PTY 交互时添加 `write_stdin`。 |
-| `Filesystem` | 智能体需要编辑文件或检查本地图片。 | 添加 `apply_patch` 和 `view_image`；patch 路径相对于工作区根目录。 |
-| `Skills` | 你希望在 sandbox 中进行 skill 发现和具体化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你在 sandbox 中索引并具体化 skills。 |
-| `Memory` | 后续运行应读取或生成 memory 产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
-| `Compaction` | 长时间运行的流程需要在 compaction 项之后裁剪上下文。 | 会调整模型采样和输入处理。 |
+| `Shell` | 智能体需要 shell 访问。 | 添加 `exec_command`，并在沙盒客户端支持 PTY 交互时添加 `write_stdin`。 |
+| `Filesystem` | 智能体需要编辑文件或检查本地图像。 | 添加 `apply_patch` 和 `view_image`；补丁路径相对于工作区根目录。 |
+| `Skills` | 你想在沙盒中进行技能发现和物化。 | 优先使用它，而不是手动挂载 `.agents` 或 `.agents/skills`；`Skills` 会为你将技能索引并物化到沙盒中。 |
+| `Memory` | 后续运行应读取或生成记忆产物。 | 需要 `Shell`；实时更新还需要 `Filesystem`。 |
+| `Compaction` | 长时间运行的流程需要在压缩项之后裁剪上下文。 | 调整模型采样和输入处理。 |
-默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍然需要的任何默认 capability。
+默认情况下，`SandboxAgent.capabilities` 使用 `Capabilities.default()`，其中包括 `Filesystem()`、`Shell()` 和 `Compaction()`。如果你传入 `capabilities=[...]`，该列表会替换默认值，因此请包含你仍然想要的任何默认能力。
-对于 skills，请根据你希望其被具体化的方式选择来源：
+对于技能，请根据你希望它们如何物化来选择来源：
-- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大的本地 skill 目录的一个良好默认选项，因为模型可以先发现索引，再仅加载所需内容。
-- `LocalDirLazySkillSource(source=LocalDir(src=...))` 会从运行 SDK 进程的文件系统中读取。请传入宿主机侧原始 skills 目录，而不是只存在于 sandbox 镜像或工作区中的路径。
-- `Skills(from_=LocalDir(src=...))` 更适合你希望预先准备好的小型本地 bundle。
-- `Skills(from_=GitRepo(repo=..., ref=...))` 适用于 skills 本身应来自某个仓库的场景。
+- `Skills(lazy_from=LocalDirLazySkillSource(...))` 是较大本地技能目录的良好默认选择，因为模型可以先发现索引，只加载所需内容。
+- `LocalDirLazySkillSource(source=LocalDir(src=...))` 从运行 SDK 进程所在的文件系统读取。传入原始的主机侧技能目录，而不是仅存在于沙盒镜像或工作区内部的路径。
+- `Skills(from_=LocalDir(src=...))` 更适合你希望预先暂存的小型本地包。
+- `Skills(from_=GitRepo(repo=..., ref=...))` 适合技能本身应来自仓库的情况。
-`LocalDir.src` 是 SDK 宿主机上的源路径。`skills_path` 是调用 `load_skill` 时，skills 在 sandbox 工作区内准备到的相对目标路径。
+`LocalDir.src` 是 SDK 主机上的源路径。`skills_path` 是沙盒工作区内部的相对目标路径，在调用 `load_skill` 时技能会被暂存到那里。
-如果你的 skills 已经以类似 `.agents/skills//SKILL.md` 的结构存在于磁盘上，请将 `LocalDir(...)` 指向该源根目录，并仍然使用 `Skills(...)` 来暴露它们。保留默认的 `skills_path=".agents"`，除非你已有依赖不同 sandbox 内布局的现有工作区契约。
+如果你的技能已经在磁盘上位于类似 `.agents/skills//SKILL.md` 的位置，请将 `LocalDir(...)` 指向该源根目录，并仍使用 `Skills(...)` 来公开它们。除非你有依赖不同沙盒内布局的现有工作区契约，否则保留默认的 `skills_path=".agents"`。
-在适用时优先使用内置 capabilities。只有当你需要内置项未覆盖的 sandbox 专属工具或 instruction 接口时，才编写自定义 capability。
+当内置能力适用时，优先使用内置能力。只有在需要内置能力未覆盖的沙盒特定工具或指令表面时，才编写自定义能力。
## 概念
### Manifest
-[`Manifest`][agents.sandbox.manifest.Manifest] 描述一个全新 sandbox session 的工作区。它可以设置工作区 `root`、声明文件和目录、复制本地文件、克隆 Git 仓库、附加远程存储挂载、设置环境变量、定义用户或组，并授予对工作区外特定绝对路径的访问权限。
+[`Manifest`][agents.sandbox.manifest.Manifest] 描述全新沙盒会话的工作区。它可以设置工作区 `root`，声明文件和目录，复制本地文件，克隆 Git 仓库，附加远程存储挂载，设置环境变量，定义用户或组，并授予对工作区外特定绝对路径的访问权限。
-Manifest 条目的路径是相对于工作区的。它们不能是绝对路径，也不能通过 `..` 逃离工作区，这使工作区契约可以在本地、Docker 和托管 client 之间保持可移植性。
+Manifest 条目路径是相对于工作区的。它们不能是绝对路径，也不能使用 `..` 逃离工作区，这使工作区契约在本地、Docker 和托管客户端之间保持可移植。
-将 manifest 条目用于智能体在开始工作前所需的材料：
+将 manifest 条目用于智能体开始工作前所需的材料：
| Manifest 条目 | 用途 |
| --- | --- |
-| `File`、`Dir` | 小型合成输入、辅助文件或输出目录。 |
-| `LocalFile`、`LocalDir` | 应在 sandbox 中具体化的宿主机文件或目录。 |
+| `File`, `Dir` | 小型合成输入、辅助文件或输出目录。 |
+| `LocalFile`, `LocalDir` | 应物化到沙盒中的主机文件或目录。 |
| `GitRepo` | 应获取到工作区中的仓库。 |
-| 挂载，如 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` | 应出现在 sandbox 内的外部存储。 |
+| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` 等挂载 | 应显示在沙盒内部的外部存储。 |
-挂载条目描述要暴露什么存储；挂载策略描述 sandbox 后端如何附加该存储。有关挂载选项和提供方支持，请参见 [Sandbox clients](clients.md#mounts-and-remote-storage)。
+挂载条目描述要公开的存储；挂载策略描述沙盒后端如何附加该存储。有关挂载选项和提供商支持，请参阅[沙盒客户端](clients.md#mounts-and-remote-storage)。
-良好的 manifest 设计通常意味着保持工作区契约精简，将较长的任务说明放在工作区文件中，例如 `repo/task.md`，并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` capability 的 `apply_patch` 工具编辑文件，请记住 patch 路径相对于 sandbox 工作区根目录，而不是 shell 的 `workdir`。
+良好的 manifest 设计通常意味着保持工作区契约精简，把长任务配方放在工作区文件中，例如 `repo/task.md`，并在 instructions 中使用相对工作区路径，例如 `repo/task.md` 或 `output/report.md`。如果智能体使用 `Filesystem` 能力的 `apply_patch` 工具编辑文件，请记住补丁路径相对于沙盒工作区根目录，而不是 shell 的 `workdir`。
-仅当智能体需要访问工作区外的具体绝对路径时，才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp` 或用于只读运行时的 `/opt/toolchain`。在后端可以实施文件系统策略的情况下，授权同时适用于 SDK 文件 API 和 shell 执行：
+仅当智能体需要工作区外的具体绝对路径时，才使用 `extra_path_grants`，例如用于临时工具输出的 `/tmp`，或用于只读运行时的 `/opt/toolchain`。授权适用于 SDK 文件 API，也适用于后端能够强制执行文件系统策略的 shell 执行：
```python
from agents.sandbox import Manifest, SandboxPathGrant
@@ -257,13 +257,13 @@ manifest = Manifest(
)
```
-快照和 `persist_workspace()` 仍然只包含工作区根目录。额外授权的路径属于运行时访问，而不是持久化工作区状态。
+快照和 `persist_workspace()` 仍只包含工作区根目录。额外授予的路径是运行时访问权限，而不是持久工作区状态。
### 权限
-`Permissions` 控制 manifest 条目的文件系统权限。它针对的是 sandbox 具体化出来的文件，而不是模型权限、approval 策略或 API 凭证。
+`Permissions` 控制 manifest 条目的文件系统权限。它针对沙盒物化的文件，而不是模型权限、审批策略或 API 凭据。
-默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当准备的文件应为私有、只读或可执行时，请覆盖此设置：
+默认情况下，manifest 条目对所有者可读/可写/可执行，对组和其他用户可读/可执行。当暂存文件应为私有、只读或可执行时，请覆盖此设置：
```python
from agents.sandbox import FileMode, Permissions
@@ -279,9 +279,9 @@ private_notes = File(
)
```
-`Permissions` 存储独立的 owner、group 和 other 位，以及该条目是否为目录。你可以直接构建它，也可以通过 `Permissions.from_str(...)` 从 mode 字符串解析，或通过 `Permissions.from_mode(...)` 从操作系统 mode 派生。
+`Permissions` 存储单独的所有者、组和其他位，以及该条目是否为目录。你可以直接构建它，使用 `Permissions.from_str(...)` 从模式字符串解析它，或使用 `Permissions.from_mode(...)` 从 OS 模式派生它。
-Users 是可以执行工作的 sandbox 身份。当你希望某个身份存在于 sandbox 中时，请向 manifest 添加一个 `User`；然后，当面向模型的 sandbox 工具（如 shell 命令、文件读取和 patch）应以该用户身份运行时，设置 `SandboxAgent.run_as`。如果 `run_as` 指向一个尚未存在于 manifest 中的用户，runner 会自动将其添加到实际 manifest 中。
+用户是可以执行工作的沙盒身份。当你希望该身份存在于沙盒中时，请向 manifest 添加 `User`，然后在面向模型的沙盒工具（例如 shell 命令、文件读取和补丁）应以该用户运行时，设置 `SandboxAgent.run_as`。如果 `run_as` 指向尚未在 manifest 中的用户，运行器会为你将其添加到有效 manifest。
```python
from agents import Runner
@@ -333,13 +333,13 @@ result = await Runner.run(
)
```
-如果你还需要文件级别的共享规则，请将 users 与 manifest groups 以及条目的 `group` 元数据结合使用。`run_as` 用户控制谁执行 sandbox 原生动作；`Permissions` 控制一旦 sandbox 具体化工作区后，该用户可以读取、写入或执行哪些文件。
+如果你还需要文件级共享规则，请将用户与 manifest 组和条目 `group` 元数据结合使用。`run_as` 用户控制谁执行沙盒原生操作；`Permissions` 控制沙盒物化工作区后，该用户可以读取、写入或执行哪些文件。
### SnapshotSpec
-`SnapshotSpec` 告诉一个全新 sandbox session，应从哪里恢复已保存的工作区内容，以及持久化回哪里。它是 sandbox 工作区的快照策略，而 `session_state` 是用于恢复特定 sandbox 后端的序列化连接状态。
+`SnapshotSpec` 告诉全新沙盒会话应从哪里恢复已保存的工作区内容，并将内容持久化回哪里。它是沙盒工作区的快照策略，而 `session_state` 是用于恢复特定沙盒后端的序列化连接状态。
-当你需要本地持久快照时，使用 `LocalSnapshotSpec`；当你的应用提供远程快照 client 时，使用 `RemoteSnapshotSpec`。当本地快照设置不可用时，会回退使用 no-op 快照；高级调用方也可以在不希望工作区快照持久化时显式使用它。
+将 `LocalSnapshotSpec` 用于本地持久快照，将 `RemoteSnapshotSpec` 用于你的应用提供远程快照客户端的情况。当本地快照设置不可用时，会使用 no-op 快照作为回退；高级调用者在不需要工作区快照持久化时，也可以显式使用它。
```python
from pathlib import Path
@@ -356,13 +356,13 @@ run_config = RunConfig(
)
```
-当 runner 创建一个全新 sandbox session 时，sandbox client 会为该 session 构建一个快照实例。启动时，如果快照可恢复，sandbox 会在运行继续前恢复已保存的工作区内容。清理时，由 runner 拥有的 sandbox sessions 会归档工作区，并通过快照将其持久化回去。
+当运行器创建全新沙盒会话时，沙盒客户端会为该会话构建一个快照实例。启动时，如果快照可恢复，沙盒会在运行继续前恢复已保存的工作区内容。清理时，由运行器拥有的沙盒会话会归档工作区，并通过快照将其持久化回去。
-如果你省略 `snapshot`，运行时会在可行时尝试使用默认的本地快照位置。如果无法设置，则会回退为 no-op 快照。已挂载路径和临时路径不会作为持久工作区内容复制进快照。
+如果省略 `snapshot`，运行时会在可行时尝试使用默认本地快照位置。如果无法设置，则回退到 no-op 快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。
-### Sandbox 生命周期
+### 沙盒生命周期
-有两种生命周期模式：**SDK-owned** 和 **developer-owned**。
+有两种生命周期模式：**SDK 拥有**和**开发者拥有**。
@@ -390,7 +390,7 @@ sequenceDiagram
-当 sandbox 只需存活一次运行时，使用 SDK-owned 生命周期。传入 `client`、可选的 `manifest`、可选的 `snapshot` 和 client `options`；runner 会创建或恢复 sandbox，启动它，运行智能体，持久化由快照支持的工作区状态，关闭 sandbox，并让 client 清理由 runner 拥有的资源。
+当沙盒只需要在一次运行中存活时，使用 SDK 拥有的生命周期。传入 `client`、可选 `manifest`、可选 `snapshot` 和客户端 `options`；运行器会创建或恢复沙盒，启动它，运行智能体，持久化由快照支持的工作区状态，关闭沙盒，并让客户端清理运行器拥有的资源。
```python
result = await Runner.run(
@@ -402,7 +402,7 @@ result = await Runner.run(
)
```
-当你想要提前创建一个 sandbox、在多次运行间复用同一个实时 sandbox、在运行后检查文件、对你自己创建的 sandbox 进行流式处理，或精确决定何时清理时，请使用 developer-owned 生命周期。传入 `session=...` 会告诉 runner 使用该实时 sandbox，但不会替你关闭它。
+当你想提前创建沙盒、跨多次运行复用一个实时沙盒、在运行后检查文件、在自己创建的沙盒上进行流式传输，或精确决定何时清理时，使用开发者拥有的生命周期。传入 `session=...` 会告诉运行器使用该实时沙盒，但不会替你关闭它。
```python
sandbox = await client.create(manifest=agent.default_manifest)
@@ -413,7 +413,7 @@ async with sandbox:
await Runner.run(agent, "Write the final report.", run_config=run_config)
```
-上下文管理器是常见形式：进入时启动 sandbox，退出时运行 session 清理生命周期。如果你的应用无法使用上下文管理器，请直接调用生命周期方法：
+上下文管理器是常见形态：进入时启动沙盒，退出时运行会话清理生命周期。如果你的应用不能使用上下文管理器，请直接调用生命周期方法：
```python
sandbox = await client.create(
@@ -434,62 +434,62 @@ finally:
await sandbox.aclose()
```
-`stop()` 只会持久化由快照支持的工作区内容；它不会拆除 sandbox。`aclose()` 是完整的 session 清理路径：它会运行 pre-stop hooks、调用 `stop()`、关闭 sandbox 资源，并关闭 session 范围的依赖项。
+`stop()` 只会持久化由快照支持的工作区内容；它不会拆除沙盒。`aclose()` 是完整的会话清理路径：它运行停止前 hooks，调用 `stop()`，关闭沙盒资源，并关闭会话范围的依赖项。
## `SandboxRunConfig` 选项
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 包含每次运行的选项，用于决定 sandbox session 来自哪里，以及全新 session 应如何初始化。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 保存每次运行的选项，这些选项决定沙盒会话来自哪里，以及应如何初始化全新会话。
-### Sandbox 来源
+### 沙盒来源
-这些选项决定 runner 应复用、恢复还是创建 sandbox session：
+这些选项决定运行器应复用、恢复还是创建沙盒会话：
-| 选项 | 适用场景 | 说明 |
+| 选项 | 使用时机 | 备注 |
| --- | --- | --- |
-| `client` | 你希望 runner 为你创建、恢复并清理 sandbox sessions。 | 除非你提供一个实时 sandbox `session`，否则必填。 |
-| `session` | 你已经自行创建了一个实时 sandbox session。 | 生命周期由调用方负责；runner 会复用该实时 sandbox session。 |
-| `session_state` | 你拥有序列化的 sandbox session 状态，但没有实时 sandbox session 对象。 | 需要 `client`；runner 会以拥有型 session 的方式从该显式状态恢复。 |
+| `client` | 你希望运行器为你创建、恢复和清理沙盒会话。 | 除非你提供实时沙盒 `session`，否则必需。 |
+| `session` | 你已经自己创建了实时沙盒会话。 | 调用方拥有生命周期；运行器复用该实时沙盒会话。 |
+| `session_state` | 你有序列化的沙盒会话状态，但没有实时沙盒会话对象。 | 需要 `client`；运行器会从该显式状态恢复，并作为拥有方会话。 |
-在实践中，runner 会按以下顺序解析 sandbox session：
+实践中，运行器按以下顺序解析沙盒会话：
-1. 如果你注入 `run_config.sandbox.session`，则直接复用该实时 sandbox session。
-2. 否则，如果该运行是从 `RunState` 恢复的，则恢复存储的 sandbox session 状态。
-3. 否则，如果你传入 `run_config.sandbox.session_state`，runner 会从该显式序列化的 sandbox session 状态恢复。
-4. 否则，runner 会创建一个全新的 sandbox session。对于该全新 session，若提供了 `run_config.sandbox.manifest` 就使用它，否则使用 `agent.default_manifest`。
+1. 如果你注入 `run_config.sandbox.session`，该实时沙盒会话会被直接复用。
+2. 否则，如果运行正在从 `RunState` 恢复，则会恢复已存储的沙盒会话状态。
+3. 否则，如果你传入 `run_config.sandbox.session_state`，运行器会从该显式序列化的沙盒会话状态恢复。
+4. 否则，运行器会创建全新的沙盒会话。对于该全新会话，如果提供了 `run_config.sandbox.manifest`，就使用它；否则使用 `agent.default_manifest`。
-### 全新 session 输入
+### 全新会话输入
-这些选项仅在 runner 正在创建一个全新 sandbox session 时才有意义：
+这些选项仅在运行器创建全新沙盒会话时才有意义：
-| 选项 | 适用场景 | 说明 |
+| 选项 | 使用时机 | 备注 |
| --- | --- | --- |
-| `manifest` | 你希望一次性覆盖全新 session 工作区。 | 省略时回退到 `agent.default_manifest`。 |
-| `snapshot` | 全新的 sandbox session 应从快照中获得初始内容。 | 适用于类似恢复的流程或远程快照 client。 |
-| `options` | sandbox client 需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名、E2B 模板、超时以及类似的 client 专属设置。 |
+| `manifest` | 你想要一次性的全新会话工作区覆盖。 | 省略时回退到 `agent.default_manifest`。 |
+| `snapshot` | 全新沙盒会话应从快照播种。 | 对类似恢复的流程或远程快照客户端很有用。 |
+| `options` | 沙盒客户端需要创建时选项。 | 常见于 Docker 镜像、Modal 应用名称、E2B 模板、超时和类似的客户端特定设置。 |
-### 具体化控制
+### 物化控制
-`concurrency_limits` 控制有多少 sandbox 具体化工作可以并行运行。当大型 manifest 或本地目录复制需要更严格的资源控制时，使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设为 `None` 可禁用该特定限制。
+`concurrency_limits` 控制可以并行运行多少沙盒物化工作。当大型 manifest 或本地目录复制需要更严格的资源控制时，请使用 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`。将任一值设置为 `None` 可禁用该特定限制。
-有几点值得注意：
+有几点影响值得牢记：
-- 全新 sessions：`manifest=` 和 `snapshot=` 仅在 runner 创建全新 sandbox session 时生效。
-- 恢复 vs 快照：`session_state=` 会重新连接到先前序列化的 sandbox 状态，而 `snapshot=` 会从已保存的工作区内容为新的 sandbox session 提供初始内容。
-- client 专属选项：`options=` 依赖于 sandbox client；Docker 和许多托管 client 都需要它。
-- 注入的实时 sessions：如果你传入一个正在运行的 sandbox `session`，由 capability 驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。
-- Runner API：`SandboxAgent` 执行仍使用常规的 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。
+- 全新会话：`manifest=` 和 `snapshot=` 仅在运行器创建全新沙盒会话时适用。
+- 恢复 vs 快照：`session_state=` 会重新连接到之前序列化的沙盒状态，而 `snapshot=` 会从保存的工作区内容为新的沙盒会话播种。
+- 客户端特定选项：`options=` 取决于沙盒客户端；Docker 和许多托管客户端都需要它。
+- 注入的实时会话：如果你传入正在运行的沙盒 `session`，能力驱动的 manifest 更新可以添加兼容的非挂载条目。它们不能更改 `manifest.root`、`manifest.environment`、`manifest.users` 或 `manifest.groups`；不能移除现有条目；不能替换条目类型；也不能添加或更改挂载条目。
+- 运行器 API：`SandboxAgent` 执行仍使用常规 `Runner.run()`、`Runner.run_sync()` 和 `Runner.run_streamed()` API。
## 完整示例：编码任务
-这个编码风格的示例是一个很好的默认起点：
+这个编码风格示例是一个良好的默认起点：
```python
import asyncio
@@ -559,7 +559,7 @@ async def main(model: str, prompt: str) -> None:
if __name__ == "__main__":
asyncio.run(
main(
- model="gpt-5.4",
+ model="gpt-5.5",
prompt=(
"Open `repo/task.md`, use the `$credit-note-fixer` skill, fix the bug, "
f"run `{TARGET_TEST_CMD}`, and summarize the change."
@@ -568,19 +568,19 @@ if __name__ == "__main__":
)
```
-参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个基于 shell 的微型仓库，以便该示例可以在 Unix 本地运行中被确定性验证。当然，你的真实任务仓库可以是 Python、JavaScript 或任何其他类型。
+请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的仓库，因此示例可以在 Unix 本地运行中确定性地验证。你的真实任务仓库当然可以是 Python、JavaScript 或任何其他内容。
## 常见模式
-从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，而只更改 sandbox client、sandbox-session 来源或工作区来源。
+从上面的完整示例开始。在许多情况下，同一个 `SandboxAgent` 可以保持不变，只改变沙盒客户端、沙盒会话来源或工作区来源。
-### 切换 sandbox clients
+### 切换沙盒客户端
-保持智能体定义不变，只更改 run config。当你需要容器隔离或镜像一致性时使用 Docker；当你希望由提供方管理执行环境时使用托管提供方。示例和提供方选项请参见 [Sandbox clients](clients.md)。
+保持智能体定义不变，只更改运行配置。当需要容器隔离或镜像一致性时使用 Docker；当想要提供商管理的执行时使用托管提供商。有关代码示例和提供商选项，请参阅[沙盒客户端](clients.md)。
### 覆盖工作区
-保持智能体定义不变，仅替换全新 session 的 manifest：
+保持智能体定义不变，只替换全新会话 manifest：
```python
from agents.run import RunConfig
@@ -600,11 +600,11 @@ run_config = RunConfig(
)
```
-当同一智能体角色应面向不同仓库、材料包或任务包运行，而无需重建智能体时，可使用此方式。上面的已验证编码示例展示了使用 `default_manifest` 而不是一次性覆盖的相同模式。
+当同一个智能体角色应针对不同仓库、资料包或任务包运行，而无需重建智能体时，请使用此模式。上面经过验证的编码示例展示了相同模式，只是使用了 `default_manifest` 而不是一次性覆盖。
-### 注入 sandbox session
+### 注入沙盒会话
-当你需要显式生命周期控制、运行后检查或输出复制时，注入一个实时 sandbox session：
+当需要显式生命周期控制、运行后检查或输出复制时，注入实时沙盒会话：
```python
from agents import Runner
@@ -625,11 +625,11 @@ async with sandbox:
)
```
-当你希望在运行后检查工作区，或对一个已经启动的 sandbox session 进行流式处理时，可使用此方式。参见 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
+当你想在运行后检查工作区，或在已经启动的沙盒会话上进行流式传输时，请使用此模式。请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) 和 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
-### 从 session 状态恢复
+### 从会话状态恢复
-如果你已经在 `RunState` 之外序列化了 sandbox 状态，让 runner 从该状态重新连接：
+如果你已经在 `RunState` 之外序列化了沙盒状态，请让运行器从该状态重新连接：
```python
from agents.run import RunConfig
@@ -646,11 +646,11 @@ run_config = RunConfig(
)
```
-当 sandbox 状态保存在你自己的存储或作业系统中，并且你希望 `Runner` 直接从中恢复时，可使用此方式。序列化/反序列化流程请参见 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。
+当沙盒状态存在于你自己的存储或作业系统中，并且你希望 `Runner` 直接从中恢复时，请使用此模式。有关序列化/反序列化流程，请参阅 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)。
### 从快照开始
-从已保存的文件和产物为新的 sandbox 提供初始内容：
+从保存的文件和产物为新沙盒播种：
```python
from pathlib import Path
@@ -667,11 +667,11 @@ run_config = RunConfig(
)
```
-当一次全新运行应从已保存的工作区内容开始，而不仅仅是 `agent.default_manifest` 时，可使用此方式。本地快照流程请参见 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)，远程快照 client 请参见 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。
+当全新运行应从已保存的工作区内容开始，而不是仅从 `agent.default_manifest` 开始时，请使用此模式。有关本地快照流程，请参阅 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)；有关远程快照客户端，请参阅 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)。
-### 从 Git 加载 skills
+### 从 Git 加载技能
-将本地 skill 来源替换为仓库支持的来源：
+将本地技能来源替换为由仓库支持的来源：
```python
from agents.sandbox.capabilities import Capabilities, Skills
@@ -682,11 +682,11 @@ capabilities = Capabilities.default() + [
]
```
-当 skills bundle 有其自身的发布节奏，或应在多个 sandboxes 之间共享时，可使用此方式。参见 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。
+当技能包有自己的发布节奏，或应在多个沙盒之间共享时，请使用此模式。请参阅 [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)。
-### 作为工具暴露
+### 作为工具公开
-工具智能体可以拥有自己的 sandbox 边界，也可以复用父运行中的实时 sandbox。复用对于一个快速的只读探索智能体很有用：它可以检查父级正在使用的精确工作区，而无需付出创建、填充或快照另一个 sandbox 的成本。
+工具智能体可以拥有自己的沙盒边界，也可以复用父运行中的实时沙盒。复用对快速只读浏览智能体很有用：它可以检查父级正在使用的确切工作区，而无需付出创建、注水或快照另一个沙盒的成本。
```python
from agents import Runner
@@ -768,9 +768,9 @@ async with sandbox:
)
```
-这里父智能体以 `coordinator` 身份运行，而探索工具智能体在同一个实时 sandbox session 中以 `explorer` 身份运行。`pricing_packet/` 条目对 `other` 用户可读，因此 explorer 可以快速检查它们，但它没有写权限。`work/` 目录仅对 coordinator 的用户/组可用，因此父级可以写入最终产物，而 explorer 保持只读。
+这里父智能体以 `coordinator` 身份运行，而浏览器工具智能体以 `explorer` 身份在同一个实时沙盒会话中运行。`pricing_packet/` 条目对 `other` 用户可读，因此浏览器可以快速检查它们，但没有写入位。`work/` 目录仅对协调者的用户/组可用，因此父级可以写入最终产物，而浏览器保持只读。
-当工具智能体确实需要真正的隔离时，请为它提供自己的 sandbox `RunConfig`：
+当工具智能体需要真正隔离时，请为它提供自己的沙盒 `RunConfig`：
```python
from docker import from_env as docker_from_env
@@ -791,11 +791,11 @@ rollout_agent.as_tool(
)
```
-当工具智能体应能自由修改、运行不受信任的命令，或使用不同的后端/镜像时，请使用单独的 sandbox。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
+当工具智能体应自由变更、运行不可信命令，或使用不同后端/镜像时，请使用单独的沙盒。请参阅 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
-### 结合本地工具和 MCP
+### 与本地工具和 MCP 组合
-在保留 sandbox 工作区的同时，仍在同一个智能体上使用普通工具：
+在保留沙盒工作区的同时，仍在同一智能体上使用普通工具：
```python
from agents.sandbox import SandboxAgent
@@ -810,46 +810,46 @@ agent = SandboxAgent(
)
```
-当工作区检查只是智能体工作的一部分时，可使用此方式。参见 [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。
+当工作区检查只是智能体任务的一部分时，请使用此模式。请参阅 [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)。
-## Memory
+## 记忆
-当未来的 sandbox-agent 运行应从先前运行中学习时，使用 `Memory` capability。Memory 与 SDK 的对话式 `Session` memory 分离：它会将经验提炼为 sandbox 工作区内的文件，之后的运行即可读取这些文件。
+当未来的沙盒智能体运行应从先前运行中学习时，请使用 `Memory` 能力。记忆不同于 SDK 的会话式 `Session` 记忆：它将经验提炼为沙盒工作区内的文件，随后运行可以读取这些文件。
-有关设置、读取/生成行为、多轮对话和布局隔离，请参见 [Agent memory](memory.md)。
+有关设置、读取/生成行为、多轮对话和布局隔离，请参阅[智能体记忆](memory.md)。
## 组合模式
-当单智能体模式已经清晰后，下一个设计问题就是在更大的系统中应将 sandbox 边界放在哪里。
+一旦单智能体模式清晰，下一个设计问题就是在更大的系统中沙盒边界应位于何处。
-Sandbox 智能体仍可与 SDK 的其他部分组合：
+沙盒智能体仍然可以与 SDK 的其余部分组合：
-- [Handoffs](../handoffs.md)：将文档密集型工作从非 sandbox 的接入智能体转移给 sandbox 审查智能体。
-- [Agents as tools](../tools.md#agents-as-tools)：将多个 sandbox 智能体作为工具暴露，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具获得自己的 sandbox 边界。
-- [MCP](../mcp.md) 和普通工具调用：sandbox capabilities 可以与 `mcp_servers` 和常规 Python 工具共存。
-- [Running agents](../running_agents.md)：sandbox 运行仍使用常规的 `Runner` API。
+- [任务转移](../handoffs.md)：将文档密集型工作从非沙盒接收智能体转移给沙盒审阅者。
+- [Agents as tools](../tools.md#agents-as-tools)：将多个沙盒智能体公开为工具，通常是在每次 `Agent.as_tool(...)` 调用时传入 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`，以便每个工具都有自己的沙盒边界。
+- [MCP](../mcp.md) 和普通工具调用：沙盒能力可以与 `mcp_servers` 和普通 Python 工具共存。
+- [运行智能体](../running_agents.md)：沙盒运行仍使用常规 `Runner` API。
-有两种模式尤其常见：
+两种模式尤其常见：
-- 非 sandbox 智能体仅在工作流中需要工作区隔离的部分才转移给 sandbox 智能体
-- 一个编排器将多个 sandbox 智能体作为工具暴露，通常每次 `Agent.as_tool(...)` 调用都使用单独的 sandbox `RunConfig`，从而让每个工具获得各自隔离的工作区
+- 非沙盒智能体仅在工作流中需要工作区隔离的部分任务转移到沙盒智能体
+- 编排器将多个沙盒智能体公开为工具，通常为每个 `Agent.as_tool(...)` 调用使用单独的沙盒 `RunConfig`，以便每个工具都有自己的隔离工作区
-### Turns 和 sandbox 运行
+### 轮次和沙盒运行
-分别解释 handoff 与 agent-as-tool 调用会更容易理解。
+分别解释任务转移和 agent-as-tool 调用会更清楚。
-对于 handoff，仍然只有一个顶层运行和一个顶层 turn 循环。活动智能体会变化，但运行不会变成嵌套。如果一个非 sandbox 的接入智能体转移给 sandbox 审查智能体，那么该同一次运行中的下一次模型调用就会为 sandbox 智能体准备，而该 sandbox 智能体将成为执行下一个 turn 的智能体。换句话说，handoff 改变的是同一次运行中下一个 turn 由哪个智能体负责。参见 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。
+对于任务转移，仍然只有一个顶层运行和一个顶层轮次循环。活动智能体会改变，但运行不会变成嵌套。如果非沙盒接收智能体任务转移给沙盒审阅者，同一运行中的下一次模型调用会为沙盒智能体准备，而该沙盒智能体会成为执行下一轮的智能体。换句话说，任务转移会改变同一运行中由哪个智能体拥有下一轮。请参阅 [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)。
-而对于 `Agent.as_tool(...)`，关系则不同。外层编排器会在一个外层 turn 中决定调用该工具，而该工具调用会为 sandbox 智能体启动一次嵌套运行。嵌套运行有自己的 turn 循环、`max_turns`、approvals，以及通常也有自己的 sandbox `RunConfig`。它可能在一个嵌套 turn 内完成，也可能需要多个。从外层编排器的角度看，这些工作仍然都隐藏在一次工具调用之后，因此嵌套 turn 不会增加外层运行的 turn 计数。参见 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
+对于 `Agent.as_tool(...)`，关系则不同。外层编排器使用一个外层轮次来决定调用工具，而该工具调用会为沙盒智能体启动一个嵌套运行。嵌套运行有自己的轮次循环、`max_turns`、审批，并且通常有自己的沙盒 `RunConfig`。它可能在一个嵌套轮次中完成，也可能需要多个轮次。从外层编排器的角度来看，所有这些工作仍然位于一次工具调用之后，因此嵌套轮次不会增加外层运行的轮次计数器。请参阅 [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)。
-approval 行为也遵循相同的划分：
+审批行为遵循相同的拆分：
-- 对于 handoff，approvals 保持在同一个顶层运行上，因为 sandbox 智能体现在是该运行中的活动智能体
-- 对于 `Agent.as_tool(...)`，在 sandbox 工具智能体内部产生的 approvals 仍会显示在外层运行上，但它们来自已存储的嵌套运行状态，并会在外层运行恢复时恢复嵌套的 sandbox 运行
+- 对于任务转移，审批保留在同一个顶层运行中，因为沙盒智能体现在是该运行中的活动智能体
+- 对于 `Agent.as_tool(...)`，沙盒工具智能体内部提出的审批仍会浮现在外层运行上，但它们来自已存储的嵌套运行状态，并在外层运行恢复时恢复嵌套沙盒运行
## 延伸阅读
-- [Quickstart](quickstart.md)：运行一个 sandbox 智能体。
-- [Sandbox clients](clients.md)：选择本地、Docker、托管和挂载选项。
-- [Agent memory](memory.md)：保留并复用先前 sandbox 运行中的经验。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、memory、handoff 和智能体组合模式。
\ No newline at end of file
+- [快速开始](quickstart.md)：运行一个沙盒智能体。
+- [沙盒客户端](clients.md)：选择本地、Docker、托管和挂载选项。
+- [智能体记忆](memory.md)：保留并复用先前沙盒运行中的经验。
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)：可运行的本地、编码、记忆、任务转移和智能体组合模式。
\ No newline at end of file
diff --git a/docs/zh/sandbox_agents.md b/docs/zh/sandbox_agents.md
index 4c76ddd1f4..a04242a820 100644
--- a/docs/zh/sandbox_agents.md
+++ b/docs/zh/sandbox_agents.md
@@ -2,21 +2,21 @@
search:
exclude: true
---
-# 快速开始
+# 快速入门
!!! warning "Beta 功能"
- Sandbox 智能体目前处于 beta 阶段。预计 API 的细节、默认设置和支持的能力会在正式可用前发生变化，并且功能也会随着时间推移变得更高级。
+ 沙盒智能体处于 beta 阶段。在正式发布前，API、默认值和支持能力的细节可能会变化，并且后续会逐步加入更多高级功能。
-现代智能体在能够对文件系统中的真实文件进行操作时效果最佳。Agents SDK 中的 **Sandbox Agents** 为模型提供了一个持久化工作区，模型可以在其中检索大型文档集、编辑文件、运行命令、生成产物，并从已保存的 sandbox 状态中继续工作。
+当现代智能体能够在文件系统中的真实文件上操作时，效果最好。Agents SDK 中的**沙盒智能体**为模型提供了一个持久化工作区，使其可以搜索大型文档集、编辑文件、运行命令、生成产物，并从已保存的沙盒状态继续工作。
-SDK 为你提供了这一执行框架，无需你自己去拼接文件暂存、文件系统工具、shell 访问、sandbox 生命周期、快照以及特定提供方的胶水代码。你可以保留常规的 `Agent` 和 `Runner` 流程，然后再为工作区添加 `Manifest`、用于 sandbox 原生工具的 capabilities，以及用于指定工作运行位置的 `SandboxRunConfig`。
+SDK 为你提供了这套执行框架，无需你自行拼接文件暂存、文件系统工具、shell 访问、沙盒生命周期、快照以及特定提供商的胶水代码。你可以保留常规的 `Agent` 和 `Runner` 流程，然后为工作区添加 `Manifest`，为沙盒原生工具添加 capabilities，并用 `SandboxRunConfig` 指定工作运行的位置。
## 前提条件
- Python 3.10 或更高版本
-- 对 OpenAI Agents SDK 有基本了解
-- 一个 sandbox 客户端。对于本地开发，建议从 `UnixLocalSandboxClient` 开始。
+- 基本熟悉 OpenAI Agents SDK
+- 一个沙盒客户端。对于本地开发，请从 `UnixLocalSandboxClient` 开始。
## 安装
@@ -26,15 +26,15 @@ SDK 为你提供了这一执行框架，无需你自己去拼接文件暂存、
pip install openai-agents
```
-对于由 Docker 支持的 sandboxes：
+对于 Docker 支持的沙盒：
```bash
pip install "openai-agents[docker]"
```
-## 创建本地 sandbox 智能体
+## 创建本地沙盒智能体
-此示例会将本地仓库暂存到 `repo/` 下，按需延迟加载本地 skills，并让 runner 为本次运行创建一个 Unix 本地 sandbox 会话。
+此示例会将本地仓库暂存在 `repo/` 下，延迟加载本地 skills，并让 runner 为本次运行创建 Unix 本地沙盒会话。
```python
import asyncio
@@ -80,7 +80,7 @@ def build_agent(model: str) -> SandboxAgent[None]:
async def main() -> None:
result = await Runner.run(
- build_agent("gpt-5.4"),
+ build_agent("gpt-5.5"),
"Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.",
run_config=RunConfig(
sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
@@ -94,24 +94,24 @@ if __name__ == "__main__":
asyncio.run(main())
```
-参见[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用了一个基于 shell 的小型仓库，因此该示例可以在 Unix 本地运行中以确定性方式进行验证。
+请参阅 [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)。它使用一个很小的基于 shell 的仓库，因此可以在 Unix 本地运行中以确定性的方式验证该示例。
## 关键选择
-当基础运行正常后，大多数人接下来会关注这些选择：
+基本运行正常后，大多数人接下来会关注的选择包括：
-- `default_manifest`：用于全新 sandbox 会话的文件、仓库、目录和挂载
-- `instructions`：应在各个提示词中统一适用的简短工作流规则
-- `base_instructions`：一种高级兜底方式，用于替换 SDK 的 sandbox 提示词
-- `capabilities`：sandbox 原生工具，例如文件系统编辑/图像检查、shell、skills、memory 和 compaction
-- `run_as`：面向模型的工具所使用的 sandbox 用户身份
-- `SandboxRunConfig.client`：sandbox 后端
-- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到先前工作
+- `default_manifest`：用于全新沙盒会话的文件、仓库、目录和挂载
+- `instructions`：应在各个提示中适用的简短工作流规则
+- `base_instructions`：用于替换 SDK 沙盒提示词的高级逃生舱
+- `capabilities`：沙盒原生工具，例如文件系统编辑/图像检查、shell、skills、memory 和 compaction
+- `run_as`：面向模型的工具所使用的沙盒用户身份
+- `SandboxRunConfig.client`：沙盒后端
+- `SandboxRunConfig.session`、`session_state` 或 `snapshot`：后续运行如何重新连接到之前的工作
## 后续内容
- [概念](sandbox/guide.md)：了解 manifest、capabilities、权限、快照、运行配置和组合模式。
-- [Sandbox 客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供方以及挂载策略。
-- [智能体 memory](sandbox/memory.md)：保留并复用先前 sandbox 运行中的经验。
+- [沙盒客户端](sandbox/clients.md)：选择 Unix 本地、Docker、托管提供商和挂载策略。
+- [智能体记忆](sandbox/memory.md)：保留并复用此前沙盒运行中的经验。
-如果 shell 访问只是偶尔使用的工具之一，请先查看[tools 指南](tools.md)中的托管 shell。若工作区隔离、sandbox 客户端选择或 sandbox 会话恢复行为是设计的一部分，则应使用 sandbox 智能体。
\ No newline at end of file
+如果 shell 访问只是偶尔使用的工具，请从[工具指南](tools.md)中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为是设计的一部分时，再使用沙盒智能体。
\ No newline at end of file
diff --git a/docs/zh/streaming.md b/docs/zh/streaming.md
index 930d50e5eb..ab3da2fa24 100644
--- a/docs/zh/streaming.md
+++ b/docs/zh/streaming.md
@@ -4,19 +4,19 @@ search:
---
# 流式传输
-流式传输让你可以在智能体运行过程中订阅其更新。这对于向终端用户展示进度更新和部分响应很有帮助。
+流式传输让你可以在智能体运行过程中订阅其更新。这对于向最终用户展示进度更新和部分响应很有用。
-要进行流式传输，你可以调用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，它会返回一个 [`RunResultStreaming`][agents.result.RunResultStreaming]。调用 `result.stream_events()` 会得到一个由 [`StreamEvent`][agents.stream_events.StreamEvent] 对象组成的异步流，下面会进行说明。
+要进行流式传输，你可以调用 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]，它会返回一个 [`RunResultStreaming`][agents.result.RunResultStreaming]。调用 `result.stream_events()` 会得到一个由 [`StreamEvent`][agents.stream_events.StreamEvent] 对象组成的异步流，下面将对此进行说明。
-持续消费 `result.stream_events()`，直到异步迭代器结束。流式运行在迭代器结束前都不算完成，而且诸如会话持久化、审批记录或历史压缩等后处理，可能会在最后一个可见 token 到达后才完成。循环退出时，`result.is_complete` 会反映最终运行状态。
+持续消费 `result.stream_events()`，直到异步迭代器结束。只有当迭代器结束时，流式运行才算完成；在最后一个可见 token 到达后，会话持久化、审批记账或历史压缩等后处理仍可能完成。当循环退出时，`result.is_complete` 会反映最终运行状态。
## 原始响应事件
-[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] 是直接从 LLM 透传的原始事件。它们采用 OpenAI Responses API 格式，这意味着每个事件都有类型（如 `response.created`、`response.output_text.delta` 等）和数据。如果你希望在响应消息生成后立即流式发送给用户，这些事件会很有用。
+[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] 是直接从 LLM 传递过来的原始事件。它们采用 OpenAI Responses API 格式，这意味着每个事件都有一个类型（例如 `response.created`、`response.output_text.delta` 等）和数据。如果你想在响应消息生成后立即将其流式传输给用户，这些事件会很有用。
-计算机工具原始事件与存储结果一样，保持 preview 与 GA 的区分。Preview 流会流式返回带有单个 `action` 的 `computer_call` 项，而 `gpt-5.4` 可以流式返回带有批量 `actions[]` 的 `computer_call` 项。更高层的 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 接口不会为此增加专用的计算机事件名：这两种形态仍都会以 `tool_called` 呈现，而截图结果会以封装了 `computer_call_output` 项的 `tool_output` 返回。
+计算机工具原始事件会保留与存储结果相同的预览版与 GA 区分。预览版流程会流式传输带有一个 `action` 的 `computer_call` 项，而 `gpt-5.5` 可以流式传输带有批量 `actions[]` 的 `computer_call` 项。更高层级的 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 表层不会为此添加仅限计算机的特殊事件名称：这两种形态仍都会以 `tool_called` 呈现，截图结果则会作为包装了 `computer_call_output` 项的 `tool_output` 返回。
-例如，下面将按 token 逐个输出 LLM 生成的文本。
+例如，这会逐个 token 输出 LLM 生成的文本。
```python
import asyncio
@@ -41,7 +41,7 @@ if __name__ == "__main__":
## 流式传输与审批
-流式传输与因工具审批而暂停的运行兼容。如果某个工具需要审批，`result.stream_events()` 会结束，待处理的审批会暴露在 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 中。将结果通过 `result.to_state()` 转换为 [`RunState`][agents.run_state.RunState]，批准或拒绝该中断，然后使用 `Runner.run_streamed(...)` 恢复运行。
+流式传输与因工具审批而暂停的运行兼容。如果某个工具需要审批，`result.stream_events()` 会结束，并且待处理的审批会在 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] 中暴露。使用 `result.to_state()` 将结果转换为 [`RunState`][agents.run_state.RunState]，批准或拒绝该中断，然后使用 `Runner.run_streamed(...)` 恢复运行。
```python
result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.")
@@ -57,21 +57,21 @@ if result.interruptions:
pass
```
-完整的暂停/恢复流程请参见[人类参与指南](human_in_the_loop.md)。
+如需完整的暂停/恢复演练，请参阅[人在环路指南](human_in_the_loop.md)。
-## 在当前轮次后取消流式传输
+## 当前轮次后的流式传输取消
-如果你需要在中途停止一次流式运行，调用 [`result.cancel()`][agents.result.RunResultStreaming.cancel]。默认会立即停止运行。若想在停止前让当前轮次完整结束，请改用 `result.cancel(mode="after_turn")`。
+如果你需要在中途停止一次流式运行，请调用 [`result.cancel()`][agents.result.RunResultStreaming.cancel]。默认情况下，这会立即停止运行。若要让当前轮次在停止前干净地完成，请改为调用 `result.cancel(mode="after_turn")`。
-在 `result.stream_events()` 结束前，流式运行都不算完成。SDK 可能仍在最后一个可见 token 之后持久化会话项、完成审批状态收尾或压缩历史。
+在 `result.stream_events()` 结束之前，流式运行都不算完成。在最后一个可见 token 之后，SDK 可能仍在持久化会话项、最终确定审批状态或压缩历史。
-如果你是基于 [`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] 手动继续，且 `cancel(mode="after_turn")` 在工具轮次后停止，请用该 normalized 输入重新运行 `result.last_agent` 以继续未完成轮次，而不是立即追加新的用户轮次。
-- 如果一次流式运行因工具审批而停止，不要将其视为新轮次。先完成流的消费，检查 `result.interruptions`，然后改为从 `result.to_state()` 恢复。
-- 使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 自定义在下一次模型调用前，如何合并检索到的会话历史与新的用户输入。如果你在其中改写了新轮次项，被改写后的版本将作为该轮次的持久化内容。
+如果你正从 [`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] 手动继续，并且 `cancel(mode="after_turn")` 在工具轮次之后停止，请使用该规范化输入重新运行 `result.last_agent` 来继续这个未完成的轮次，而不是立即追加一个新的用户轮次。
+- 如果一次流式运行因工具审批而停止，不要将其视为新的轮次。请先完成对流的读取，检查 `result.interruptions`，然后改为从 `result.to_state()` 恢复。
+- 使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 自定义在下一次模型调用之前，如何合并检索到的会话历史与新的用户输入。如果你在那里重写了新轮次的项目，则该轮次会持久化重写后的版本。
## 运行项事件与智能体事件
-[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 是更高层级的事件。它会在某个项完整生成后通知你。这样你就可以在“消息已生成”“工具已运行”等层级推送进度更新，而不是按 token 推送。类似地，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时提供更新（例如因任务转移导致的变化）。
+[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 是更高层级的事件。它们会在某个项完全生成后通知你。这使你能够在“消息已生成”“工具已运行”等层级推送进度更新，而不是针对每个 token 推送。同样，[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] 会在当前智能体发生变化时（例如因任务转移而变化）向你提供更新。
### 运行项事件名称
@@ -89,11 +89,11 @@ if result.interruptions:
- `mcp_approval_response`
- `mcp_list_tools`
-出于向后兼容考虑，`handoff_occured` 保留了故意的拼写错误。
+为保持向后兼容，`handoff_occured` 有意拼写错误。
-当你使用托管工具搜索时，模型发出工具搜索请求会触发 `tool_search_called`，Responses API 返回已加载子集时会触发 `tool_search_output_created`。
+使用托管工具搜索时，当模型发出工具搜索请求时会发出 `tool_search_called`，当 Responses API 返回已加载的子集时会发出 `tool_search_output_created`。
-例如，下面会忽略原始事件，并向用户流式推送更新。
+例如，这会忽略原始事件，并向用户流式传输更新。
```python
import asyncio
diff --git a/docs/zh/tools.md b/docs/zh/tools.md
index c7b42f87d9..7e7cd2d9f3 100644
--- a/docs/zh/tools.md
+++ b/docs/zh/tools.md
@@ -4,41 +4,41 @@ search:
---
# 工具
-工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至操作计算机。SDK 支持五类：
+工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至使用计算机。SDK 支持五个目录：
-- 由OpenAI托管的工具：与模型一起在 OpenAI 服务上运行。
-- 本地/运行时执行工具：`ComputerTool` 和 `ApplyPatchTool` 始终在你的环境中运行，而 `ShellTool` 可在本地或托管容器中运行。
+- 由 OpenAI 托管的工具：与模型一起在 OpenAI 服务上运行。
+- 本地/运行时执行工具：`ComputerTool` 和 `ApplyPatchTool` 始终在你的环境中运行，而 `ShellTool` 可以在本地或托管容器中运行。
- Function Calling：将任意 Python 函数封装为工具。
-- Agents as tools：将智能体作为可调用工具暴露，而无需完整任务转移。
-- 实验性：Codex 工具：通过工具调用运行工作区范围内的 Codex 任务。
+- Agents as tools：将智能体公开为可调用工具，无需完整任务转移。
+- 实验性：Codex 工具：通过工具调用运行作用域限定在工作区内的 Codex 任务。
## 工具类型选择
-将本页作为目录使用，然后跳转到与你可控运行时匹配的章节。
+将本页用作目录，然后跳转到与你控制的运行时匹配的部分。
-| 如果你想... | 从这里开始 |
+| 如果你想要... | 从这里开始 |
| --- | --- |
-| 使用由 OpenAI 管理的工具（网络检索、文件检索、Code Interpreter、托管 MCP、图像生成） | [托管工具](#hosted-tools) |
-| 通过工具搜索将大型工具集合延迟到运行时加载 | [托管工具搜索](#hosted-tool-search) |
+| 使用 OpenAI 管理的工具（网络检索、文件检索、代码解释器、托管 MCP、图像生成） | [托管工具](#hosted-tools) |
+| 通过工具搜索将大型工具表面推迟到运行时 | [托管工具搜索](#hosted-tool-search) |
| 在你自己的进程或环境中运行工具 | [本地运行时工具](#local-runtime-tools) |
| 将 Python 函数封装为工具 | [工具调用](#function-tools) |
-| 让一个智能体在不任务转移的情况下调用另一个智能体 | [Agents as tools](#agents-as-tools) |
-| 从智能体运行工作区范围内的 Codex 任务 | [实验性：Codex 工具](#experimental-codex-tool) |
+| 让一个智能体在没有任务转移的情况下调用另一个智能体 | [Agents as tools](#agents-as-tools) |
+| 从智能体运行作用域限定在工作区内的 Codex 任务 | [实验性：Codex 工具](#experimental-codex-tool) |
## 托管工具
-在使用 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 时，OpenAI 提供了一些内置工具：
+使用 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 时，OpenAI 提供了一些内置工具：
-- [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体可以搜索网络。
+- [`WebSearchTool`][agents.tool.WebSearchTool] 让智能体搜索网络。
- [`FileSearchTool`][agents.tool.FileSearchTool] 允许从你的 OpenAI 向量存储中检索信息。
-- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙箱环境中执行代码。
-- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务的工具暴露给模型。
+- [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] 让 LLM 在沙盒环境中执行代码。
+- [`HostedMCPTool`][agents.tool.HostedMCPTool] 将远程 MCP 服务的工具公开给模型。
- [`ImageGenerationTool`][agents.tool.ImageGenerationTool] 根据提示词生成图像。
-- [`ToolSearchTool`][agents.tool.ToolSearchTool] 让模型按需加载延迟工具、命名空间或托管 MCP 服务。
+- [`ToolSearchTool`][agents.tool.ToolSearchTool] 让模型按需加载延迟的工具、命名空间或托管 MCP 服务。
高级托管搜索选项：
-- `FileSearchTool` 除了 `vector_store_ids` 和 `max_num_results` 外，还支持 `filters`、`ranking_options` 和 `include_search_results`。
+- 除了 `vector_store_ids` 和 `max_num_results`，`FileSearchTool` 还支持 `filters`、`ranking_options` 和 `include_search_results`。
- `WebSearchTool` 支持 `filters`、`user_location` 和 `search_context_size`。
```python
@@ -62,9 +62,9 @@ async def main():
### 托管工具搜索
-工具搜索让 OpenAI Responses 模型将大型工具集合延迟到运行时，因此模型只会加载当前轮次所需的子集。当你拥有大量工具调用、命名空间分组或托管 MCP 服务，并希望减少工具 schema token 而不在前期暴露所有工具时，这非常有用。
+工具搜索让 OpenAI Responses 模型能够将大型工具表面推迟到运行时，因此模型只加载当前轮次所需的子集。当你有许多工具调用、命名空间组或托管 MCP 服务，并且希望减少工具 schema token、同时不预先暴露每个工具时，这会很有用。
-当候选工具在构建智能体时已知时，优先使用托管工具搜索。如果你的应用需要动态决定加载内容，Responses API 也支持客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。
+当你构建智能体时候选工具已经已知，请从托管工具搜索开始。如果你的应用需要动态决定加载什么，Responses API 也支持客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。
```python
from typing import Annotated
@@ -97,7 +97,7 @@ crm_tools = tool_namespace(
agent = Agent(
name="Operations assistant",
- model="gpt-5.4",
+ model="gpt-5.5",
instructions="Load the crm namespace before using CRM tools.",
tools=[*crm_tools, ToolSearchTool()],
)
@@ -106,26 +106,26 @@ result = await Runner.run(agent, "Look up customer_42 and list their open orders
print(result.final_output)
```
-注意事项：
+需要了解的事项：
-- 托管工具搜索仅适用于 OpenAI Responses 模型。当前 Python SDK 支持依赖 `openai>=2.25.0`。
-- 当你在智能体上配置延迟加载集合时，精确添加一个 `ToolSearchTool()`。
-- 可搜索集合包括 `@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])` 和 `HostedMCPTool(tool_config={..., "defer_loading": True})`。
-- 延迟加载的工具调用必须与 `ToolSearchTool()` 搭配使用。仅命名空间配置也可使用 `ToolSearchTool()` 以便模型按需加载正确分组。
-- `tool_namespace()` 在共享命名空间名称和描述下对 `FunctionTool` 实例分组。当你有许多相关工具（如 `crm`、`billing` 或 `shipping`）时，这通常是最佳选择。
-- OpenAI 官方最佳实践指南是 [Use namespaces where possible](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)。
-- 在可能的情况下，优先使用命名空间或托管 MCP 服务，而不是大量单独延迟函数。它们通常能为模型提供更好的高层搜索面，并带来更好的 token 节省。
-- 命名空间可以混合即时工具和延迟工具。未设置 `defer_loading=True` 的工具仍可立即调用，而同一命名空间中的延迟工具通过工具搜索加载。
-- 经验法则是让每个命名空间保持较小规模，理想情况下少于 10 个函数。
-- 命名 `tool_choice` 不能定位到裸命名空间名或仅延迟工具。优先使用 `auto`、`required` 或真实的顶层可调用工具名。
-- `ToolSearchTool(execution="client")` 用于手动 Responses 编排。如果模型输出客户端执行的 `tool_search_call`，标准 `Runner` 会抛出异常而不是替你执行。
-- 工具搜索活动会出现在 [`RunResult.new_items`](results.md#new-items) 以及 [`RunItemStreamEvent`](streaming.md#run-item-event-names) 中，并使用专用条目和事件类型。
-- 参见 `examples/tools/tool_search.py`，其中有涵盖命名空间加载和顶层延迟工具的完整可运行代码示例。
-- 官方平台指南：[Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search)。
+- 托管工具搜索仅适用于 OpenAI Responses 模型。当前 Python SDK 支持取决于 `openai>=2.25.0`。
+- 在智能体上配置延迟加载表面时，恰好添加一个 `ToolSearchTool()`。
+- 可搜索表面包括 `@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])`，以及 `HostedMCPTool(tool_config={..., "defer_loading": True})`。
+- 延迟加载的工具调用必须与 `ToolSearchTool()` 配对。仅命名空间的设置也可以使用 `ToolSearchTool()`，以便让模型按需加载正确的组。
+- `tool_namespace()` 将 `FunctionTool` 实例分组到共享的命名空间名称和描述下。当你有许多相关工具（例如 `crm`、`billing` 或 `shipping`）时，这通常最合适。
+- OpenAI 的官方最佳实践指南是[尽可能使用命名空间](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)。
+- 尽可能优先使用命名空间或托管 MCP 服务，而不是许多单独延迟的函数。它们通常能为模型提供更好的高层搜索表面，并带来更好的 token 节省。
+- 命名空间可以混合立即可用和延迟的工具。没有 `defer_loading=True` 的工具仍可立即调用，而同一命名空间中的延迟工具会通过工具搜索加载。
+- 根据经验法则，每个命名空间应保持相当小，最好少于 10 个函数。
+- 具名 `tool_choice` 不能指向裸命名空间名称或仅延迟的工具。优先使用 `auto`、`required`，或真实的顶层可调用工具名称。
+- `ToolSearchTool(execution="client")` 用于手动 Responses 编排。如果模型发出客户端执行的 `tool_search_call`，标准 `Runner` 会抛出异常，而不是替你执行它。
+- 工具搜索活动会出现在 [`RunResult.new_items`](results.md#new-items) 中，并以专用条目和事件类型出现在 [`RunItemStreamEvent`](streaming.md#run-item-event-names) 中。
+- 请参阅 `examples/tools/tool_search.py`，其中包含覆盖命名空间加载和顶层延迟工具的完整可运行示例。
+- 官方平台指南：[工具搜索](https://developers.openai.com/api/docs/guides/tools-tool-search)。
-### 托管容器 Shell + 技能
+### 托管容器 shell + 技能
-`ShellTool` 也支持 OpenAI 托管容器执行。当你希望模型在托管容器而不是本地运行时执行 shell 命令时，请使用此模式。
+`ShellTool` 还支持 OpenAI 托管的容器执行。当你希望模型在受管容器中运行 shell 命令，而不是在你的本地运行时中运行时，请使用此模式。
```python
from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -138,7 +138,7 @@ csv_skill: ShellToolSkillReference = {
agent = Agent(
name="Container shell agent",
- model="gpt-5.4",
+ model="gpt-5.5",
instructions="Use the mounted skill when helpful.",
tools=[
ShellTool(
@@ -158,52 +158,52 @@ result = await Runner.run(
print(result.final_output)
```
-如需在后续运行中复用现有容器，设置 `environment={"type": "container_reference", "container_id": "cntr_..."}`。
+若要在后续运行中复用现有容器，请设置 `environment={"type": "container_reference", "container_id": "cntr_..."}`。
-注意事项：
+需要了解的事项：
- 托管 shell 可通过 Responses API shell 工具使用。
-- `container_auto` 为请求配置容器；`container_reference` 复用现有容器。
-- `container_auto` 还可包含 `file_ids` 和 `memory_limit`。
+- `container_auto` 会为请求预置一个容器；`container_reference` 会复用现有容器。
+- `container_auto` 还可以包含 `file_ids` 和 `memory_limit`。
- `environment.skills` 接受技能引用和内联技能包。
-- 在托管环境下，不要在 `ShellTool` 上设置 `executor`、`needs_approval` 或 `on_approval`。
+- 使用托管环境时，不要在 `ShellTool` 上设置 `executor`、`needs_approval` 或 `on_approval`。
- `network_policy` 支持 `disabled` 和 `allowlist` 模式。
-- 在 allowlist 模式下，`network_policy.domain_secrets` 可按名称注入域级密钥。
-- 参见 `examples/tools/container_shell_skill_reference.py` 和 `examples/tools/container_shell_inline_skill.py` 获取完整代码示例。
+- 在 allowlist 模式下，`network_policy.domain_secrets` 可以按名称注入域作用域的密钥。
+- 请参阅 `examples/tools/container_shell_skill_reference.py` 和 `examples/tools/container_shell_inline_skill.py`，了解完整示例。
- OpenAI 平台指南：[Shell](https://platform.openai.com/docs/guides/tools-shell) 和 [Skills](https://platform.openai.com/docs/guides/tools-skills)。
## 本地运行时工具
-本地运行时工具在模型响应本身之外执行。模型仍决定何时调用它们，但实际工作由你的应用或配置的执行环境完成。
+本地运行时工具在模型响应本身之外执行。模型仍会决定何时调用它们，但实际工作由你的应用或配置的执行环境完成。
-`ComputerTool` 和 `ApplyPatchTool` 始终需要你提供本地实现。`ShellTool` 同时覆盖两种模式：当你希望托管执行时，使用上方托管容器配置；当你希望命令在自己的进程中运行时，使用下方本地运行时配置。
+`ComputerTool` 和 `ApplyPatchTool` 始终需要你提供本地实现。`ShellTool` 跨越两种模式：当你希望托管执行时，使用上面的托管容器配置；当你希望命令在自己的进程中运行时，使用下面的本地运行时配置。
-本地运行时工具需要你提供实现：
+本地运行时工具要求你提供实现：
-- [`ComputerTool`][agents.tool.ComputerTool]：实现 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 接口以启用 GUI/浏览器自动化。
-- [`ShellTool`][agents.tool.ShellTool]：同时支持本地执行和托管容器执行的最新 shell 工具。
+- [`ComputerTool`][agents.tool.ComputerTool]：实现 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 接口，以启用 GUI/浏览器自动化。
+- [`ShellTool`][agents.tool.ShellTool]：用于本地执行和托管容器执行的最新 shell 工具。
- [`LocalShellTool`][agents.tool.LocalShellTool]：旧版本地 shell 集成。
- [`ApplyPatchTool`][agents.tool.ApplyPatchTool]：实现 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] 以在本地应用 diff。
- 本地 shell 技能可通过 `ShellTool(environment={"type": "local", "skills": [...]})` 使用。
### ComputerTool 与 Responses 计算机工具
-`ComputerTool` 仍是本地 harness：你提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 将该 harness 映射到 OpenAI Responses API 的计算机能力面。
+`ComputerTool` 仍然是一个本地 harness：你提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 会将该 harness 映射到 OpenAI Responses API 的计算机表面。
-对于显式的 [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) 请求，SDK 发送 GA 内置工具负载 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型继续使用预览负载 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI [Computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use/) 中描述的平台迁移一致：
+对于显式的 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 请求，SDK 发送 GA 内置工具载荷 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型保留预览载荷 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI 的[计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)中描述的平台迁移一致：
-- 模型：`computer-use-preview` -> `gpt-5.4`
+- 模型：`computer-use-preview` -> `gpt-5.5`
- 工具选择器：`computer_use_preview` -> `computer`
-- 计算机调用形态：每个 `computer_call` 一个 `action` -> `computer_call` 上批量 `actions[]`
-- 截断：预览路径需要 `ModelSettings(truncation="auto")` -> GA 路径不需要
+- 计算机调用形态：每个 `computer_call` 一个 `action` -> `computer_call` 上的批量 `actions[]`
+- 截断：预览路径上需要 `ModelSettings(truncation="auto")` -> GA 路径上不需要
-SDK 根据实际 Responses 请求中的生效模型选择该线协议形态。如果你使用 prompt 模板且请求因 prompt 持有模型而省略 `model`，SDK 会保持预览兼容的计算机负载，除非你显式保留 `model="gpt-5.4"`，或通过 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。
+SDK 会根据实际 Responses 请求上的有效模型选择该线缆形态。如果你使用提示模板，并且由于提示自身拥有模型而请求省略了 `model`，SDK 会保持预览兼容的计算机载荷，除非你显式保留 `model="gpt-5.5"`，或使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用 GA 选择器。
-当存在 [`ComputerTool`][agents.tool.ComputerTool] 时，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 都会被接受，并标准化为与生效请求模型匹配的内置选择器。没有 `ComputerTool` 时，这些字符串仍表现为普通函数名。
+当存在 [`ComputerTool`][agents.tool.ComputerTool] 时，`tool_choice="computer"`、`"computer_use"` 和 `"computer_use_preview"` 都会被接受，并规范化为与有效请求模型匹配的内置选择器。没有 `ComputerTool` 时，这些字符串仍像普通函数名一样工作。
-当 `ComputerTool` 由 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂支持时，这一区别尤为重要。GA `computer` 负载在序列化时不需要 `environment` 或尺寸，因此未解析工厂也没问题。预览兼容序列化仍需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 发送 `environment`、`display_width` 和 `display_height`。
+当 `ComputerTool` 由 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂提供支持时，这一区别很重要。GA `computer` 载荷在序列化时不需要 `environment` 或尺寸，因此未解析的工厂也没问题。预览兼容的序列化仍需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 能发送 `environment`、`display_width` 和 `display_height`。
-在运行时，两条路径仍使用同一本地 harness。预览响应会输出带单个 `action` 的 `computer_call` 条目；`gpt-5.4` 可输出批量 `actions[]`，SDK 会按顺序执行，然后产出 `computer_call_output` 截图条目。参见 `examples/tools/computer_use.py` 获取基于 Playwright 的可运行 harness。
+运行时，两条路径仍使用相同的本地 harness。预览响应会发出带有单个 `action` 的 `computer_call` 条目；`gpt-5.5` 可以发出批量 `actions[]`，SDK 会按顺序执行它们，然后生成一个 `computer_call_output` 截图条目。请参阅 `examples/tools/computer_use.py`，了解基于 Playwright 的可运行 harness。
```python
from agents import Agent, ApplyPatchTool, ShellTool
@@ -247,16 +247,16 @@ agent = Agent(
## 工具调用
-你可以将任何 Python 函数用作工具。Agents SDK 会自动完成工具设置：
+你可以将任意 Python 函数用作工具。Agents SDK 会自动设置该工具：
-- 工具名称将是 Python 函数名（也可自行提供名称）
-- 工具描述将取自函数 docstring（也可自行提供描述）
-- 函数输入 schema 会根据函数参数自动创建
-- 每个输入的描述将取自函数 docstring，除非禁用
+- 工具名称将是 Python 函数的名称（或者你可以提供一个名称）
+- 工具描述将来自函数的 docstring（或者你可以提供描述）
+- 函数输入的 schema 会根据函数参数自动创建
+- 除非禁用，否则每个输入的描述都来自函数的 docstring
-我们使用 Python 的 `inspect` 模块提取函数签名，配合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，并使用 `pydantic` 创建 schema。
+我们使用 Python 的 `inspect` 模块提取函数签名，并结合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析 docstring，使用 `pydantic` 创建 schema。
-当你使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏工具调用，直到由 `ToolSearchTool()` 加载。你也可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关工具调用分组。完整设置和约束请参见 [托管工具搜索](#hosted-tool-search)。
+当你使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏工具调用，直到 `ToolSearchTool()` 加载它。你也可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关工具调用进行分组。请参阅[托管工具搜索](#hosted-tool-search)，了解完整设置和约束。
```python
import json
@@ -308,9 +308,9 @@ for tool in agent.tools:
```
-1. 你可以在函数参数中使用任意 Python 类型，且函数可为同步或异步。
-2. 如有 docstring，会用于提取描述和参数描述。
-3. 函数可选择接收 `context`（必须是第一个参数）。你也可以设置覆盖项，例如工具名、描述、使用哪种 docstring 风格等。
+1. 你可以将任意 Python 类型用作函数参数，函数可以是同步或异步的。
+2. 如果存在 docstring，会用于捕获描述和参数描述
+3. 函数可以选择接收 `context`（必须是第一个参数）。你还可以设置覆盖项，例如工具名称、描述、使用哪种 docstring 风格等。
4. 你可以将装饰后的函数传入工具列表。
??? note "展开查看输出"
@@ -383,22 +383,22 @@ for tool in agent.tools:
}
```
-### 工具调用返回图像或文件
+### 从工具调用返回图像或文件
-除了返回文本输出外，你还可以将一个或多个图像或文件作为工具调用的输出返回。可返回以下任意类型：
+除了返回文本输出，你还可以将一个或多个图像或文件作为工具调用的输出返回。为此，你可以返回以下任意内容：
-- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或其 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]）
-- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或其 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]）
-- 文本：字符串或可转字符串对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或其 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
+- 图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]）
+- 文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]）
+- 文本：字符串或可字符串化对象，或者 [`ToolOutputText`][agents.tool.ToolOutputText]（或 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
### 自定义工具调用
-有时你不想将 Python 函数作为工具。你也可以直接创建 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供：
+有时，你不想将 Python 函数用作工具。如果你愿意，可以直接创建 [`FunctionTool`][agents.tool.FunctionTool]。你需要提供：
- `name`
- `description`
- `params_json_schema`，即参数的 JSON schema
-- `on_invoke_tool`，一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和 JSON 字符串形式的参数，并返回工具输出（例如文本、结构化工具输出对象或输出列表）。
+- `on_invoke_tool`，这是一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和以 JSON 字符串形式传入的参数，并返回工具输出（例如文本、结构化工具输出对象，或输出列表）。
```python
from typing import Any
@@ -431,18 +431,18 @@ tool = FunctionTool(
)
```
-### 参数与 docstring 自动解析
+### 自动参数与 docstring 解析
-如前所述，我们会自动解析函数签名以提取工具 schema，并解析 docstring 以提取工具及各参数描述。说明如下：
+如前所述，我们会自动解析函数签名以提取工具的 schema，并解析 docstring 以提取工具及各个参数的描述。相关说明：
-1. 签名解析通过 `inspect` 模块完成。我们使用类型注解理解参数类型，并动态构建 Pydantic 模型表示整体 schema。它支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。
-2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这属于尽力而为；你也可在调用 `function_tool` 时显式设置。你还可以通过将 `use_docstring_info` 设为 `False` 来禁用 docstring 解析。
+1. 签名解析通过 `inspect` 模块完成。我们使用类型注解来理解参数类型，并动态构建一个 Pydantic 模型来表示整体 schema。它支持大多数类型，包括 Python primitives、Pydantic 模型、TypedDict 等。
+2. 我们使用 `griffe` 解析 docstring。支持的 docstring 格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测 docstring 格式，但这是尽力而为；你也可以在调用 `function_tool` 时显式设置。你还可以通过将 `use_docstring_info` 设置为 `False` 来禁用 docstring 解析。
-schema 提取代码位于 [`agents.function_schema`][]。
+用于 schema 提取的代码位于 [`agents.function_schema`][]。
### 使用 Pydantic Field 约束和描述参数
-你可以使用 Pydantic 的 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) 为工具参数添加约束（例如数字最小/最大值、字符串长度或模式）和描述。与 Pydantic 一致，两种形式都支持：基于默认值（`arg: int = Field(..., ge=1)`）和 `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）。生成的 JSON schema 和校验都会包含这些约束。
+你可以使用 Pydantic 的 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) 为工具参数添加约束（例如数字的最小/最大值、字符串的长度或模式）和描述。与 Pydantic 中一样，两种形式都受支持：基于默认值的形式（`arg: int = Field(..., ge=1)`）和 `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）。生成的 JSON schema 和验证都会包含这些约束。
```python
from typing import Annotated
@@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr
### 工具调用超时
-你可以通过 `@function_tool(timeout=...)` 为异步工具调用设置每次调用超时。
+你可以使用 `@function_tool(timeout=...)` 为异步工具调用设置每次调用的超时时间。
```python
import asyncio
@@ -482,13 +482,13 @@ agent = Agent(
)
```
-当达到超时时，默认行为是 `timeout_behavior="error_as_result"`，即向模型发送可见的超时消息（例如 `Tool 'slow_lookup' timed out after 2 seconds.`）。
+达到超时时，默认行为是 `timeout_behavior="error_as_result"`，它会发送一条模型可见的超时消息（例如 `Tool 'slow_lookup' timed out after 2 seconds.`）。
-你可以控制超时处理方式：
+你可以控制超时处理：
-- `timeout_behavior="error_as_result"`（默认）：向模型返回超时消息，使其可恢复。
+- `timeout_behavior="error_as_result"`（默认）：向模型返回超时消息，以便模型恢复。
- `timeout_behavior="raise_exception"`：抛出 [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] 并使运行失败。
-- `timeout_error_function=...`：在使用 `error_as_result` 时自定义超时消息。
+- `timeout_error_function=...`：使用 `error_as_result` 时自定义超时消息。
```python
import asyncio
@@ -511,15 +511,15 @@ except ToolTimeoutError as e:
!!! note
- 超时配置仅支持异步 `@function_tool` 处理器。
+ 仅异步 `@function_tool` 处理程序支持超时配置。
-### 处理工具调用中的错误
+### 工具调用中的错误处理
-当你通过 `@function_tool` 创建工具调用时，可以传入 `failure_error_function`。这是在工具调用崩溃时向 LLM 提供错误响应的函数。
+通过 `@function_tool` 创建工具调用时，你可以传入 `failure_error_function`。这是一个在工具调用崩溃时向 LLM 提供错误响应的函数。
-- 默认情况下（即你未传任何值），会运行 `default_tool_error_function`，告知 LLM 发生了错误。
-- 如果你传入自己的错误函数，则运行该函数，并将其响应发送给 LLM。
-- 如果你显式传入 `None`，则任何工具调用错误都会被重新抛出供你处理。这可能是模型生成了无效 JSON 导致的 `ModelBehaviorError`，也可能是你的代码崩溃导致的 `UserError` 等。
+- 默认情况下（即你不传入任何内容），它会运行 `default_tool_error_function`，告知 LLM 发生了错误。
+- 如果你传入自己的错误函数，它会改为运行该函数，并将响应发送给 LLM。
+- 如果你显式传入 `None`，则任何工具调用错误都会重新抛出，由你处理。这可能是模型生成无效 JSON 时的 `ModelBehaviorError`，或你的代码崩溃时的 `UserError` 等。
```python
from agents import function_tool, RunContextWrapper
@@ -542,11 +542,11 @@ def get_user_profile(user_id: str) -> str:
```
-如果你是手动创建 `FunctionTool` 对象，则必须在 `on_invoke_tool` 函数中处理错误。
+如果你手动创建 `FunctionTool` 对象，则必须在 `on_invoke_tool` 函数内部处理错误。
## Agents as tools
-在某些工作流中，你可能希望由一个中心智能体编排一组专用智能体，而不是移交控制权。你可以通过将智能体建模为工具来实现。
+在某些工作流中，你可能希望由一个中央智能体编排一组专门智能体，而不是移交控制权。你可以通过将智能体建模为工具来实现这一点。
```python
from agents import Agent, Runner
@@ -587,7 +587,7 @@ async def main():
### 工具智能体自定义
-`agent.as_tool` 函数是一个便捷方法，便于将智能体转换为工具。它支持常见运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它还通过 `parameters`、`input_builder` 和 `include_input_schema` 支持结构化输入。对于高级编排（例如条件重试、回退行为或链式多个智能体调用），请在你的工具实现中直接使用 `Runner.run`：
+`agent.as_tool` 函数是一个便捷方法，便于将智能体转换为工具。它支持常见运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它还支持通过 `parameters`、`input_builder` 和 `include_input_schema` 实现结构化输入。对于高级编排（例如条件重试、回退行为或链接多个智能体调用），请在工具实现中直接使用 `Runner.run`：
```python
@function_tool
@@ -608,13 +608,13 @@ async def run_my_agent() -> str:
### 工具智能体的结构化输入
-默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）暴露结构化 schema。
+默认情况下，`Agent.as_tool()` 期望单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）来公开结构化 schema。
-附加选项：
+其他选项：
-- `include_input_schema=True` 会在生成的嵌套输入中包含完整 JSON Schema。
-- `input_builder=...` 允许你完全自定义结构化工具参数如何转换为嵌套智能体输入。
-- `RunContextWrapper.tool_input` 在嵌套运行上下文中包含已解析的结构化负载。
+- `include_input_schema=True` 会在生成的嵌套输入中包含完整的 JSON Schema。
+- `input_builder=...` 让你完全自定义结构化工具参数如何变成嵌套智能体输入。
+- `RunContextWrapper.tool_input` 包含嵌套运行上下文中的已解析结构化载荷。
```python
from pydantic import BaseModel, Field
@@ -634,19 +634,19 @@ translator_tool = translator_agent.as_tool(
)
```
-参见 `examples/agent_patterns/agents_as_tools_structured.py` 获取完整可运行代码示例。
+请参阅 `examples/agent_patterns/agents_as_tools_structured.py`，了解完整可运行示例。
-### 工具智能体的审批门控
+### 工具智能体的审批门禁
-`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理条目会出现在 `result.interruptions`；随后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后继续。完整暂停/恢复模式请参见 [Human-in-the-loop guide](human_in_the_loop.md)。
+`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理条目会出现在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复。请参阅[人机协同指南](human_in_the_loop.md)，了解完整的暂停/恢复模式。
### 自定义输出提取
-在某些情况下，你可能希望在将工具智能体输出返回给中心智能体之前进行修改。这在以下场景可能有用：
+在某些情况下，你可能希望在将工具智能体的输出返回给中央智能体之前修改它。如果你想要：
-- 从子智能体聊天历史中提取特定信息（例如 JSON 负载）。
-- 转换或重格式化智能体最终答案（例如将 Markdown 转为纯文本或 CSV）。
-- 当智能体响应缺失或格式错误时，验证输出或提供回退值。
+- 从子智能体的聊天历史中提取特定信息片段（例如 JSON 载荷）。
+- 转换或重新格式化智能体的最终答案（例如将 Markdown 转换为纯文本或 CSV）。
+- 验证输出，或在智能体响应缺失或格式错误时提供回退值。
你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现：
@@ -668,13 +668,13 @@ json_tool = data_agent.as_tool(
```
在自定义提取器内部，嵌套的 [`RunResult`][agents.result.RunResult] 还会暴露
-[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]，这在
-你需要外层工具名、调用 ID 或原始参数来进行嵌套结果后处理时非常有用。
-参见 [Results guide](results.md#agent-as-tool-metadata)。
+[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]，当你在后处理嵌套结果时
+需要外层工具名称、调用 ID 或原始参数，这很有用。
+请参阅[结果指南](results.md#agent-as-tool-metadata)。
-### 流式传输嵌套智能体运行
+### 嵌套智能体运行的流式传输
-向 `as_tool` 传入 `on_stream` 回调，以监听嵌套智能体发出的流式事件，同时在流完成后仍返回其最终输出。
+向 `as_tool` 传入 `on_stream` 回调，以监听嵌套智能体发出的流式传输事件，同时仍在流完成后返回其最终输出。
```python
from agents import AgentToolStreamEvent
@@ -694,15 +694,15 @@ billing_agent_tool = billing_agent.as_tool(
预期行为：
-- 事件类型与 `StreamEvent["type"]` 一致：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。
-- 提供 `on_stream` 会自动让嵌套智能体以流式模式运行，并在返回最终输出前消费完整流。
-- 处理器可以是同步或异步；每个事件按到达顺序交付。
-- 通过模型工具调用触发时会有 `tool_call`；直接调用时它可能为 `None`。
-- 完整可运行示例参见 `examples/agent_patterns/agents_as_tools_streaming.py`。
+- 事件类型与 `StreamEvent["type"]` 相对应：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。
+- 提供 `on_stream` 会自动以流式传输模式运行嵌套智能体，并在返回最终输出前消耗完该流。
+- 处理程序可以是同步或异步的；每个事件会按到达顺序交付。
+- 当工具通过模型工具调用被调用时，`tool_call` 存在；直接调用时它可能为 `None`。
+- 请参阅 `examples/agent_patterns/agents_as_tools_streaming.py`，了解完整可运行示例。
-### 条件性启用工具
+### 条件性工具启用
-你可以使用 `is_enabled` 参数在运行时条件性启用或禁用智能体工具。这使你能够根据上下文、用户偏好或运行时条件动态筛选哪些工具对 LLM 可用。
+你可以使用 `is_enabled` 参数在运行时有条件地启用或禁用智能体工具。这使你能够根据上下文、用户偏好或运行时条件，动态筛选哪些工具可供 LLM 使用。
```python
import asyncio
@@ -763,18 +763,18 @@ asyncio.run(main())
- **可调用函数**：接收 `(context, agent)` 并返回布尔值的函数
- **异步函数**：用于复杂条件逻辑的异步函数
-被禁用的工具在运行时会对 LLM 完全隐藏，这在以下场景很有用：
+禁用的工具在运行时会对 LLM 完全隐藏，因此这适用于：
- 基于用户权限的功能门控
-- 特定环境下的工具可用性（开发 vs 生产）
-- 不同工具配置的 A/B 测试
+- 环境特定的工具可用性（dev 与 prod）
+- 对不同工具配置进行 A/B 测试
- 基于运行时状态的动态工具筛选
## 实验性：Codex 工具
-`codex_tool` 封装了 Codex CLI，使智能体能够在工具调用期间运行工作区范围任务（shell、文件编辑、MCP 工具）。该能力面为实验性，可能变更。
+`codex_tool` 封装了 Codex CLI，使智能体能够在工具调用期间运行作用域限定在工作区内的任务（shell、文件编辑、MCP 工具）。此表面处于实验阶段，可能会发生变化。
-当你希望主智能体在不离开当前运行的前提下，将受限工作区任务委派给 Codex 时可使用它。默认工具名为 `codex`。若设置自定义名称，必须为 `codex` 或以 `codex_` 开头。当智能体包含多个 Codex 工具时，每个名称必须唯一。
+当你希望主智能体将有界的工作区任务委派给 Codex，且不离开当前运行时，请使用它。默认情况下，工具名称是 `codex`。如果你设置自定义名称，它必须是 `codex` 或以 `codex_` 开头。当智能体包含多个 Codex 工具时，每个工具都必须使用唯一名称。
```python
from agents import Agent
@@ -788,7 +788,7 @@ agent = Agent(
sandbox_mode="workspace-write",
working_directory="/path/to/repo",
default_thread_options=ThreadOptions(
- model="gpt-5.4",
+ model="gpt-5.5",
model_reasoning_effort="low",
network_access_enabled=True,
web_search_mode="disabled",
@@ -803,26 +803,26 @@ agent = Agent(
)
```
-从这些选项组开始：
+从以下选项组开始：
-- 执行能力面：`sandbox_mode` 和 `working_directory` 定义 Codex 可操作范围。请配对使用；当工作目录不在 Git 仓库内时，设置 `skip_git_repo_check=True`。
-- 线程默认值：`default_thread_options=ThreadOptions(...)` 配置模型、推理力度、审批策略、附加目录、网络访问和网络检索模式。优先使用 `web_search_mode`，而不是旧版 `web_search_enabled`。
-- 轮次默认值：`default_turn_options=TurnOptions(...)` 配置每轮行为，如 `idle_timeout_seconds` 和可选取消 `signal`。
-- 工具 I/O：工具调用必须至少包含一个 `inputs` 条目，格式为 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。`output_schema` 可用于要求结构化 Codex 响应。
+- 执行表面：`sandbox_mode` 和 `working_directory` 定义 Codex 可以在哪里操作。将它们配对使用；当工作目录不在 Git 仓库中时，设置 `skip_git_repo_check=True`。
+- 线程默认值：`default_thread_options=ThreadOptions(...)` 配置模型、推理强度、审批策略、附加目录、网络访问和网络检索模式。优先使用 `web_search_mode`，而不是旧版 `web_search_enabled`。
+- 轮次默认值：`default_turn_options=TurnOptions(...)` 配置每轮行为，例如 `idle_timeout_seconds` 和可选取消 `signal`。
+- 工具 I/O：工具调用必须至少包含一个 `inputs` 条目，其形式为 `{ "type": "text", "text": ... }` 或 `{ "type": "local_image", "path": ... }`。`output_schema` 让你要求 Codex 返回结构化响应。
-线程复用与持久化是分离控制项：
+线程复用和持久化是独立控制项：
-- `persist_session=True` 会在对同一工具实例重复调用时复用一个 Codex 线程。
-- `use_run_context_thread_id=True` 会在共享同一可变上下文对象的跨运行中，在运行上下文中存储并复用线程 ID。
-- 线程 ID 优先级为：每次调用的 `thread_id`，然后运行上下文线程 ID（若启用），再然后是已配置的 `thread_id` 选项。
-- 默认运行上下文键为：当 `name="codex"` 时为 `codex_thread_id`，当 `name="codex_"` 时为 `codex_thread_id_`。可用 `run_context_thread_id_key` 覆盖。
+- `persist_session=True` 会对同一工具实例的重复调用复用一个 Codex 线程。
+- `use_run_context_thread_id=True` 会在共享同一可变上下文对象的多次运行之间，在运行上下文中存储并复用线程 ID。
+- 线程 ID 优先级为：每次调用的 `thread_id`，然后是运行上下文线程 ID（如果启用），然后是配置的 `thread_id` 选项。
+- 对于 `name="codex"`，默认运行上下文键是 `codex_thread_id`；对于 `name="codex_"`，则是 `codex_thread_id_`。可用 `run_context_thread_id_key` 覆盖它。
运行时配置：
-- 鉴权：设置 `CODEX_API_KEY`（推荐）或 `OPENAI_API_KEY`，或传入 `codex_options={"api_key": "..."}`。
-- 运行时：`codex_options.base_url` 覆盖 CLI base URL。
-- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则 SDK 会先从 `PATH` 解析 `codex`，再回退到内置 vendor 二进制。
-- 环境：`codex_options.env` 完整控制子进程环境。提供后，子进程不会继承 `os.environ`。
+- 认证：设置 `CODEX_API_KEY`（首选）或 `OPENAI_API_KEY`，或传入 `codex_options={"api_key": "..."}`。
+- 运行时：`codex_options.base_url` 会覆盖 CLI base URL。
+- 二进制解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则，SDK 会先从 `PATH` 解析 `codex`，然后回退到捆绑的 vendor 二进制文件。
+- 环境：`codex_options.env` 完全控制子进程环境。提供该项时，子进程不会继承 `os.environ`。
- 流限制：`codex_options.codex_subprocess_stream_limit_bytes`（或 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）控制 stdout/stderr 读取器限制。有效范围为 `65536` 到 `67108864`；默认值为 `8388608`。
- 流式传输：`on_stream` 接收线程/轮次生命周期事件和条目事件（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list` 和 `error` 条目更新）。
- 输出：结果包含 `response`、`usage` 和 `thread_id`；usage 会添加到 `RunContextWrapper.usage`。
@@ -832,4 +832,4 @@ agent = Agent(
- [Codex 工具 API 参考](ref/extensions/experimental/codex/codex_tool.md)
- [ThreadOptions 参考](ref/extensions/experimental/codex/thread_options.md)
- [TurnOptions 参考](ref/extensions/experimental/codex/turn_options.md)
-- 完整可运行代码示例参见 `examples/tools/codex.py` 和 `examples/tools/codex_same_thread.py`。
\ No newline at end of file
+- 请参阅 `examples/tools/codex.py` 和 `examples/tools/codex_same_thread.py`，了解完整可运行示例。
\ No newline at end of file
diff --git a/docs/zh/voice/quickstart.md b/docs/zh/voice/quickstart.md
index edfa88c7a5..b4c9023d68 100644
--- a/docs/zh/voice/quickstart.md
+++ b/docs/zh/voice/quickstart.md
@@ -2,11 +2,11 @@
search:
exclude: true
---
-# 快速开始
+# 快速入门
-## 前置条件
+## 先决条件
-请确保你已按照 Agents SDK 的基础[快速开始说明](../quickstart.md)完成操作，并设置好虚拟环境。然后，从 SDK 安装可选的语音依赖项：
+请确保你已按照 Agents SDK 的基础[快速入门说明](../quickstart.md)完成设置，并配置好虚拟环境。然后，安装 SDK 中可选的语音依赖项：
```bash
pip install 'openai-agents[voice]'
@@ -16,9 +16,9 @@ pip install 'openai-agents[voice]'
需要了解的主要概念是 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]，它是一个 3 步流程：
-1. 运行一个语音转文本模型，将音频转换为文本。
-2. 运行你的代码（通常是智能体工作流），生成结果。
-3. 运行一个文本转语音模型，将结果文本转换回音频。
+1. 运行语音转文本模型，将音频转换为文本。
+2. 运行你的代码（通常是一个智能体工作流）以生成结果。
+3. 运行文本转语音模型，将结果文本转换回音频。
```mermaid
graph LR
@@ -48,7 +48,7 @@ graph LR
## 智能体
-首先，让我们设置一些智能体。如果你曾用这个 SDK 构建过任何智能体，这部分会让你感到熟悉。我们会有几个智能体、一次任务转移和一个工具调用。
+首先，我们来设置一些智能体。如果你已经使用此 SDK 构建过任何智能体，这应该会让你感到熟悉。我们会准备几个智能体、一个任务转移以及一个工具。
```python
import asyncio
@@ -76,7 +76,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -84,22 +84,22 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
```
-## 语音管道
+## 语音流水线
-我们将设置一个简单的语音管道，并使用 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] 作为工作流。
+我们将使用 [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] 作为工作流，设置一个简单的语音流水线。
```python
from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
```
-## 运行管道
+## 流水线运行
```python
import numpy as np
@@ -124,7 +124,7 @@ async for event in result.stream():
```
-## 整体整合
+## 完整组合
```python
import asyncio
@@ -160,7 +160,7 @@ spanish_agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. Speak in Spanish.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
)
agent = Agent(
@@ -168,7 +168,7 @@ agent = Agent(
instructions=prompt_with_handoff_instructions(
"You're speaking to a human, so be polite and concise. If the user speaks in Spanish, handoff to the spanish agent.",
),
- model="gpt-5.4",
+ model="gpt-5.5",
handoffs=[spanish_agent],
tools=[get_weather],
)
@@ -195,4 +195,4 @@ if __name__ == "__main__":
asyncio.run(main())
```
-如果你运行这个示例，智能体会和你说话！查看 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) 中的示例，了解一个你可以亲自与智能体对话的演示。
\ No newline at end of file
+如果你运行这个示例，智能体就会对你说话！请查看 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) 中的示例，了解一个你可以亲自与智能体对话的演示。
\ No newline at end of file