docs: update translated pages

2026-08-01 10:38:39 +09:00
parent 07cdff5cde
commit c9b5d1ba3f
10 changed files with 872 additions and 844 deletions
@@ -4,40 +4,42 @@ search:
 ---
 # サンドボックスクライアント

-このページでは、サンドボックスでの作業をどこで実行するかを選択します。ほとんどの場合、`SandboxAgent` の定義は同じままにし、サンドボックスクライアントとクライアント固有のオプションを [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変更します。
+このページでは、サンドボックスでの処理を実行する場所を選択します。ほとんどの場合、`SandboxAgent` の定義はそのまま使用し、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] のサンドボックスクライアントとクライアント固有のオプションのみを変更します。

 !!! warning "ベータ機能"

-    サンドボックスエージェントはベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能が変更される可能性があります。また、時間とともにより高度な機能が追加される見込みです。
+    サンドボックスエージェントはベータ版です。一般提供までに API の詳細、デフォルト、サポートされる機能が変更される可能性があります。また、今後さらに高度な機能が追加される予定です。

-## 判断ガイド
+## 選択ガイド

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 目的 | まず使うもの | 理由 |
+| 目的 | 最初に使用するもの | 理由 |
 | --- | --- | --- |
-| macOS または Linux での最速のローカル反復 | `UnixLocalSandboxClient` | 追加インストール不要で、シンプルなローカルファイルシステム開発ができます。 |
-| 基本的なコンテナ分離 | `DockerSandboxClient` | 特定のイメージを使って Docker 内で作業を実行します。 |
-| ホスト型実行または本番環境スタイルの分離 | ホスト型サンドボックスクライアント | ワークスペース境界をプロバイダー管理環境へ移します。 |
+| macOS または Linux で最速のローカル反復開発 | `UnixLocalSandboxClient` | 追加のインストールが不要で、ローカルファイルシステムを使用した開発が簡単です。 |
+| 基本的なコンテナ分離 | `DockerSandboxClient` | 指定したイメージを使用して Docker 内で処理を実行します。 |
+| ホスト環境での実行または本番環境相当の分離 | ホスト型サンドボックスクライアント | ワークスペースの境界をプロバイダー管理の環境へ移します。 |

 </div>

 ## ローカルクライアント

-ほとんどのユーザーは、これら 2 つのサンドボックスクライアントのいずれかから始めることをおすすめします。
+ほとんどのユーザーは、次の 2 つのサンドボックスクライアントのいずれかから開始することをお勧めします。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| クライアント | インストール | 選ぶ場面 | 例 |
+| クライアント | インストール | 適している状況 | コード例 |
 | --- | --- | --- | --- |
-| `UnixLocalSandboxClient` | なし | macOS または Linux で最速のローカル反復が必要な場合。ローカル開発の既定として適しています。 | [Unix-local スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
-| `DockerSandboxClient` | `openai-agents[docker]` | コンテナ分離、またはローカルで同等性を保つための特定のイメージが必要な場合。 | [Docker スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
+| `UnixLocalSandboxClient` | なし | macOS または Linux で最速のローカル反復開発を行う場合。ローカル開発に適したデフォルトです。 | [Unix-local スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
+| `DockerSandboxClient` | `openai-agents[docker]` | コンテナ分離が必要な場合、またはローカル環境との整合性を保つために特定のイメージを使用する場合。 | [Docker スターター](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |

 </div>

-Unix-local は、ローカルファイルシステムに対して開発を始める最も簡単な方法です。より強い環境分離や本番環境スタイルの同等性が必要になったら、Docker またはホスト型プロバイダーへ移行してください。
+Unix-local は、ローカルファイルシステムを対象とした開発を開始する最も簡単な方法です。より強力な環境分離や本番環境相当の整合性が必要になった場合は、Docker またはホスト型プロバイダーへ移行してください。

-Unix-local から Docker に切り替えるには、エージェント定義は同じままにして、実行設定だけを変更します。
+`SandboxPathGrant.host_path` は Docker 専用であり、ホスト上のパスをコンテナ内の別の POSIX パスへマッピングします。Unix-local では、同一パスへの許可のみがサポートされます。詳細については、[マニフェストのパス許可](guide.md#manifest)を参照してください。
+
+Unix-local から Docker へ切り替えるには、エージェント定義をそのまま維持し、実行設定のみを変更します。

 ```python
 from docker import from_env as docker_from_env
@@ -54,45 +56,45 @@ run_config = RunConfig(
 )
 ```

-コンテナ分離またはイメージの同等性が必要な場合に使用してください。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
+コンテナ分離またはイメージの整合性が必要な場合に使用してください。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)を参照してください。

 ## マウントとリモートストレージ

-マウントエントリーはどのストレージを公開するかを表し、マウント戦略はサンドボックスバックエンドがそのストレージをどのようにアタッチするかを表します。組み込みのマウントエントリーと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダーの戦略は `agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。
+マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージを接続する方法を記述します。組み込みのマウントエントリと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダー向けの戦略は、`agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。

-一般的なマウントオプション:
+一般的なマウントオプションは次のとおりです。

- `mount_path`: ストレージがサンドボックス内で表示される場所です。相対パスはマニフェストルート配下で解決され、絶対パスはそのまま使用されます。
- `read_only`: 既定は `True` です。サンドボックスがマウントされたストレージへ書き戻す必要がある場合にのみ `False` に設定してください。
- `mount_strategy`: 必須です。マウントエントリーとサンドボックスバックエンドの両方に合う戦略を使用してください。
+- `mount_path`: サンドボックス内でストレージが配置される場所です。相対パスはマニフェストのルートを基準に解決され、絶対パスはそのまま使用されます。
+- `read_only`: デフォルトは `True` です。サンドボックスからマウント済みストレージへ書き戻す必要がある場合にのみ、`False` に設定してください。
+- `mount_strategy`: 必須です。マウントエントリとサンドボックスバックエンドの両方に適合する戦略を使用してください。

-マウントは一時的なワークスペースエントリーとして扱われます。スナップショットと永続化のフローでは、マウントされたリモートストレージを保存済みワークスペースへコピーするのではなく、マウントされたパスをデタッチするかスキップします。
+マウントは、一時的なワークスペースエントリとして扱われます。スナップショットと永続化のフローでは、マウントされたリモートストレージを保存済みワークスペースへコピーする代わりに、マウント済みパスを切り離すかスキップします。

-汎用ローカル / コンテナ戦略:
+汎用のローカル／コンテナ戦略は次のとおりです。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 戦略またはパターン | 使用する場面 | 備考 |
+| 戦略またはパターン | 適している状況 | 注記 |
 | --- | --- | --- |
 | `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | サンドボックスイメージで `rclone` を実行できる場合。 | S3、GCS、R2、Azure Blob、Box をサポートします。`RcloneMountPattern` は `fuse` モードまたは `nfs` モードで実行できます。 |
-| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` があり、Mountpoint スタイルの S3 または S3 互換アクセスが必要な場合。 | `S3Mount` と `GCSMount` をサポートします。 |
-| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` があり、FUSE サポートがある場合。 | `AzureBlobMount` をサポートします。 |
-| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` があり、既存の S3 Files マウントターゲットに到達できる場合。 | `S3FilesMount` をサポートします。 |
-| `DockerVolumeMountStrategy(driver=...)` | Docker がコンテナ起動前にボリュームドライバー対応のマウントをアタッチする必要がある場合。 | Docker のみです。`rclone` は S3、GCS、R2、Azure Blob、Box をサポートし、`mountpoint` は S3 と GCS もサポートします。 |
+| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` が含まれており、Mountpoint 形式で S3 または S3 互換ストレージへアクセスする場合。 | `S3Mount` と `GCSMount` をサポートします。 |
+| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` と FUSE のサポートが含まれている場合。 | `AzureBlobMount` をサポートします。 |
+| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` が含まれており、既存の S3 Files マウントターゲットへ接続できる場合。 | `S3FilesMount` をサポートします。 |
+| `DockerVolumeMountStrategy(driver=...)` | コンテナの起動前に、Docker でボリュームドライバーを使用したマウントを接続する場合。 | Docker 専用です。S3、GCS、R2、Azure Blob、Box は `rclone` をサポートし、S3 と GCS は `mountpoint` もサポートします。 |

 </div>

-## サポートされるホスト型プラットフォーム
+## サポート対象のホスト型プラットフォーム

-ホスト型環境が必要な場合、通常は同じ `SandboxAgent` 定義をそのまま引き継ぎ、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] でサンドボックスクライアントだけを変更します。
+ホスト型環境が必要な場合でも、通常は同じ `SandboxAgent` 定義をそのまま使用でき、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] のサンドボックスクライアントのみを変更します。

-このリポジトリのチェックアウトではなく公開されている SDK を使用している場合は、対応するパッケージ extra を通じてサンドボックスクライアントの依存関係をインストールしてください。
+このリポジトリのチェックアウトではなく公開版 SDK を使用している場合は、対応するパッケージの追加依存関係を通じてサンドボックスクライアントの依存関係をインストールしてください。

-プロバイダー固有のセットアップメモと、チェックイン済みの拡張コード例へのリンクについては、[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md) を参照してください。
+プロバイダー固有の設定に関する注記と、リポジトリに含まれる拡張機能のコード例へのリンクについては、[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)を参照してください。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| クライアント | インストール | 例 |
+| クライアント | インストール | コード例 |
 | --- | --- | --- |
 | `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
 | `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
@@ -104,24 +106,24 @@ run_config = RunConfig(

 </div>

-ホスト型サンドボックスクライアントは、プロバイダー固有のマウント戦略を公開します。ストレージプロバイダーに最も合うバックエンドとマウント戦略を選択してください。
+ホスト型サンドボックスクライアントは、プロバイダー固有のマウント戦略を提供します。ストレージプロバイダーに最も適したバックエンドとマウント戦略を選択してください。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

 | バックエンド | マウントに関する注記 |
 | --- | --- |
-| Docker | `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略で、`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` をサポートします。 |
-| `ModalSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`ModalCloudBucketMountStrategy` による Modal のクラウドバケットマウントをサポートします。インライン認証情報、または名前付きの Modal Secret を使用できます。 |
-| `CloudflareSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`CloudflareBucketMountStrategy` による Cloudflare バケットマウントをサポートします。 |
-| `BlaxelSandboxClient` | `S3Mount`、`R2Mount`、`GCSMount` で、`BlaxelCloudBucketMountStrategy` によるクラウドバケットマウントをサポートします。`agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` による永続的な Blaxel Drives もサポートします。 |
-| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
-| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
-| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
-| `VercelSandboxClient` | `VercelCloudBucketMountStrategy` と `S3Mount` による、作成時限定の S3 および S3 互換バケットマウントをサポートします。マウントを含むセッションは再開できず、インライン認証情報を使用するには `allow_s3_credential_exposure=True` が必要です。 |
+| Docker | `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略を使用して、`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` をサポートします。 |
+| `ModalSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`ModalCloudBucketMountStrategy` を使用した Modal クラウドバケットのマウントをサポートします。インライン認証情報または名前付き Modal Secret を使用できます。 |
+| `CloudflareSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`CloudflareBucketMountStrategy` を使用した Cloudflare バケットのマウントをサポートします。 |
+| `BlaxelSandboxClient` | `S3Mount`、`R2Mount`、`GCSMount` で、`BlaxelCloudBucketMountStrategy` を使用したクラウドバケットのマウントをサポートします。また、`agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` を使用した永続的な Blaxel Drive もサポートします。 |
+| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` を使用した、rclone ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` を使用した、rclone ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` を使用した、rclone ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `VercelSandboxClient` | `S3Mount` で `VercelCloudBucketMountStrategy` を使用した、作成時のみの S3 および S3 互換バケットのマウントをサポートします。マウントされたセッションは再開できません。また、インライン認証情報を使用するには `allow_s3_credential_exposure=True` が必要です。 |

 </div>

-以下の表は、各バックエンドが直接マウントできるリモートストレージエントリーをまとめたものです。
+次の表は、各バックエンドが直接マウントできるリモートストレージエントリをまとめたものです。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

@@ -138,4 +140,4 @@ run_config = RunConfig(

 </div>

-実行可能なコード例をさらに見るには、ローカル、コーディング、メモリ、ハンドオフ、エージェント合成パターンについては [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox) を、ホスト型サンドボックスクライアントについては [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions) を参照してください。
+実行可能なコード例をさらに確認するには、ローカル、コーディング、メモリ、ハンドオフ、エージェント構成のパターンについては [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)を、ホスト型サンドボックスクライアントについては [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)を参照してください。
@@ -4,11 +4,11 @@ search:
 ---
 # セッション

-Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。
+Agents SDK には、複数回のエージェント実行にわたって会話履歴を自動的に維持する組み込みのセッションメモリが用意されているため、ターン間で `.to_input_list()` を手動で処理する必要がありません。

-セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えておいてほしいチャットアプリケーションや複数ターンの会話を構築する場合に特に便利です。
+セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを記憶させたいチャットアプリケーションや複数ターンの会話を構築する場合に特に便利です。

-SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは、同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI のサーバー管理による継続を使用したい場合は、セッションを重ねて使うのではなく、それらの仕組みのいずれかを選択してください。
+SDK にクライアント側のメモリを管理させたい場合は、セッションを使用してください。同じ実行内で、セッションを `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI サーバーが管理する継続機能を使用する場合は、セッションと重ねて使用せず、これらのメカニズムのいずれかを選択してください。

 ## クイックスタート

@@ -51,7 +51,7 @@ print(result.final_output)  # "Approximately 39 million"

 ## 同じセッションによる中断された実行の再開

-実行が承認待ちで一時停止した場合は、同じセッションインスタンス（または同じバッキングストアを指す別のセッションインスタンス）で再開し、再開されたターンが同じ保存済み会話履歴を継続するようにします。
+承認待ちで実行が一時停止した場合は、再開されたターンが同じ保存済み会話履歴を継続できるように、同じセッションインスタンス、または同じバッキングストアを指す別のセッションインスタンスを使用して再開してください。

 ```python
 result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -63,31 +63,31 @@ if result.interruptions:
    result = await Runner.run(agent, state, session=session)
 ```

-## コアセッション動作
+## セッションの基本動作

-セッションメモリが有効な場合:
+セッションメモリが有効な場合、次のように動作します。

-1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの前に追加します。
-2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）がセッションに自動的に保存されます。
-3. **コンテキストの保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。
+1. **各実行の前**: Runner はセッションの会話履歴を自動的に取得し、入力項目の先頭に追加します。
+2. **各実行の後**: 実行中に生成されたすべての新しい項目（ユーザー入力、アシスタントの応答、ツール呼び出しなど）が、セッションに自動的に保存されます。
+3. **コンテキストの保持**: 同じセッションを使用する後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。

-これにより、`.to_input_list()` を手動で呼び出したり、実行間の会話状態を管理したりする必要がなくなります。
+これにより、`.to_input_list()` を手動で呼び出し、実行間の会話状態を管理する必要がなくなります。

-## 履歴と新しい入力のマージ方法の制御
+## 履歴と新規入力のマージ制御

-セッションを渡すと、ランナーは通常、モデル入力を次のように準備します。
+セッションを渡すと、Runner は通常、モデル入力を次の順序で準備します。

 1. セッション履歴（`session.get_items(...)` から取得）
-2. 新しいターン入力
+2. 新しいターンの入力

-モデル呼び出しの前にこのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは次の 2 つのリストを受け取ります。
+モデルを呼び出す前のこのマージ処理をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは次の 2 つのリストを受け取ります。

-   `history`: 取得されたセッション履歴（すでに入力アイテム形式に正規化済み）
-   `new_input`: 現在のターンの新しい入力アイテム
+-   `history`: 取得したセッション履歴（入力項目形式に正規化済み）
+-   `new_input`: 現在のターンの新しい入力項目

-モデルに送信する最終的な入力アイテムのリストを返します。
+モデルに送信する最終的な入力項目のリストを返してください。

-コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK は新しいターンに属するアイテムのみを永続化します。そのため、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。
+コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは新しいターンに属する項目のみです。そのため、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッション項目が新しい入力として再度保存されることはありません。

 ```python
 from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -109,16 +109,16 @@ result = await Runner.run(
 )
 ```

-セッションがアイテムを保存する方法を変更せずに、カスタムの枝刈り、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終的な処理が必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。
+セッションが項目を保存する方法を変更せずに、履歴の独自の枝刈り、並べ替え、または選択的な追加が必要な場合に使用します。モデル呼び出しの直前に最終処理が必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。

 ## 取得する履歴の制限

-各実行の前に取得する履歴の量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。
+各実行前に取得する履歴の量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。

-   `SessionSettings(limit=None)`（デフォルト）: 利用可能なすべてのセッションアイテムを取得します
-   `SessionSettings(limit=N)`: 直近の `N` アイテムのみを取得します
+-   `SessionSettings(limit=None)`（デフォルト）: 利用可能なすべてのセッション項目を取得します
+-   `SessionSettings(limit=N)`: 最新の `N` 項目のみを取得します

-これは、[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を介して実行ごとに適用できます。
+これは、[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を使用して実行ごとに適用できます。

 ```python
 from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
@@ -134,13 +134,13 @@ result = await Runner.run(
 )
 ```

-セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズを上限設定したい長い会話で便利です。
+セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について、`None` 以外の値を上書きします。これは、セッションのデフォルト動作を変更せずに取得件数を制限したい長い会話で役立ちます。

 ## メモリ操作

 ### 基本操作

-セッションは、会話履歴を管理するためのいくつかの操作をサポートしています。
+セッションでは、会話履歴を管理するための複数の操作を使用できます。

 ```python
 from agents import SQLiteSession
@@ -165,9 +165,9 @@ print(last_item)  # {"role": "assistant", "content": "Hi there!"}
 await session.clear_session()
 ```

-### 修正のための pop_item の使用
+### 修正での pop_item の使用

-`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したりしたい場合に特に便利です。
+`pop_item` メソッドは、会話の最後の項目を取り消したり変更したりする場合に特に便利です。

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -198,32 +198,32 @@ print(f"Agent: {result.final_output}")

 ## 組み込みセッション実装

-SDK は、さまざまなユースケース向けに複数のセッション実装を提供しています。
+SDK には、さまざまなユースケースに対応する複数のセッション実装が用意されています。

 ### 組み込みセッション実装の選択

-以下の詳細な例を読む前に、開始点を選ぶためにこの表を使用してください。
+以下の詳細な例を読む前に、この表を使用して開始点を選択してください。

-| セッションタイプ | 最適な用途 | 注記 |
+| セッションタイプ | 最適な用途 | 備考 |
 | --- | --- | --- |
-| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルバックまたはインメモリ |
-| `AsyncSQLiteSession` | `aiosqlite` を使用した非同期 SQLite | 非同期ドライバー対応の拡張バックエンド |
-| `RedisSession` | ワーカーやサービス間で共有するメモリ | 低レイテンシの分散デプロイに適しています |
-| `SQLAlchemySession` | 既存データベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースで動作します |
-| `MongoDBSession` | すでに MongoDB を使用しているアプリ、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo；順序付け用のアトミックシーケンスカウンター |
-| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数のステートストアに加え、TTL と整合性制御をサポートします |
-| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API をバックエンドとする履歴 |
-| `OpenAIResponsesCompactionSession` | 自動圧縮を伴う長い会話 | 別のセッションバックエンドをラップします |
-| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析 | より多機能です。専用ページを参照してください |
-| `EncryptedSession` | 別のセッション上での暗号化と TTL | ラッパーです。まず基盤となるバックエンドを選択してください |
+| `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込みで軽量、ファイルベースまたはインメモリ |
+| `AsyncSQLiteSession` | `aiosqlite` を使用する非同期 SQLite | 非同期ドライバーをサポートする拡張バックエンド |
+| `RedisSession` | ワーカーやサービス間での共有メモリ | 低レイテンシーの分散デプロイに適しています |
+| `SQLAlchemySession` | 既存のデータベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースで動作します |
+| `MongoDBSession` | MongoDB をすでに使用しているアプリ、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo。順序付け用のアトミックなシーケンスカウンター |
+| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブなデプロイ | 複数のステートストアに加え、TTL と整合性制御をサポートします |
+| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API を利用した履歴 |
+| `OpenAIResponsesCompactionSession` | 自動コンパクションを使用する長い会話 | 別のセッションバックエンドをラップします |
+| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析が必要な場合 | より多機能です。専用ページを参照してください |
+| `EncryptedSession` | 別のセッションに暗号化と TTL を追加する場合 | ラッパーです。まず基盤となるバックエンドを選択してください |

-一部の実装には、追加の詳細を含む専用ページがあります。それらは各サブセクション内でリンクされています。
+一部の実装には追加の詳細を説明する専用ページがあり、それぞれのサブセクション内にリンクがあります。

-ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドとアイテムの永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置き換えではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。
+ChatKit 用の Python サーバーを実装する場合は、ChatKit のスレッドと項目の永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアをそのまま置き換えることはできません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。

 ### OpenAI Conversations API セッション

-`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations)を使用します。
+`OpenAIConversationsSession` を通じて、[OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations)を使用します。

 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -257,11 +257,11 @@ result = await Runner.run(
 print(result.final_output)  # "California"
 ```

-### OpenAI Responses 圧縮セッション
+### OpenAI Responses コンパクションセッション

-Responses API（`responses.compact`）で保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターンの後に自動的に圧縮できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。
+Responses API（`responses.compact`）を使用して保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターンの後に自動的にコンパクションを実行できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。

-#### 一般的な使用方法（自動圧縮）
+#### 一般的な使用方法（自動コンパクション）

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```

-デフォルトでは、候補しきい値に達すると各ターンの後に圧縮が実行されます。
+デフォルトでは、候補のしきい値に達すると、各ターンの後にコンパクションが実行されます。

-`compaction_mode="previous_response_id"` は、Responses API の応答 ID でターンをすでに連鎖させている場合に最も適しています。`compaction_mode="input"` は、代わりに現在のセッションアイテムから圧縮リクエストを再構築します。これは、応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に便利です。デフォルトの `"auto"` は、利用可能な中で最も安全な選択肢を選びます。
+Responses API のレスポンス ID を使用してターンをすでに連結している場合は、`compaction_mode="previous_response_id"` が最適です。一方、`compaction_mode="input"` は、現在のセッション項目からコンパクションリクエストを再構築します。これは、レスポンスチェーンを利用できない場合や、セッション内容を信頼できる唯一の情報源にしたい場合に便利です。デフォルトの `"auto"` は、利用可能な最も安全なオプションを選択します。

-エージェントが `ModelSettings(store=False)` で実行される場合、Responses API は後で検索するための最後の応答を保持しません。このステートレスな構成では、デフォルトの `"auto"` モードは `previous_response_id` に依存するのではなく、入力ベースの圧縮にフォールバックします。完全な例については、[`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。
+エージェントが `ModelSettings(store=False)` で実行される場合、Responses API は後で参照できるように最後のレスポンスを保持しません。このステートレスな構成では、デフォルトの `"auto"` モードは `previous_response_id` に依存せず、入力ベースのコンパクションにフォールバックします。完全な例については、[`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)を参照してください。

-#### auto-compaction によるストリーミングのブロック
+#### 自動コンパクションによるストリーミングのブロック

-圧縮はセッション履歴をクリアして書き換えるため、SDK は実行完了とみなす前に圧縮の完了を待ちます。ストリーミングモードでは、圧縮が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになることがあります。
+コンパクションではセッション履歴がクリアされて書き換えられるため、SDK はコンパクションが完了するまで実行を完了と見なしません。ストリーミングモードでは、コンパクションの処理が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになることがあります。

-低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動圧縮を無効にし、ターン間（またはアイドル時間中）に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ圧縮を強制するかを決めることができます。
+低レイテンシーのストリーミングやターンの迅速な切り替えが必要な場合は、自動コンパクションを無効にし、ターン間またはアイドル時間中に `run_compaction()` を自分で呼び出してください。独自の基準に基づいて、コンパクションを強制するタイミングを決定できます。

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -332,7 +332,7 @@ result = await Runner.run(

 ### 非同期 SQLite セッション

-`aiosqlite` をバックエンドとする SQLite の永続化が必要な場合は、`AsyncSQLiteSession` を使用します。
+`aiosqlite` を基盤とする SQLite 永続化が必要な場合は、`AsyncSQLiteSession` を使用します。

 ```bash
 pip install aiosqlite
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)

 ### Redis セッション

-複数のワーカーまたはサービス間で共有セッションメモリを使用するには、`RedisSession` を使用します。
+複数のワーカーまたはサービス間でセッションメモリを共有するには、`RedisSession` を使用します。

 ```bash
 pip install openai-agents[redis]
@@ -365,11 +365,14 @@ session = RedisSession.from_url(
    url="redis://localhost:6379/0",
 )
 result = await Runner.run(agent, "Hello", session=session)
+await session.close()
 ```

+`from_url(...)` は Redis クライアントを作成して所有します。`close()` の後、セッションは終了状態になり、それ以降のセッション操作では `RuntimeError` が発生します。`close()` を繰り返し、または同時に呼び出しても安全です。アプリケーションがすでに Redis クライアントを管理している場合は、`redis_client=...` を指定して `RedisSession(...)` を直接構築してください。その場合、`close()` は何も行わず、呼び出し元がクライアントの所有権とセッションの利用可能性の両方を維持します。
+
 ### SQLAlchemy セッション

-SQLAlchemy がサポートする任意のデータベースを使用した、本番対応の Agents SDK セッション永続化です。
+SQLAlchemy がサポートする任意のデータベースを使用した、本番環境向けの Agents SDK セッション永続化です。

 ```python
 from agents.extensions.memory import SQLAlchemySession
@@ -391,7 +394,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True)

 ### Dapr セッション

-すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なるステートストアバックエンドへ移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。
+Dapr サイドカーをすでに実行している場合、またはエージェントコードを変更せずに異なるステートストアバックエンド間で移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。

 ```bash
 pip install openai-agents[dapr]
@@ -412,18 +415,19 @@ async with DaprSession.from_address(
    print(result.final_output)
 ```

-注記:
+注意事項:

-   `from_address(...)` は Dapr クライアントを作成し、所有します。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。
-   基盤となるステートストアが TTL をサポートしている場合に古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。
-   より強い read-after-write 保証が必要な場合は、`consistency=DAPR_CONSISTENCY_STRONG` を渡します。
-   Dapr Python SDK は HTTP サイドカーエンドポイントもチェックします。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。
-   ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順については、[`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) を参照してください。
+-   `from_address(...)` は Dapr クライアントを作成して所有します。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。
+-   コンテキストを終了するか `close()` を呼び出すと、所有クライアントを使用するセッションは終了状態になります。それ以降のセッション操作では `RuntimeError` が発生しますが、`close()` を繰り返し、または同時に呼び出しても安全です。注入されたクライアントを使用する場合、`close()` は何も行わず、セッションは引き続き使用できます。
+-   バッキングステートストアが TTL をサポートしている場合、古いセッションデータを自動的に期限切れにするには `ttl=...` を渡します。
+-   書き込み後の読み取りについて、より強い保証が必要な場合は `consistency=DAPR_CONSISTENCY_STRONG` を渡します。
+-   Dapr Python SDK は HTTP サイドカーエンドポイントも確認します。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` を指定して Dapr を起動してください。
+-   ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順については、[`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)を参照してください。


 ### MongoDB セッション

-すでに MongoDB を使用しているアプリケーション、または水平スケーラブルでマルチプロセス対応のセッションストレージが必要なアプリケーションには、`MongoDBSession` を使用します。
+MongoDB をすでに使用しているアプリケーション、または水平スケーリング可能なマルチプロセスのセッションストレージが必要なアプリケーションでは、`MongoDBSession` を使用します。

 ```bash
 pip install openai-agents[mongodb]
@@ -446,12 +450,12 @@ print(result.final_output)
 await session.close()
 ```

-注記:
+注意事項:

-   `from_uri(...)` は `AsyncMongoClient` を作成し、所有し、`session.close()` で閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op となり、ライフサイクルは呼び出し元が保持します。
-   ほかの変更なしに、`from_uri(...)` に `mongodb+srv://user:password@cluster.example.mongodb.net` URI を渡すことで [MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。
-   2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルトは `agent_sessions`）と `messages_collection=`（デフォルトは `agent_messages`）で設定できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントは、同時実行の書き込み元やプロセスをまたいで順序を保持する単調増加の `seq` カウンターを持ちます。
-   最初の実行前に接続性を確認するには、`await session.ping()` を使用します。
+-   `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` で閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は何も行わず、ライフサイクルの管理は呼び出し元が引き続き行います。
+-   `mongodb+srv://user:password@cluster.example.mongodb.net` URI を `from_uri(...)` に渡すことで、ほかに変更を加えずに [MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。
+-   2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルトは `agent_sessions`）と `messages_collection=`（デフォルトは `agent_messages`）で設定できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントには単調増加する `seq` カウンターが含まれ、同時に書き込む複数のライターやプロセス間でも順序が保持されます。
+-   最初の実行前に接続を確認するには、`await session.ping()` を使用します。

 ### 高度な SQLite セッション

@@ -479,7 +483,7 @@ await session.create_branch_from_turn(2)  # Branch from turn 2

 ### 暗号化セッション

-任意のセッション実装向けの透過的な暗号化ラッパーです。
+任意のセッション実装に対する透過的な暗号化ラッパーです。

 ```python
 from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -506,13 +510,13 @@ result = await Runner.run(agent, "Hello", session=session)

 ### その他のセッションタイプ

-組み込みの選択肢はほかにもいくつかあります。`examples/memory/` と `extensions/memory/` 以下のソースコードを参照してください。
+ほかにもいくつかの組み込みオプションがあります。`examples/memory/` および `extensions/memory/` 配下のソースコードを参照してください。

 ## 運用パターン

 ### セッション ID の命名

-会話を整理しやすい、意味のあるセッション ID を使用してください。
+会話の整理に役立つ、意味のあるセッション ID を使用してください。

 -   ユーザーベース: `"user_12345"`
 -   スレッドベース: `"thread_abc123"`
@@ -520,18 +524,18 @@ result = await Runner.run(agent, "Hello", session=session)

 ### メモリの永続化

-   一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します
-   永続的な会話にはファイルベース SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します
+-   一時的な会話には、インメモリ SQLite（`SQLiteSession("session_id")`）を使用します
+-   永続的な会話には、ファイルベースの SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します
 -   `aiosqlite` ベースの実装が必要な場合は、非同期 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）を使用します
-   共有された低レイテンシのセッションメモリには、Redis バックのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します
-   SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy を利用したセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) を使用します
-   すでに MongoDB を使用しているアプリケーション、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します
-   組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドをサポートする本番クラウドネイティブデプロイには、Dapr ステートストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します
+-   共有された低レイテンシーのセッションメモリには、Redis ベースのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します
+-   SQLAlchemy がサポートする既存のデータベースを使用する本番システムには、SQLAlchemy ベースのセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します
+-   MongoDB をすでに使用しているアプリケーション、または水平スケーリング可能なマルチプロセスのセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します
+-   組み込みのテレメトリー、トレーシング、データ分離を備え、30 種類以上のデータベースバックエンドをサポートする本番環境のクラウドネイティブなデプロイには、Dapr ステートストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します
 -   OpenAI Conversations API に履歴を保存したい場合は、OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します
-   透過的な暗号化と TTL ベースの有効期限で任意のセッションをラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します
-   より高度なユースケースでは、ほかの本番システム（たとえば Django）向けのカスタムセッションバックエンドの実装を検討してください
+-   任意のセッションを透過的な暗号化と TTL ベースの有効期限でラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します
+-   より高度なユースケースでは、ほかの本番システム（Django など）向けのカスタムセッションバックエンドの実装を検討してください

-### 複数セッション
+### 複数のセッション

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -554,7 +558,7 @@ result2 = await Runner.run(
 )
 ```

-### セッション共有
+### セッションの共有

 ```python
 # Different agents can share the same session
@@ -641,7 +645,7 @@ if __name__ == "__main__":

 ## カスタムセッション実装

-[`Session`][agents.memory.session.Session] プロトコルに従うクラスを作成することで、独自のセッションメモリを実装できます。
+[`Session`][agents.memory.session.Session] プロトコルに準拠するクラスを作成することで、独自のセッションメモリを実装できます。

 ```python
 from agents.memory.session import SessionABC
@@ -686,26 +690,26 @@ result = await Runner.run(

 ## コミュニティによるセッション実装

-コミュニティは追加のセッション実装を開発しています。
+コミュニティによって、追加のセッション実装が開発されています。

 | パッケージ | 説明 |
 |---------|-------------|
-| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django 対応データベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション |
+| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション |

-セッション実装を構築した場合は、ぜひドキュメント PR を送ってここに追加してください。
+セッション実装を構築した場合は、ここに追加するためのドキュメント PR をぜひ送信してください。

 ## API リファレンス

 詳細な API ドキュメントについては、以下を参照してください。

-   [`Session`][agents.memory.session.Session] - プロトコルインターフェイス
+-   [`Session`][agents.memory.session.Session] - プロトコルインターフェース
 -   [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 実装
-   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 圧縮ラッパー
+-   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API コンパクションラッパー
 -   [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本的な SQLite 実装
-   [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` に基づく非同期 SQLite 実装
-   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis バックのセッション実装
-   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy を利用した実装
-   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB バックのセッション実装
+-   [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` ベースの非同期 SQLite 実装
+-   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis ベースのセッション実装
+-   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy ベースの実装
+-   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB ベースのセッション実装
 -   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr ステートストア実装
-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite
+-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析機能を備えた拡張 SQLite
 -   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向けの暗号化ラッパー
@@ -6,42 +6,42 @@ search:

 ツールを使用すると、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。

-   OpenAI がホストするツール: OpenAI のサーバー上でモデルとともに実行されます。
+-   OpenAI がホストするツール: OpenAI のサーバー上でモデルと並行して実行されます。
 -   ローカル／ランタイム実行ツール: `ComputerTool` と `ApplyPatchTool` は常にご利用の環境で実行され、`ShellTool` はローカルまたはホスト型コンテナで実行できます。
 -   Function Calling: 任意の Python 関数をツールとしてラップします。
-   Agents as tools: 完全なハンドオフを行わずに、エージェントを呼び出し可能なツールとして公開します。
-   実験的機能: Codex ツール: ツール呼び出しからワークスペーススコープの Codex タスクを実行します。
+-   Agents as tools: 完全なハンドオフを行わず、エージェントを呼び出し可能なツールとして公開します。
+-   試験的機能: Codex ツール: ツール呼び出しからワークスペーススコープの Codex タスクを実行します。

 ## ツールタイプの選択

-このページをカタログとして利用し、ご自身が制御するランタイムに該当するセクションへ移動してください。
+このページをカタログとして使用し、管理するランタイムに該当するセクションへ移動してください。

 | 目的 | 参照先 |
 | --- | --- |
 | OpenAI が管理するツール（Web 検索、ファイル検索、Code Interpreter、ホスト型 MCP、画像生成）を使用する | [ホスト型ツール](#hosted-tools) |
-| ツール検索を使用して、大規模なツール群の読み込みをランタイムまで遅延させる | [ホスト型ツール検索](#hosted-tool-search) |
+| ツール検索を使用して、大規模なツールサーフェスの読み込みをランタイムまで遅延する | [ホスト型ツール検索](#hosted-tool-search) |
 | 生成された JavaScript から複数のツール呼び出しを調整する | [プログラムによるツール呼び出し](#programmatic-tool-calling) |
-| ご自身のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) |
+| 独自のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) |
 | Python 関数をツールとしてラップする | [関数ツール](#function-tools) |
 | ハンドオフを行わずに、あるエージェントから別のエージェントを呼び出せるようにする | [Agents as tools](#agents-as-tools) |
-| エージェントからワークスペーススコープの Codex タスクを実行する | [実験的機能: Codex ツール](#experimental-codex-tool) |
+| エージェントからワークスペーススコープの Codex タスクを実行する | [試験的機能: Codex ツール](#experimental-codex-tool) |

 ## ホスト型ツール

 OpenAI は、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合に、いくつかの組み込みツールを提供しています。

-   [`WebSearchTool`][agents.tool.WebSearchTool] を使用すると、エージェントは Web を検索できます。
+-   [`WebSearchTool`][agents.tool.WebSearchTool] を使用すると、エージェントが Web を検索できます。
 -   [`FileSearchTool`][agents.tool.FileSearchTool] を使用すると、OpenAI ベクトルストアから情報を取得できます。
-   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] を使用すると、LLM はサンドボックス環境でコードを実行できます。
+-   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] を使用すると、LLM がサンドボックス環境でコードを実行できます。
 -   [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモート MCP サーバーのツールをモデルに公開します。
 -   [`ImageGenerationTool`][agents.tool.ImageGenerationTool] は、プロンプトから画像を生成します。
-   [`ToolSearchTool`][agents.tool.ToolSearchTool] を使用すると、モデルは遅延読み込みされたツール、名前空間、またはホスト型 MCP サーバーを必要に応じて読み込めます。
-   [`ProgrammaticToolCallingTool`][agents.tool.ProgrammaticToolCallingTool] を使用すると、モデルは生成された JavaScript から対象ツールを調整できます。
+-   [`ToolSearchTool`][agents.tool.ToolSearchTool] を使用すると、モデルが遅延ツール、名前空間、またはホスト型 MCP サーバーをオンデマンドで読み込めます。
+-   [`ProgrammaticToolCallingTool`][agents.tool.ProgrammaticToolCallingTool] を使用すると、モデルが生成した JavaScript から対象ツールを調整できます。

 ホスト型検索の高度なオプション:

-   `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
@@ -64,9 +64,9 @@ async def main():

 ### ホスト型ツール検索

-ツール検索を使用すると、OpenAI Responses モデルは大規模なツール群の読み込みをランタイムまで遅延させ、現在のターンに必要なサブセットのみを読み込めます。これは、多数の関数ツール、名前空間グループ、またはホスト型 MCP サーバーがあり、すべてのツールを事前に公開せずにツールスキーマのトークン数を削減したい場合に便利です。
+ツール検索を使用すると、OpenAI Responses モデルは大規模なツールサーフェスの読み込みをランタイムまで遅延できるため、現在のターンに必要なサブセットのみを読み込みます。これは、多数の関数ツール、名前空間グループ、またはホスト型 MCP サーバーがあり、すべてのツールを事前に公開することなくツールスキーマのトークン数を削減したい場合に便利です。

-エージェントを構築する時点で候補ツールがすでに判明している場合は、ホスト型ツール検索から始めてください。アプリケーション側で読み込む対象を動的に決定する必要がある場合、Responses API はクライアント実行型のツール検索もサポートしていますが、標準の `Runner` はこのモードを自動実行しません。
+エージェントを構築する時点で候補ツールがすでに判明している場合は、ホスト型ツール検索から始めてください。アプリケーションで読み込む対象を動的に決定する必要がある場合、Responses API はクライアント実行型のツール検索もサポートしますが、標準の `Runner` はこのモードを自動実行しません。

 ```python
 from typing import Annotated
@@ -109,28 +109,28 @@ 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()` を 1 つだけ追加してください。
-   検索可能な対象には、`@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])`、`HostedMCPTool(tool_config={..., "defer_loading": True})` が含まれます。
-   遅延読み込みされる関数ツールは、`ToolSearchTool()` と組み合わせる必要があります。名前空間のみの構成でも、モデルが適切なグループを必要に応じて読み込めるよう、`ToolSearchTool()` を使用できます。
-   `tool_namespace()` は、複数の `FunctionTool` インスタンスを共通の名前空間名と説明の下にグループ化します。これは通常、`crm`、`billing`、`shipping` など、関連するツールが多数ある場合に最適です。
+-   エージェントに遅延読み込みサーフェスを設定する場合は、`ToolSearchTool()` をちょうど 1 つ追加してください。
+-   検索可能なサーフェスには、`@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` を参照してください。
+-   可能な場合は、個別に遅延される多数の関数よりも、名前空間またはホスト型 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)。

 ### プログラムによるツール呼び出し

-プログラムによるツール呼び出しを使用すると、サポート対象の OpenAI Responses モデルは、対象ツールを呼び出してその出力を組み合わせ、1 つの結果をモデルに返す JavaScript を生成できます。これは、ツール呼び出しごとにモデルとのラウンドトリップを行わずに、ループ、分岐、並列呼び出し、中間計算を活用できる、範囲が限定されたワークフローに役立ちます。
+プログラムによるツール呼び出しを使用すると、サポート対象の OpenAI Responses モデルが JavaScript を生成し、対象ツールを呼び出して、その出力を結合し、1 つの実行結果をモデルに返せます。各ツール呼び出し後にモデルとのラウンドトリップを行うことなく、ループ、分岐、並列呼び出し、中間計算を活用できる範囲の限定されたワークフローに便利です。

-生成されたプログラムは、新しいホスト型 V8 環境で実行されます。Node.js API、ファイルシステムやネットワークへのアクセス、永続的なプロセスは利用できません。プログラムが操作できるのは、明示的に許可したツールのみです。
+生成されたプログラムは、新しいホスト型 V8 環境で実行されます。Node.js API、ファイルシステムやネットワークへのアクセス、永続的なプロセスは使用できません。プログラムが操作できるのは、明示的に許可したツールのみです。

 ```python
 from pydantic import BaseModel
@@ -165,23 +165,24 @@ result = Runner.run_sync(agent, "Check inventory for desk-lamp and summarize it.
 print(result.final_output)
 ```

-注意事項:
+留意事項:

 -   プログラムによるツール呼び出しは、サポート対象の OpenAI Responses モデルでのみ利用できます。`ProgrammaticToolCallingTool()` と `tool_choice="programmatic_tool_calling"` は、Chat Completions モデルおよび Responses 以外のバックエンドでは拒否されます。
-   エージェントには、`ProgrammaticToolCallingTool()` を最大 1 つ追加できます。エージェントは、プログラムから呼び出し可能なツール、`ToolSearchTool()`、またはプロンプトで管理されるツール群のうち、少なくとも 1 つも公開する必要があります。
-   `allowed_callers` は、ツールを呼び出す方法を制御します。省略すると、モデルからの直接呼び出しのみが許可されます。プログラムからのみアクセスできるようにするには `["programmatic"]`、両方を許可するには `["direct", "programmatic"]` を使用してください。
-   オプトインできる SDK のツールタイプは、`FunctionTool`、`CustomTool`、`ShellTool`、`ApplyPatchTool`、`HostedMCPTool`、`CodeInterpreterTool` です。関数ツール、カスタムツール、シェルツール、パッチ適用ツールでは、`allowed_callers` を直接指定できます。ホスト型 MCP と Code Interpreter では、`tool_config` 内に `allowed_callers` を設定してください。
-   `@function_tool(allowed_callers=[...])` では、Pydantic モデル、TypedDict、データクラスなどの構造化された戻り値アノテーションが自動的に厳密なオブジェクト出力スキーマとなり、値がプログラムに返される前に検証されます。関数に利用可能なアノテーションがない場合は `output_type=...` を使用し、厳密なオブジェクトスキーマがすでにある場合は、より低レベルのエスケープハッチである `output_json_schema={...}` を使用してください。`output_type` と `output_json_schema` は同時に使用できません。単純な `str`、`Any`、`None` の戻り値には型が付けられません。
-   プログラムが所有する SDK ツールでも、通常の Runner ライフサイクルが使用されます。ツールの入力および出力ガードレール、フック、タイムアウト、同時実行数の制限、再試行、承認、セッション、`RunState` の一時停止／再開動作は引き続き適用され、SDK は各子呼び出しとプログラム呼び出し元との関係を保持します。
-   承認が重要なツールや影響の大きいツールは、通常、直接呼び出しとして維持する方が適しています。これにより、大規模なプログラムの一部になる前に、各アクションを人が確認できます。プログラムが所有する呼び出しが承認待ちで一時停止した場合は、通常どおり `RunState` を通じて中断を解決し、元の実行を再開してください。
-   プログラムによるツール呼び出しは、[ホスト型ツール検索](#hosted-tool-search)と組み合わせられます。生成されたプログラムが遅延ツールを呼び出すには、その前にモデルがツールを読み込む必要があります。
-   `program` アイテムと、プログラムが所有する子呼び出しは、[`ToolCallItem`][agents.items.ToolCallItem] エントリとして表示されます。対応する `program_output` は、[`ToolCallOutputItem`][agents.items.ToolCallOutputItem] として表示されます。確認方法の詳細については、[実行結果](results.md#new-items)および[ストリーミング](streaming.md#run-item-event-names)を参照してください。
-   同時実行による在庫計画の完全なコード例については、`examples/tools/programmatic_tool_calling.py` を参照してください。
+-   エージェントには `ProgrammaticToolCallingTool()` を最大 1 つ追加できます。また、エージェントはプログラムから呼び出し可能なツールを少なくとも 1 つ、名前空間、遅延関数、遅延されたホスト型 MCP サーバーに基づく `ToolSearchTool()`、または不透明なプロンプト管理ツールサーフェスを公開する必要があります。検索可能なサーフェスを伴わない単独の `ToolSearchTool()` は拒否されます。
+-   `allowed_callers` は、ツールの呼び出し方法を制御します。省略すると、モデルからの直接呼び出しのみが許可されます。プログラム専用アクセスには `["programmatic"]`、両方を許可するには `["direct", "programmatic"]` を使用してください。
+-   オプトインできる SDK ツールタイプは、`FunctionTool`、`CustomTool`、`ShellTool`、`ApplyPatchTool`、`HostedMCPTool`、`CodeInterpreterTool` です。関数、カスタム、シェル、パッチ適用の各ツールでは、`allowed_callers` を直接公開します。ホスト型 MCP と Code Interpreter では、`tool_config` 内に `allowed_callers` を設定してください。
+-   `@function_tool(allowed_callers=[...])` では、Pydantic モデル、TypedDict、dataclass などの構造化された戻り値アノテーションが、自動的に厳密なオブジェクト出力スキーマとなり、値がプログラムに返される前に検証されます。関数に使用可能なアノテーションがない場合は `output_type=...` を使用し、厳密なオブジェクトスキーマがすでにある場合は、より低レベルのエスケープハッチである `output_json_schema={...}` を使用してください。`output_type` と `output_json_schema` は相互排他的です。単純な `str`、`Any`、`None` の戻り値は型なしのままです。スキーマに基づくプログラム所有の呼び出しでは、自由形式のテキストが出力スキーマを満たさないため、デフォルトの失敗フォーマッターが無効になります。そのため、スキーマに準拠する JSON を返すカスタム `failure_error_function` を指定しない限り、ハンドラーの例外が伝播します。
+-   プログラム所有の SDK ツールでも、通常の Runner ライフサイクルが使用されます。ツールの入力および出力ガードレール、フック、タイムアウト、同時実行数制限、承認、セッション、`RunState` の一時停止／再開動作は引き続き適用され、SDK は各子呼び出しとプログラム呼び出し元との関係を保持します。
+-   `ProgrammaticToolCallingTool()` が存在する場合、プログラムが実行される前であっても、モデルリクエストの再試行にはより厳格なリプレイ安全性の境界が使用されます。SDK は、これらのリクエストに対するプロバイダー管理の再試行と WebSocket のイベント前再試行を無効にします。Runner の再試行ポリシーは、プロバイダーからの指示によってリプレイが安全であると明示的に示された場合にのみ再試行します。`retry_policies.network_error()` だけでは、この境界を上書きしません。
+-   承認が重要なツールや影響の大きいツールは、通常、直接呼び出しのままにすることを推奨します。これにより、大規模なプログラムの一部になる前に、各アクションを人が確認できます。プログラム所有の呼び出しが承認のために一時停止した場合は、通常どおり `RunState` を介して中断を解決し、元の実行を再開してください。
+-   プログラムによるツール呼び出しは、[ホスト型ツール検索](#hosted-tool-search)と組み合わせられます。生成されたプログラムが遅延ツールを呼び出す前に、モデルがそのツールを読み込む必要があります。
+-   `program` 項目と、プログラムが所有する通常の子ツール呼び出しは、[`ToolCallItem`][agents.items.ToolCallItem] エントリとして表示されます。対応する `program_output` は、[`ToolCallOutputItem`][agents.items.ToolCallOutputItem] として表示されます。一方、ホスト型 MCP の承認リクエストとツールカタログでは、専用の MCP 項目およびストリームイベントが使用されます。確認方法の詳細については、[実行結果](results.md#new-items)および[ストリーミング](streaming.md#run-item-event-names)を参照してください。
+-   完全な並行在庫計画のコード例については、`examples/tools/programmatic_tool_calling.py` を参照してください。
 -   公式プラットフォームガイド: [プログラムによるツール呼び出し](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)。

-### ホスト型コンテナシェル + スキル
+### ホスト型コンテナシェルとスキル

-`ShellTool` は、OpenAI がホストするコンテナでの実行もサポートしています。ローカルランタイムではなく、管理されたコンテナ内でモデルにシェルコマンドを実行させたい場合は、このモードを使用してください。
+`ShellTool` は、OpenAI がホストするコンテナでの実行もサポートします。ローカルランタイムではなく、管理されたコンテナ内でモデルにシェルコマンドを実行させる場合に、このモードを使用してください。

 ```python
 from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -214,52 +215,52 @@ result = await Runner.run(
 print(result.final_output)
 ```

-既存のコンテナを後続の実行で再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。
+後続の実行で既存のコンテナを再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。

-注意事項:
+留意事項:

 -   ホスト型シェルは、Responses API のシェルツールを通じて利用できます。
 -   `container_auto` はリクエスト用のコンテナをプロビジョニングし、`container_reference` は既存のコンテナを再利用します。
 -   `container_auto` には、`file_ids` と `memory_limit` も含められます。
-   `environment.skills` は、スキルへの参照とインラインスキルバンドルを受け付けます。
+-   `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` を参照してください。
+-   `network_policy` は、`disabled` モードと `allowlist` モードをサポートします。
+-   許可リストモードでは、`network_policy.domain_secrets` によって、名前を指定してドメインスコープのシークレットを挿入できます。
+-   完全なコード例については、`examples/tools/container_shell_skill_reference.py` と `examples/tools/container_shell_inline_skill.py` を参照してください。
 -   OpenAI プラットフォームガイド: [シェル](https://platform.openai.com/docs/guides/tools-shell)および[スキル](https://platform.openai.com/docs/guides/tools-skills)。

 ## ローカルランタイムツール

-ローカルランタイムツールは、モデルのレスポンス自体の外部で実行されます。呼び出すタイミングは引き続きモデルが決定しますが、実際の処理はご利用のアプリケーションまたは設定済みの実行環境が行います。
+ローカルランタイムツールは、モデルレスポンス自体の外部で実行されます。モデルは引き続き呼び出すタイミングを決定しますが、実際の処理はアプリケーションまたは設定済みの実行環境が行います。

-`ComputerTool` と `ApplyPatchTool` には、常にご自身で用意したローカル実装が必要です。`ShellTool` は両方のモードに対応しています。管理された実行を使用する場合は前述のホスト型コンテナ設定を使用し、ご自身のプロセスでコマンドを実行する場合は以下のローカルランタイム設定を使用してください。
+`ComputerTool` と `ApplyPatchTool` には、常にご自身で用意したローカル実装が必要です。`ShellTool` は両方のモードに対応します。管理された実行が必要な場合は上記のホスト型コンテナ設定を使用し、独自のプロセスでコマンドを実行する場合は以下のローカルランタイム設定を使用してください。

-ローカルランタイムツールでは、実装を用意する必要があります。
+ローカルランタイムツールには、実装を用意する必要があります。

-   [`ComputerTool`][agents.tool.ComputerTool]: GUI／ブラウザの自動化を有効にするには、[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] インターフェースを実装します。
+-   [`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]: 差分をローカルに適用するには、[`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] を実装します。
 -   ローカルシェルスキルは、`ShellTool(environment={"type": "local", "skills": [...]})` で利用できます。

-### ComputerTool と Responses のコンピュータツール
+### `ComputerTool` と Responses コンピュータツール

-`ComputerTool` は引き続きローカルハーネスです。ご自身で [`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] の実装を提供し、SDK がそのハーネスを OpenAI Responses API のコンピュータ操作インターフェースにマッピングします。
+`ComputerTool` は引き続きローカルハーネスです。[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] の実装を用意すると、SDK がそのハーネスを OpenAI Responses API のコンピュータサーフェスにマッピングします。

-明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストでは、SDK は GA 版の組み込みツールペイロード `{"type": "computer"}` を送信します。以前の `computer-use-preview` モデルでは、プレビューペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` が引き続き使用されます。これは、OpenAI の[コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/)で説明されているプラットフォーム移行に対応しています。
+明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストの場合、SDK は GA 組み込みツールのペイロード `{"type": "computer"}` を送信します。以前の `computer-use-preview` モデルでは、プレビューペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` が引き続き使用されます。これは、OpenAI の[コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/)に記載されているプラットフォーム移行を反映しています。

 -   モデル: `computer-use-preview` -> `gpt-5.5`
 -   ツールセレクター: `computer_use_preview` -> `computer`
-   コンピュータ呼び出しの形式: `computer_call` ごとに 1 つの `action` -> `computer_call` 上のバッチ化された `actions[]`
-   切り詰め: プレビューパスでは `ModelSettings(truncation="auto")` が必須 -> GA パスでは不要
+-   コンピュータ呼び出し形式: `computer_call` ごとに 1 つの `action` -> `computer_call` 上の一括 `actions[]`
+-   切り詰め: プレビューパスでは `ModelSettings(truncation="auto")` が必要 -> GA パスでは不要

-SDK は、実際の Responses リクエストにおける有効なモデルから、この通信形式を選択します。プロンプトテンプレートを使用していて、プロンプト側でモデルを指定するためリクエストから `model` が省略される場合、`model="gpt-5.5"` を明示したままにするか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。
+SDK は、実際の Responses リクエストで有効なモデルに基づいてワイヤー形式を選択します。プロンプトテンプレートを使用し、プロンプト側でモデルを保持しているためリクエストで `model` が省略される場合、`model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。

-[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け付けられ、有効なリクエストモデルに対応する組み込みセレクターへ正規化されます。`ComputerTool` がない場合、これらの文字列は通常の関数名と同様に動作します。
+[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け入れられ、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` がない場合、これらの文字列は引き続き通常の関数名として動作します。

-この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーによって提供される場合に重要です。GA の `computer` ペイロードでは、シリアライズ時に `environment` や画面サイズが不要なため、未解決のファクトリーでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるよう、解決済みの `Computer` または `AsyncComputer` インスタンスが引き続き必要です。
+この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーに基づく場合に重要です。GA の `computer` ペイロードでは、シリアライズ時に `environment` や寸法は不要なため、未解決のファクトリーでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるように、解決済みの `Computer` または `AsyncComputer` インスタンスが引き続き必要です。

-ランタイムでは、どちらのパスも同じローカルハーネスを使用します。プレビューのレスポンスでは、単一の `action` を持つ `computer_call` アイテムが生成されます。`gpt-5.5` ではバッチ化された `actions[]` が生成される場合があり、SDK は `computer_call_output` のスクリーンショットアイテムを生成する前に、それらを順番に実行します。実行可能な Playwright ベースのハーネスについては、`examples/tools/computer_use.py` を参照してください。
+ランタイムでは、両方のパスで同じローカルハーネスが引き続き使用されます。プレビューレスポンスは単一の `action` を含む `computer_call` 項目を生成します。`gpt-5.5` は一括の `actions[]` を生成でき、SDK は `computer_call_output` スクリーンショット項目を生成する前に、それらを順番に実行します。実行可能な Playwright ベースのハーネスについては、`examples/tools/computer_use.py` を参照してください。

 ```python
 from agents import Agent, ApplyPatchTool, ShellTool
@@ -308,11 +309,13 @@ agent = Agent(
 -   ツール名には Python 関数の名前が使用されます（名前を指定することもできます）
 -   ツールの説明は関数の docstring から取得されます（説明を指定することもできます）
 -   関数入力のスキーマは、関数の引数から自動的に作成されます
-   無効化されていない限り、各入力の説明は関数の docstring から取得されます
+-   無効にしない限り、各入力の説明は関数の docstring から取得されます
+
+`@tool` で作成されたツールは、読み取り専用の `__wrapped__` 属性を通じて元の Python 呼び出し可能オブジェクトを公開します。これは検査やテストに便利ですが、直接呼び出すと、スキーマ検証、コンテキスト挿入、ガードレール、タイムアウト、失敗処理、トレーシングを含むツールランタイムパイプラインが回避されます。手動で構築した `FunctionTool` インスタンスは、`__wrapped__` を公開しません。

 Python の `inspect` モジュールを使用して関数シグネチャを抽出し、さらに [`griffe`](https://mkdocstrings.github.io/griffe/) で docstring を解析し、`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
@@ -365,12 +368,12 @@ for tool in agent.tools:

 ```

-1.  関数の引数には任意の Python 型を使用でき、関数は同期または非同期のどちらでもかまいません。
-2.  docstring が存在する場合は、説明と引数の説明を取得するために使用されます。
-3.  関数は、必要に応じて `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、使用する docstring のスタイルなどを上書きすることもできます。
+1.  任意の Python 型を関数の引数として使用でき、関数は同期または非同期にできます。
+2.  docstring が存在する場合、説明と引数の説明の取得に使用されます。
+3.  関数はオプションで `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。
 4.  デコレートされた関数をツールのリストに渡せます。

-??? note "出力を表示するには展開してください"
+??? note "出力の表示"

    ```
    fetch_weather
@@ -442,20 +445,20 @@ for tool in agent.tools:

 ### 関数ツールからの画像またはファイルの返却

-テキスト出力に加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返すことができます。そのためには、次のいずれかを返します。
+テキスト出力に加えて、1 つまたは複数の画像やファイルを関数ツールの出力として返せます。そのためには、次のいずれかを返します。

 -   画像: [`ToolOutputImage`][agents.tool.ToolOutputImage]（または TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]）
 -   ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（または TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]）
-   テキスト: 文字列、文字列に変換可能なオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
+-   テキスト: 文字列、文字列化可能なオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）

 ### カスタム関数ツール

-Python 関数をツールとして使用したくない場合もあります。その場合は、必要に応じて [`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。以下を指定する必要があります。
+Python 関数をツールとして使用したくない場合もあります。必要に応じて、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次の項目を指定する必要があります。

 -   `name`
 -   `description`
-   `params_json_schema`。引数の JSON スキーマです
-   `on_invoke_tool`。[`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列形式の引数を受け取り、ツール出力（テキスト、構造化されたツール出力オブジェクト、出力のリストなど）を返す非同期関数です。
+-   引数の JSON スキーマである `params_json_schema`
+-   [`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列形式の引数を受け取り、ツール出力（たとえば、テキスト、構造化ツール出力オブジェクト、出力のリスト）を返す非同期関数である `on_invoke_tool`

 ```python
 from typing import Any
@@ -490,16 +493,16 @@ tool = FunctionTool(

 ### 引数と docstring の自動解析

-前述のとおり、関数シグネチャを自動的に解析してツールのスキーマを抽出し、docstring を解析してツールと個々の引数の説明を抽出します。これに関する注意事項は次のとおりです。
+前述のとおり、関数シグネチャを自動的に解析してツールのスキーマを抽出し、docstring を解析してツールと各引数の説明を抽出します。留意事項は次のとおりです。

-1. シグネチャの解析は `inspect` モジュールを使用して行われます。型アノテーションを使用して引数の型を把握し、スキーマ全体を表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
-2. docstring の解析には `griffe` を使用します。サポートされている docstring 形式は `google`、`sphinx`、`numpy` です。docstring の形式は自動検出を試みますが、ベストエフォートであるため、`function_tool` を呼び出す際に明示的に設定することもできます。また、`use_docstring_info` を `False` に設定して、docstring の解析を無効にすることもできます。Google スタイルの docstring では、要約テキストの直後に空行を挟まずに配置された `Args:`、`Arguments:`、`Params:`、`Parameters:` セクションもパーサーで受け付けられます。
+1. シグネチャの解析は、`inspect` モジュールを使用して行われます。型アノテーションを使用して引数の型を把握し、スキーマ全体を表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
+2. docstring の解析には `griffe` を使用します。サポートされる docstring 形式は、`google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますが、これはベストエフォートであり、`function_tool` を呼び出す際に明示的に設定できます。`use_docstring_info` を `False` に設定して、docstring の解析を無効にすることもできます。Google スタイルの docstring では、要約テキストの直後に空行を挟まずに配置された `Args:`、`Arguments:`、`Params:`、`Parameters:` セクションもパーサーが受け入れます。

-スキーマ抽出のコードは [`agents.function_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 スキーマと検証には、これらの制約が含まれます。
+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
@@ -519,7 +522,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr

 ### 関数ツールのタイムアウト

-`@function_tool(timeout=...)` を使用すると、非同期関数ツールの呼び出しごとにタイムアウトを設定できます。
+`@function_tool(timeout=...)` を使用して、非同期関数ツールに呼び出し単位のタイムアウトを設定できます。

 ```python
 import asyncio
@@ -540,13 +543,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
@@ -570,15 +573,15 @@ except ToolTimeoutError as e:

 !!! note

-    タイムアウト設定は、非同期の `@function_tool` ハンドラーでのみサポートされています。
+    タイムアウト設定は、非同期の `@function_tool` ハンドラーでのみサポートされます。

-### 関数ツールでのエラー処理
+### 関数ツールのエラー処理

-`@function_tool` を使用して関数ツールを作成する際に、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを提供する関数です。
+`@function_tool` を使用して関数ツールを作成する場合、`failure_error_function` を渡せます。これは、ツール呼び出しがクラッシュした場合に LLM へエラーレスポンスを提供する関数です。

-   デフォルトでは（何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。
-   独自のエラー関数を渡した場合は、その関数が代わりに実行され、レスポンスが LLM に送信されます。
-   明示的に `None` を渡した場合、ツール呼び出しのエラーは再度発生し、ご自身で処理できます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などが発生する可能性があります。
+-   デフォルトでは（何も渡さない場合）、`default_tool_error_function` が実行され、エラーが発生したことを LLM に通知します。
+-   独自のエラー関数を渡した場合は、代わりにその関数が実行され、レスポンスが LLM に送信されます。
+-   `None` を明示的に渡した場合、ツール呼び出しのエラーは再送出され、ご自身で処理できます。モデルが無効な JSON を生成した場合は `ModelBehaviorError`、コードがクラッシュした場合は `UserError` などになる可能性があります。

 ```python
 from agents import RunContextWrapper
@@ -606,7 +609,7 @@ def get_user_profile(user_id: str) -> str:

 ## Agents as tools

-一部のワークフローでは、制御をハンドオフする代わりに、中央のエージェントで専門的なエージェントのネットワークをオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。
+一部のワークフローでは、制御をハンドオフする代わりに、中央のエージェントで専門エージェントのネットワークをオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。

 ```python
 import asyncio
@@ -652,9 +655,9 @@ if __name__ == "__main__":

 ### ツールエージェントのカスタマイズ

-`agent.as_tool` 関数は、エージェントを簡単にツールへ変換するための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` など、一般的なランタイムオプションをサポートしています。また、`parameters`、`input_builder`、`include_input_schema` を使用した構造化入力もサポートしています。
+`agent.as_tool` 関数は、エージェントを簡単にツールへ変換するための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` を使用した構造化入力もサポートします。

-状態オプションは、ツール呼び出しによって開始されるネストされたエージェント実行を設定します。親実行の会話状態は自動的には継承されません。クライアント管理の履歴を親実行とネストされた実行の間で共有するには、両方に同じ `session` を明示的に渡してください。`Runner.run` と同様に、ネストされた実行では、クライアント管理の `session`、または `previous_response_id` か `conversation_id` を使用したサーバー管理の継続のいずれか 1 つの状態管理方式を選択してください。
+状態オプションは、ツール呼び出しによって開始されるネストされたエージェント実行を設定します。親実行の会話状態は自動的には継承されません。クライアント管理の履歴を親実行とネストされた実行の間で共有するには、同じ `session` を両方に明示的に渡してください。`Runner.run` と同様に、ネストされた実行には 1 つの状態戦略を選択します。クライアント管理の `session`、または `previous_response_id` もしくは `conversation_id` を使用したサーバー管理の継続です。

 ```python
 from agents.decorators import tool
@@ -678,7 +681,7 @@ async def run_my_agent() -> str:

 ### ツールエージェントの構造化入力

-デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたはデータクラス型）を渡すことで、構造化スキーマを公開できます。
+デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたは dataclass 型）を渡すことで構造化スキーマを公開できます。

 追加オプション:

@@ -708,17 +711,17 @@ translator_tool = translator_agent.as_tool(

 ### ツールエージェントの承認ゲート

-`Agent.as_tool(..., needs_approval=...)` は、`function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中のアイテムが `result.interruptions` に表示されます。その後、`result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出してから再開します。一時停止／再開の完全なパターンについては、[Human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。
+`Agent.as_tool(..., needs_approval=...)` は、`function_tool` と同じ承認フローを使用します。承認が必要な場合、実行が一時停止し、保留中の項目が `result.interruptions` に表示されます。その後、`result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出してから再開します。完全な一時停止／再開パターンについては、[Human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。

 ### カスタム出力の抽出

-場合によっては、中央のエージェントへ返す前にツールエージェントの出力を変更したいことがあります。これは、次のような場合に役立ちます。
+場合によっては、中央のエージェントに返す前に、ツールエージェントの出力を変更したいことがあります。これは、次のような場合に役立ちます。

 -   サブエージェントのチャット履歴から特定の情報（JSON ペイロードなど）を抽出する。
-   エージェントの最終回答を変換または再フォーマットする（Markdown をプレーンテキストや CSV に変換するなど）。
-   出力を検証するか、エージェントのレスポンスが欠落している、または形式が不正な場合にフォールバック値を提供する。
+-   エージェントの最終回答を変換または再フォーマットする（Markdown をプレーンテキストまたは CSV に変換するなど）。
+-   出力を検証するか、エージェントのレスポンスが欠落している場合や形式が不正な場合にフォールバック値を提供する。

-これは、`as_tool` メソッドに `custom_output_extractor` 引数を指定することで実現できます。
+これを行うには、`as_tool` メソッドに `custom_output_extractor` 引数を指定します。

 ```python
 async def extract_json_payload(run_result: RunResult) -> str:
@@ -737,11 +740,11 @@ json_tool = data_agent.as_tool(
 )
 ```

-カスタム抽出関数内では、ネストされた [`RunResult`][agents.result.RunResult] から [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] にもアクセスできます。これは、ネストされた実行結果の後処理時に、外側のツール名、呼び出し ID、または raw 引数が必要な場合に役立ちます。[実行結果ガイド](results.md#agent-as-tool-metadata)を参照してください。
+カスタム抽出関数内では、ネストされた [`RunResult`][agents.result.RunResult] によって [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] も公開されます。これは、ネストされた実行結果を後処理する際に、外側のツール名、呼び出し ID、raw 引数が必要な場合に便利です。[実行結果ガイド](results.md#agent-as-tool-metadata)を参照してください。

 ### ネストされたエージェント実行のストリーミング

-`as_tool` に `on_stream` コールバックを渡すと、ネストされたエージェントが生成するストリーミングイベントを受信しながら、ストリームの完了後に最終出力を返せます。
+`as_tool` に `on_stream` コールバックを渡すと、ネストされたエージェントが生成するストリーミングイベントを受信しながら、ストリーム完了後に最終出力を返せます。

 ```python
 from agents import AgentToolStreamEvent
@@ -761,15 +764,15 @@ billing_agent_tool = billing_agent.as_tool(

 想定される動作:

- イベントタイプは `StreamEvent["type"]` と同様に、`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event` です。
- `on_stream` を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームが最後まで処理されます。
+- イベントタイプは `StreamEvent["type"]` を反映します。`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event` です。
+- `on_stream` を指定すると、ネストされたエージェントが自動的にストリーミングモードで実行され、最終出力を返す前にストリームが最後まで処理されます。
 - ハンドラーは同期または非同期にできます。各イベントは到着順に配信されます。
- モデルのツール呼び出しを通じてツールが呼び出された場合は、`tool_call` が存在します。直接呼び出した場合は `None` のままになることがあります。
+- モデルのツール呼び出しによってツールが呼び出された場合、`tool_call` が存在します。直接呼び出しでは `None` の場合があります。
 - 実行可能な完全なサンプルについては、`examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。

-### 条件付きのツール有効化
+### 条件付きツール有効化

-`is_enabled` パラメーターを使用すると、ランタイムでエージェントツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザー設定、ランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。
+`is_enabled` パラメーターを使用すると、ランタイムでエージェントツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザー設定、ランタイム条件に基づいて、LLM が利用できるツールを動的に絞り込めます。

 ```python
 import asyncio
@@ -824,24 +827,24 @@ async def main():
 asyncio.run(main())
 ```

-`is_enabled` パラメーターは、次の値を受け付けます。
+`is_enabled` パラメーターは、次を受け入れます。

 -   **ブール値**: `True`（常に有効）または `False`（常に無効）
 -   **呼び出し可能な関数**: `(context, agent)` を受け取り、ブール値を返す関数
-   **非同期関数**: 複雑な条件ロジック用の非同期関数
+-   **非同期関数**: 複雑な条件ロジックに使用する非同期関数

-無効化されたツールはランタイムで LLM から完全に非表示になるため、次の用途に役立ちます。
+無効化されたツールはランタイムで LLM から完全に非表示になるため、次の用途に便利です。

-   ユーザー権限に基づく機能ゲーティング
-   環境固有のツール利用可否（開発環境と本番環境）
+-   ユーザー権限に基づく機能制限
+-   環境固有のツール可用性（開発環境と本番環境）
 -   異なるツール設定の A/B テスト
 -   ランタイム状態に基づく動的なツールフィルタリング

-## 実験的機能: Codex ツール
+## 試験的機能: Codex ツール

-`codex_tool` は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペーススコープのタスク（シェル、ファイル編集、MCP ツール）を実行できるようにします。この機能は実験的であり、変更される可能性があります。
+`codex_tool` は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペーススコープのタスク（シェル、ファイル編集、MCP ツール）を実行できるようにします。このサーフェスは試験的機能であり、変更される可能性があります。

-現在の実行を離れずに、メインエージェントから Codex へ範囲が限定されたワークスペースタスクを委任したい場合に使用してください。デフォルトのツール名は `codex` です。カスタム名を設定する場合は、`codex` または `codex_` で始まる名前にする必要があります。エージェントに複数の Codex ツールを含める場合、それぞれに一意の名前を使用する必要があります。
+メインエージェントが現在の実行を離れることなく、範囲の限定されたワークスペースタスクを Codex に委任する場合に使用します。デフォルトのツール名は `codex` です。カスタム名を設定する場合は、`codex` または `codex_` で始まる名前にする必要があります。エージェントに複数の Codex ツールを含める場合、それぞれに一意の名前を使用する必要があります。

 ```python
 from agents import Agent
@@ -870,33 +873,33 @@ agent = Agent(
 )
 ```

-まず、次のオプショングループを確認してください。
+最初に、次のオプショングループを確認してください。

-   実行対象: `sandbox_mode` と `working_directory` は、Codex が操作できる場所を定義します。これらは組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定してください。
-   スレッドのデフォルト設定: `default_thread_options=ThreadOptions(...)` は、モデル、推論強度、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを設定します。従来の `web_search_enabled` よりも `web_search_mode` を優先してください。
-   ターンのデフォルト設定: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` や任意のキャンセル用 `signal` など、ターンごとの動作を設定します。
-   ツールの入出力: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` アイテムを少なくとも 1 つ含める必要があります。`output_schema` を使用すると、構造化された Codex レスポンスを必須にできます。
+-   実行サーフェス: `sandbox_mode` と `working_directory` は、Codex が操作できる場所を定義します。これらは組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定してください。
+-   スレッドのデフォルト: `default_thread_options=ThreadOptions(...)` は、モデル、推論の労力、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを設定します。従来の `web_search_enabled` よりも `web_search_mode` の使用を推奨します。
+-   ターンのデフォルト: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` やオプションのキャンセル用 `signal` など、ターン単位の動作を設定します。
+-   ツール I/O: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` 項目を少なくとも 1 つ含める必要があります。`output_schema` を使用すると、Codex に構造化されたレスポンスを要求できます。

-スレッドの再利用と永続化は、個別に制御されます。
+スレッドの再利用と永続化は、個別の制御項目です。

 -   `persist_session=True` は、同じツールインスタンスへの繰り返し呼び出しで 1 つの Codex スレッドを再利用します。
-   `use_run_context_thread_id=True` は、同じ変更可能なコンテキストオブジェクトを共有する複数の実行にわたって、実行コンテキストにスレッド ID を保存して再利用します。
-   スレッド ID の優先順位は、呼び出しごとの `thread_id`、実行コンテキストのスレッド ID（有効な場合）、設定済みの `thread_id` オプションの順です。
+-   `use_run_context_thread_id=True` は、同じ可変コンテキストオブジェクトを共有する複数の実行にわたって、実行コンテキスト内にスレッド ID を保存して再利用します。
+-   スレッド ID の優先順位は、呼び出し単位の `thread_id`、実行コンテキストのスレッド ID（有効な場合）、設定済みの `thread_id` オプションの順です。
 -   デフォルトの実行コンテキストキーは、`name="codex"` の場合は `codex_thread_id`、`name="codex_<suffix>"` の場合は `codex_thread_id_<suffix>` です。`run_context_thread_id_key` で上書きできます。

 ランタイム設定:

 -   認証: `CODEX_API_KEY`（推奨）または `OPENAI_API_KEY` を設定するか、`codex_options={"api_key": "..."}` を渡します。
 -   ランタイム: `codex_options.base_url` は CLI のベース URL を上書きします。
-   バイナリの解決: CLI のパスを固定するには、`codex_options.codex_path_override`（または `CODEX_PATH`）を設定します。それ以外の場合、SDK は `PATH` から `codex` を解決し、見つからなければ同梱のベンダーバイナリへフォールバックします。
+-   バイナリーの解決: 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` が含まれ、使用量は `RunContextWrapper.usage` に追加されます。
+-   ストリーミング: `on_stream` は、スレッド／ターンのライフサイクルイベントと項目イベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、`error` の項目更新）を受け取ります。
+-   出力: 実行結果には `response`、`usage`、`thread_id` が含まれます。使用量は `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` を参照してください。
+-   実行可能な完全なサンプルについては、`examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。
@@ -4,21 +4,21 @@ search:
 ---
 # 샌드박스 클라이언트

-이 페이지를 사용하여 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 그대로 두고, [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 클라이언트별 옵션만 변경합니다.
+이 페이지를 사용하여 샌드박스 작업을 실행할 위치를 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 그대로 유지하고 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 에서 샌드박스 클라이언트와 클라이언트별 옵션만 변경합니다.

 !!! warning "베타 기능"

-    샌드박스 에이전트는 베타입니다. API의 세부 사항, 기본값, 지원 기능은 정식 출시 전 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다.
+    샌드박스 에이전트는 베타 버전입니다. 정식 출시 전까지 API 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 향후 더 고급 기능이 추가될 예정입니다.

-## 결정 가이드
+## 선택 가이드

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 목표 | 시작 대상 | 이유 |
+| 목표 | 시작 옵션 | 이유 |
 | --- | --- | --- |
-| macOS 또는 Linux에서 가장 빠른 로컬 반복 개발 | `UnixLocalSandboxClient` | 추가 설치가 필요 없고, 로컬 파일 시스템 개발이 간단합니다. |
-| 기본 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지로 Docker 내부에서 작업을 실행합니다. |
-| 호스티드 실행 또는 프로덕션 스타일 격리 | 호스티드 샌드박스 클라이언트 | 워크스페이스 경계를 제공자가 관리하는 환경으로 이동합니다. |
+| macOS 또는 Linux에서 가장 빠른 로컬 반복 개발 | `UnixLocalSandboxClient` | 추가 설치가 필요 없으며 로컬 파일 시스템에서 간단하게 개발할 수 있습니다. |
+| 기본적인 컨테이너 격리 | `DockerSandboxClient` | 특정 이미지가 적용된 Docker 내부에서 작업을 실행합니다. |
+| 호스티드 실행 또는 프로덕션 수준의 격리 | 호스티드 샌드박스 클라이언트 | 워크스페이스 경계를 제공업체가 관리하는 환경으로 이동합니다. |

 </div>

@@ -28,16 +28,18 @@ search:

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 클라이언트 | 설치 | 선택 시점 | 예시 |
+| 클라이언트 | 설치 | 선택하는 경우 | 예제 |
 | --- | --- | --- | --- |
-| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 개발이 필요할 때. 로컬 개발의 좋은 기본값입니다. | [Unix-local 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
-| `DockerSandboxClient` | `openai-agents[docker]` | 컨테이너 격리 또는 로컬 환경과의 동등성을 위한 특정 이미지가 필요할 때. | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
+| `UnixLocalSandboxClient` | 없음 | macOS 또는 Linux에서 가장 빠르게 로컬 반복 개발을 수행하려는 경우입니다. 로컬 개발을 위한 좋은 기본 옵션입니다. | [Unix 로컬 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
+| `DockerSandboxClient` | `openai-agents[docker]` | 컨테이너 격리가 필요하거나 로컬 환경의 동등성을 위해 특정 이미지를 사용하려는 경우입니다. | [Docker 시작 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |

 </div>

-Unix-local은 로컬 파일 시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강력한 환경 격리 또는 프로덕션 스타일의 동등성이 필요할 때 Docker나 호스티드 제공자로 이동하세요.
+Unix 로컬은 로컬 파일 시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강력한 환경 격리나 프로덕션 수준의 동등성이 필요할 때 Docker 또는 호스티드 제공업체로 전환하세요.

-Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하세요.
+`SandboxPathGrant.host_path` 는 Docker에서만 사용할 수 있으며 호스트 경로를 컨테이너 내부의 다른 POSIX 경로에 매핑합니다. Unix 로컬에서는 동일 경로 허용만 지원합니다. 자세한 내용은 [매니페스트 경로 허용](guide.md#manifest)을 참조하세요.
+
+Unix 로컬에서 Docker로 전환하려면 에이전트 정의는 그대로 유지하고 실행 구성만 변경합니다.

 ```python
 from docker import from_env as docker_from_env
@@ -54,45 +56,45 @@ run_config = RunConfig(
 )
 ```

-컨테이너 격리 또는 이미지 동등성이 필요할 때 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
+컨테이너 격리 또는 이미지 동등성이 필요한 경우 이 방식을 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참조하세요.

-## 마운트와 원격 스토리지
+## 마운트 및 원격 스토리지

-마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 기본 제공 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스티드 제공자 전략은 `agents.extensions.sandbox` 또는 제공자별 확장 패키지에서 사용할 수 있습니다.
+마운트 항목은 노출할 스토리지를 정의하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 정의합니다. 기본 제공 마운트 항목과 범용 전략은 `agents.sandbox.entries` 에서 가져옵니다. 호스티드 제공업체 전략은 `agents.extensions.sandbox` 또는 제공업체별 확장 패키지에서 사용할 수 있습니다.

-일반적인 마운트 옵션:
+일반적인 마운트 옵션은 다음과 같습니다.

- `mount_path`: 샌드박스에서 스토리지가 나타나는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다.
- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 할 때만 `False`로 설정하세요.
- `mount_strategy`: 필수입니다. 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요.
+- `mount_path`: 샌드박스에서 스토리지가 표시되는 위치입니다. 상대 경로는 매니페스트 루트를 기준으로 해석되며, 절대 경로는 그대로 사용됩니다.
+- `read_only`: 기본값은 `True` 입니다. 샌드박스가 마운트된 스토리지에 다시 기록해야 하는 경우에만 `False` 로 설정하세요.
+- `mount_strategy`: 필수 항목입니다. 마운트 항목과 샌드박스 백엔드 모두에 적합한 전략을 사용하세요.

-마운트는 임시 워크스페이스 항목으로 취급됩니다. 스냅샷 및 지속성 플로우는 마운트된 원격 스토리지를 저장된 워크스페이스로 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
+마운트는 임시 워크스페이스 항목으로 처리됩니다. 스냅샷 및 영속성 처리 과정에서는 마운트된 원격 스토리지를 저장된 워크스페이스에 복사하지 않고 마운트된 경로를 분리하거나 건너뜁니다.

-일반 로컬/컨테이너 전략:
+범용 로컬/컨테이너 전략은 다음과 같습니다.

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 전략 또는 패턴 | 사용 시점 | 참고 사항 |
+| 전략 또는 패턴 | 사용하는 경우 | 참고 사항 |
 | --- | --- | --- |
-| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone`을 실행할 수 있을 때. | S3, GCS, R2, Azure Blob, Box를 지원합니다. `RcloneMountPattern`은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다. |
-| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3`가 있고 Mountpoint 스타일의 S3 또는 S3 호환 액세스를 원할 때. | `S3Mount` 및 `GCSMount`를 지원합니다. |
-| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2`와 FUSE 지원이 있을 때. | `AzureBlobMount`를 지원합니다. |
-| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files`가 있고 기존 S3 Files 마운트 대상에 접근할 수 있을 때. | `S3FilesMount`를 지원합니다. |
-| `DockerVolumeMountStrategy(driver=...)` | Docker가 컨테이너 시작 전에 볼륨 드라이버 기반 마운트를 연결해야 할 때. | Docker 전용입니다. S3, GCS, R2, Azure Blob, Box는 `rclone`을 지원하며, S3와 GCS는 `mountpoint`도 지원합니다. |
+| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 샌드박스 이미지에서 `rclone` 을 실행할 수 있는 경우입니다. | S3, GCS, R2, Azure Blob, Box를 지원합니다. `RcloneMountPattern` 은 `fuse` 모드 또는 `nfs` 모드로 실행할 수 있습니다. |
+| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 이미지에 `mount-s3` 가 있고 Mountpoint 방식으로 S3 또는 S3 호환 스토리지에 액세스하려는 경우입니다. | `S3Mount` 및 `GCSMount` 를 지원합니다. |
+| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 이미지에 `blobfuse2` 및 FUSE 지원이 있는 경우입니다. | `AzureBlobMount` 를 지원합니다. |
+| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 이미지에 `mount.s3files` 가 있고 기존 S3 Files 마운트 대상에 접근할 수 있는 경우입니다. | `S3FilesMount` 를 지원합니다. |
+| `DockerVolumeMountStrategy(driver=...)` | 컨테이너가 시작되기 전에 Docker가 볼륨 드라이버 기반 마운트를 연결해야 하는 경우입니다. | Docker 전용입니다. S3, GCS, R2, Azure Blob, Box는 `rclone` 을 지원하며, S3와 GCS는 `mountpoint` 도 지원합니다. |

 </div>

 ## 지원되는 호스티드 플랫폼

-호스티드 환경이 필요한 경우 동일한 `SandboxAgent` 정의를 대개 그대로 사용할 수 있으며 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트만 변경하면 됩니다.
+호스티드 환경이 필요한 경우에도 일반적으로 동일한 `SandboxAgent` 정의를 그대로 사용할 수 있으며 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 에서 샌드박스 클라이언트만 변경하면 됩니다.

-이 저장소 체크아웃 대신 배포된 SDK를 사용하는 경우, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 종속성을 설치하세요.
+이 저장소의 체크아웃 대신 배포된 SDK를 사용하는 경우, 해당 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요.

-제공자별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참고하세요.
+저장소에 포함된 확장 코드 예제에 대한 제공업체별 설정 참고 사항과 링크는 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)를 참조하세요.

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 클라이언트 | 설치 | 예시 |
+| 클라이언트 | 설치 | 예제 |
 | --- | --- | --- |
 | `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
 | `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 실행 예제](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
@@ -104,24 +106,24 @@ run_config = RunConfig(

 </div>

-호스티드 샌드박스 클라이언트는 제공자별 마운트 전략을 노출합니다. 사용 중인 스토리지 제공자에 가장 적합한 백엔드와 마운트 전략을 선택하세요.
+호스티드 샌드박스 클라이언트는 제공업체별 마운트 전략을 제공합니다. 스토리지 제공업체에 가장 적합한 백엔드와 마운트 전략을 선택하세요.

 <div class="sandbox-nowrap-first-column-table" markdown="1">

 | 백엔드 | 마운트 참고 사항 |
 | --- | --- |
-| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy` 같은 로컬 전략으로 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount`를 지원합니다. |
-| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `ModalCloudBucketMountStrategy`로 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다. |
-| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `CloudflareBucketMountStrategy`로 Cloudflare 버킷 마운트를 지원합니다. |
-| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`로 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 통해 영구 Blaxel Drives도 지원합니다. |
-| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `VercelSandboxClient` | `VercelCloudBucketMountStrategy`와 `S3Mount`를 사용한 생성 시점 전용 S3 및 S3 호환 버킷 마운트를 지원합니다. 마운트가 포함된 세션은 재개할 수 없으며, 인라인 자격 증명을 사용하려면 `allow_s3_credential_exposure=True`가 필요합니다. |
+| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy` 같은 로컬 전략을 사용하여 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 를 지원합니다. |
+| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 방식의 `GCSMount` 에서 `ModalCloudBucketMountStrategy` 를 사용하는 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다. |
+| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 방식의 `GCSMount` 에서 `CloudflareBucketMountStrategy` 를 사용하는 Cloudflare 버킷 마운트를 지원합니다. |
+| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount` 에서 `BlaxelCloudBucketMountStrategy` 를 사용하는 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel` 의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy` 를 사용하여 영속적 Blaxel Drive를 지원합니다. |
+| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` 를 사용하는 rclone 기반 클라우드 스토리지 마운트를 지원하며, `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount` 와 함께 사용할 수 있습니다. |
+| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` 를 사용하는 rclone 기반 클라우드 스토리지 마운트를 지원하며, `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount` 와 함께 사용할 수 있습니다. |
+| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` 를 사용하는 rclone 기반 클라우드 스토리지 마운트를 지원하며, `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount` 와 함께 사용할 수 있습니다. |
+| `VercelSandboxClient` | `S3Mount` 에서 `VercelCloudBucketMountStrategy` 를 사용하는, 생성 시점에만 적용 가능한 S3 및 S3 호환 버킷 마운트를 지원합니다. 마운트된 세션은 재개할 수 없으며, 인라인 자격 증명을 사용하려면 `allow_s3_credential_exposure=True` 가 필요합니다. |

 </div>

-아래 표는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목을 요약합니다.
+다음 표에는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목이 요약되어 있습니다.

 <div class="sandbox-nowrap-first-column-table" markdown="1">

@@ -138,4 +140,4 @@ run_config = RunConfig(

 </div>

-실행 가능한 더 많은 예제는 로컬, 코딩, 메모리, 핸드오프 및 에이전트 구성 패턴에 대해 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)를, 호스티드 샌드박스 클라이언트에 대해 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)를 둘러보세요.
+실행 가능한 더 많은 코드 예제를 보려면 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴은 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)에서, 호스티드 샌드박스 클라이언트는 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)에서 확인하세요.
@@ -4,11 +4,11 @@ search:
 ---
 # 세션

-Agents SDK는 여러 에이전트 실행 간 대화 기록을 자동으로 유지하는 기본 제공 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요를 없애줍니다.
+Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하므로, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요가 없습니다.

-세션은 특정 세션의 대화 기록을 저장하므로, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있습니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
+세션은 특정 세션의 대화 기록을 저장하여, 명시적으로 메모리를 직접 관리하지 않아도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.

-SDK가 클라이언트 측 메모리를 관리해 주기를 원할 때 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id` 와 함께 사용할 수 없습니다. OpenAI 서버 관리형 이어가기를 원한다면 세션을 그 위에 겹쳐 사용하지 말고 해당 메커니즘 중 하나를 선택하세요.
+SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 동일한 실행에서 세션을 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용할 수 없습니다. OpenAI 서버에서 관리하는 대화 연속성을 사용하려면 세션을 추가로 적용하지 말고 이러한 메커니즘 중 하나를 선택하세요.

 ## 빠른 시작

@@ -49,9 +49,9 @@ result = Runner.run_sync(
 print(result.final_output)  # "Approximately 39 million"
 ```

-## 동일한 세션으로 인터럽트된 실행 재개
+## 동일한 세션을 사용한 인터럽션된 실행 재개

-승인을 위해 실행이 일시 중지되는 경우, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 같은 기반 저장소를 가리키는 다른 세션 인스턴스)로 재개하세요.
+승인을 위해 실행이 일시 중지되면 동일한 세션 인스턴스 또는 동일한 기반 스토리지를 가리키는 다른 세션 인스턴스로 재개하여, 재개된 턴이 저장된 동일한 대화 기록을 이어가도록 하세요.

 ```python
 result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -65,29 +65,29 @@ if result.interruptions:

 ## 핵심 세션 동작

-세션 메모리가 활성화되면 다음과 같이 동작합니다.
+세션 메모리가 활성화된 경우:

-1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하여 입력 항목 앞에 추가합니다.
+1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 항목 앞에 추가합니다.
 2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다.
-3. **컨텍스트 보존**: 동일한 세션으로 이어지는 각 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다.
+3. **컨텍스트 보존**: 동일한 세션을 사용하는 이후의 각 실행에는 전체 대화 기록이 포함되므로 에이전트가 컨텍스트를 유지할 수 있습니다.

-이를 통해 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다.
+따라서 `.to_input_list()`를 수동으로 호출하고 실행 사이의 대화 상태를 관리할 필요가 없습니다.

-## 기록과 새 입력 병합 제어
+## 기록과 새 입력의 병합 방식 제어

-세션을 전달하면 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다.
+세션을 전달하면 일반적으로 러너는 다음 순서로 모델 입력을 준비합니다.

-1. 세션 기록(`session.get_items(...)` 에서 조회)
+1. 세션 기록(`session.get_items(...)`에서 가져옴)
 2. 새 턴 입력

-모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 을 사용하세요. 콜백은 두 개의 목록을 받습니다.
+모델 호출 전에 이 병합 단계를 맞춤 설정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 콜백은 다음 두 목록을 받습니다.

-   `history`: 조회된 세션 기록(이미 입력 항목 형식으로 정규화됨)
+-   `history`: 가져온 세션 기록(이미 입력 항목 형식으로 정규화됨)
 -   `new_input`: 현재 턴의 새 입력 항목

-모델에 전송할 최종 입력 항목 목록을 반환하세요.
+모델로 전송할 최종 입력 항목 목록을 반환하세요.

-콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 지속 저장합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 이전 세션 항목이 새 입력으로 다시 저장되지는 않습니다.
+콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속하는 항목만 저장합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 기존 세션 항목이 새로운 입력으로 다시 저장되지 않습니다.

 ```python
 from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -109,16 +109,16 @@ result = await Runner.run(
 )
 ```

-세션이 항목을 저장하는 방식은 바꾸지 않으면서 기록에 대한 사용자 지정 가지치기, 재정렬 또는 선택적 포함이 필요할 때 사용하세요. 모델 호출 직전에 더 늦은 최종 처리 단계가 필요하다면 [에이전트 실행 가이드](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] 를 사용하세요.
+세션의 항목 저장 방식을 변경하지 않으면서 기록을 맞춤형으로 정리하거나 재정렬하거나 선택적으로 포함해야 할 때 이 기능을 사용하세요. 모델 호출 직전에 최종 처리 단계가 더 필요하면 [에이전트 실행 가이드](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]를 사용하세요.

-## 조회 기록 제한
+## 가져올 기록 제한

-각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요.
+각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings]를 사용하세요.

-   `SessionSettings(limit=None)` (기본값): 사용 가능한 모든 세션 항목 조회
-   `SessionSettings(limit=N)`: 가장 최근 `N` 개 항목만 조회
+-   `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목을 가져옵니다
+-   `SessionSettings(limit=N)`: 가장 최근의 `N`개 항목만 가져옵니다

-[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 를 통해 실행별로 이를 적용할 수 있습니다.
+[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 적용할 수 있습니다.

 ```python
 from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
@@ -134,13 +134,13 @@ result = await Runner.run(
 )
 ```

-세션 구현이 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings` 는 해당 실행에 대해 `None` 이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작은 변경하지 않으면서 조회 크기를 제한하고 싶을 때 유용합니다.
+세션 구현에서 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 재정의합니다. 이는 세션의 기본 동작을 변경하지 않고 가져올 기록의 크기를 제한하려는 긴 대화에 유용합니다.

 ## 메모리 작업

 ### 기본 작업

-세션은 대화 기록 관리를 위한 여러 작업을 지원합니다.
+세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다.

 ```python
 from agents import SQLiteSession
@@ -167,7 +167,7 @@ await session.clear_session()

 ### 수정을 위한 pop_item 사용

-`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하고 싶을 때 특히 유용합니다.
+대화의 마지막 항목을 실행 취소하거나 수정하려는 경우 `pop_item` 메서드가 특히 유용합니다.

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -196,34 +196,34 @@ result = await Runner.run(
 print(f"Agent: {result.final_output}")
 ```

-## 기본 제공 세션 구현
+## 내장 세션 구현

 SDK는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다.

-### 기본 제공 세션 구현 선택
+### 내장 세션 구현 선택

-아래의 상세 예제를 읽기 전에 시작점을 고르는 데 이 표를 사용하세요.
+아래의 상세한 예제를 읽기 전에 이 표를 참고하여 시작점을 선택하세요.

 | 세션 유형 | 적합한 용도 | 참고 |
 | --- | --- | --- |
-| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 기본 제공, 경량, 파일 기반 또는 인메모리 |
-| `AsyncSQLiteSession` | `aiosqlite` 기반 비동기 SQLite | 비동기 드라이버를 지원하는 확장 백엔드 |
-| `RedisSession` | 여러 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 |
-| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy가 지원하는 데이터베이스와 함께 동작 |
-| `MongoDBSession` | 이미 MongoDB를 사용하거나 다중 프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 |
-| `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 저장소와 TTL 및 일관성 제어 지원 |
-| `OpenAIConversationsSession` | OpenAI의 서버 관리형 스토리지 | OpenAI Conversations API 기반 기록 |
-| `OpenAIResponsesCompactionSession` | 자동 압축이 필요한 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 |
-| `AdvancedSQLiteSession` | SQLite와 분기/분석 | 더 많은 기능 세트; 전용 페이지 참조 |
-| `EncryptedSession` | 다른 세션 위에 암호화 + TTL 적용 | 래퍼; 먼저 하위 백엔드 선택 |
+| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 내장형 경량 구현, 파일 기반 또는 인메모리 |
+| `AsyncSQLiteSession` | `aiosqlite`를 사용하는 비동기 SQLite | 비동기 드라이버를 지원하는 확장 백엔드 |
+| `RedisSession` | 여러 워커/서비스 간 공유 메모리 | 지연 시간이 짧은 분산 배포에 적합 |
+| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy가 지원하는 데이터베이스에서 작동 |
+| `MongoDBSession` | 이미 MongoDB를 사용하거나 다중 프로세스 스토리지가 필요한 앱 | 비동기 pymongo 사용, 순서 보존을 위한 원자적 시퀀스 카운터 |
+| `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 스토어와 TTL 및 일관성 제어 지원 |
+| `OpenAIConversationsSession` | OpenAI에서 서버가 관리하는 스토리지 | OpenAI Conversations API 기반 기록 |
+| `OpenAIResponsesCompactionSession` | 자동 압축을 사용하는 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 |
+| `AdvancedSQLiteSession` | SQLite와 분기/분석 기능 | 더 많은 기능을 제공하며 전용 페이지 참고 |
+| `EncryptedSession` | 다른 세션에 암호화와 TTL 추가 | 래퍼이므로 먼저 기반 백엔드 선택 필요 |

-일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 해당 하위 섹션에 링크되어 있습니다.
+일부 구현에는 추가 세부 정보를 제공하는 전용 페이지가 있으며, 해당 하위 섹션에 링크되어 있습니다.

-ChatKit용 Python 서버를 구현하는 경우, ChatKit의 스레드 및 항목 지속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 그대로 대체할 수 있는 것은 아닙니다. [`chatkit-python` 의 ChatKit 데이터 스토어 구현 가이드](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요.
+ChatKit용 Python 서버를 구현하는 경우 ChatKit의 스레드 및 항목 영속성에는 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession`과 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만 ChatKit 스토어를 그대로 대체할 수는 없습니다. [`ChatKit 데이터 스토어 구현에 관한 chatkit-python 가이드`](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참고하세요.

 ### OpenAI Conversations API 세션

-`OpenAIConversationsSession` 을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요.
+`OpenAIConversationsSession`을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요.

 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -259,7 +259,7 @@ print(result.final_output)  # "California"

 ### OpenAI Responses 압축 세션

-Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession` 을 사용하세요. 이 세션은 하위 세션을 감싸며, `should_trigger_compaction` 에 따라 각 턴 이후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession` 을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다.
+Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession`을 사용하세요. 이 구현은 기반 세션을 감싸며 `should_trigger_compaction`을 기준으로 각 턴 이후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession`을 이 구현으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다.

 #### 일반적인 사용법(자동 압축)

@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```

-기본적으로 압축은 후보 임계값에 도달하면 각 턴 이후 실행됩니다.
+기본적으로 압축 후보 임계값에 도달하면 각 턴 이후 압축이 실행됩니다.

-`compaction_mode="previous_response_id"` 는 이미 Responses API 응답 ID로 턴을 체이닝하고 있을 때 가장 잘 동작합니다. `compaction_mode="input"` 은 대신 현재 세션 항목으로부터 압축 요청을 다시 구성합니다. 이는 응답 체인을 사용할 수 없거나 세션 내용을 신뢰할 수 있는 기준으로 삼고 싶을 때 유용합니다. 기본값인 `"auto"` 는 사용 가능한 가장 안전한 옵션을 선택합니다.
+Responses API 응답 ID로 이미 턴을 연결하고 있다면 `compaction_mode="previous_response_id"`가 가장 적합합니다. 반면 `compaction_mode="input"`은 현재 세션 항목에서 압축 요청을 다시 구성하므로, 응답 체인을 사용할 수 없거나 세션 내용을 기준 데이터로 사용하려는 경우에 유용합니다. 기본값인 `"auto"`는 사용 가능한 옵션 중 가장 안전한 것을 선택합니다.

-에이전트가 `ModelSettings(store=False)` 로 실행되는 경우, Responses API는 나중에 조회할 수 있도록 마지막 응답을 보관하지 않습니다. 이 무상태 구성에서는 기본 `"auto"` 모드가 `previous_response_id` 에 의존하지 않고 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요.
+에이전트가 `ModelSettings(store=False)`로 실행되면 Responses API는 나중에 조회할 수 있도록 마지막 응답을 보관하지 않습니다. 이러한 무상태 구성에서는 기본 `"auto"` 모드가 `previous_response_id`에 의존하지 않고 입력 기반 압축으로 대체됩니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참고하세요.

-#### 스트리밍을 차단할 수 있는 자동 압축
+#### 자동 압축으로 인한 스트리밍 차단

-압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행이 완료된 것으로 간주하기 전에 압축이 끝나기를 기다립니다. 스트리밍 모드에서는 압축 작업이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열린 상태로 남아 있을 수 있습니다.
+압축은 세션 기록을 지우고 다시 작성하므로, SDK는 실행이 완료된 것으로 처리하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축 작업이 많은 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초 동안 열린 상태로 유지될 수 있습니다.

-저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()` 을 호출하세요. 자체 기준에 따라 언제 압축을 강제로 실행할지 결정할 수 있습니다.
+지연 시간이 짧은 스트리밍이나 빠른 턴 전환이 필요하면 자동 압축을 비활성화하고 턴 사이 또는 유휴 시간에 `run_compaction()`을 직접 호출하세요. 자체 기준에 따라 압축을 강제로 실행할 시점을 결정할 수 있습니다.

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -332,7 +332,7 @@ result = await Runner.run(

 ### 비동기 SQLite 세션

-`aiosqlite` 기반 SQLite 지속성이 필요할 때 `AsyncSQLiteSession` 을 사용하세요.
+`aiosqlite` 기반의 SQLite 영속성이 필요하면 `AsyncSQLiteSession`을 사용하세요.

 ```bash
 pip install aiosqlite
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)

 ### Redis 세션

-여러 워커 또는 서비스 간 공유 세션 메모리에는 `RedisSession` 을 사용하세요.
+여러 워커 또는 서비스에서 세션 메모리를 공유하려면 `RedisSession`을 사용하세요.

 ```bash
 pip install openai-agents[redis]
@@ -365,11 +365,14 @@ session = RedisSession.from_url(
    url="redis://localhost:6379/0",
 )
 result = await Runner.run(agent, "Hello", session=session)
+await session.close()
 ```

+`from_url(...)`은 Redis 클라이언트를 생성하고 소유합니다. `close()` 이후에는 세션이 종료 상태가 되며, 이후 세션 작업은 `RuntimeError`를 발생시킵니다. 반복적으로 또는 동시에 `close()`를 호출해도 안전합니다. 애플리케이션에서 이미 Redis 클라이언트를 관리하고 있다면 `redis_client=...`를 사용하여 `RedisSession(...)`을 직접 생성하세요. 이 경우 `close()`는 아무 작업도 하지 않으며 호출자가 클라이언트 소유권을 유지하고 세션도 계속 사용할 수 있습니다.
+
 ### SQLAlchemy 세션

-SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션 환경에 적합한 Agents SDK 세션 지속성입니다.
+SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션 수준의 Agents SDK 세션 영속성 구현입니다.

 ```python
 from agents.extensions.memory import SQLAlchemySession
@@ -387,11 +390,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
 session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 ```

-자세한 문서는 [SQLAlchemy 세션](sqlalchemy_session.md)을 참조하세요.
+자세한 문서는 [SQLAlchemy 세션](sqlalchemy_session.md)을 참고하세요.

 ### Dapr 세션

-이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 여러 상태 저장소 백엔드 간에 이동할 수 있는 세션 스토리지를 원할 때 `DaprSession` 을 사용하세요.
+이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 다양한 상태 스토어 백엔드 간에 이동할 수 있는 세션 스토리지가 필요하면 `DaprSession`을 사용하세요.

 ```bash
 pip install openai-agents[dapr]
@@ -414,16 +417,17 @@ async with DaprSession.from_address(

 참고:

-   `from_address(...)` 는 Dapr 클라이언트를 생성하고 수명 주기를 관리합니다. 앱에서 이미 Dapr 클라이언트를 관리하고 있다면 `dapr_client=...` 로 `DaprSession(...)` 을 직접 생성하세요.
-   기반 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...` 을 전달하세요.
-   더 강한 쓰기 후 읽기 보장이 필요하면 `consistency=DAPR_CONSISTENCY_STRONG` 을 전달하세요.
-   Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address` 에서 사용하는 gRPC 포트뿐 아니라 `--dapr-http-port 3500` 도 함께 지정해 Dapr를 시작하세요.
-   로컬 컴포넌트와 문제 해결을 포함한 전체 설정 안내는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요.
+-   `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리하고 있다면 `dapr_client=...`를 사용하여 `DaprSession(...)`을 직접 생성하세요.
+-   컨텍스트에서 나가거나 `close()`를 호출하면 클라이언트를 소유한 세션은 종료 상태가 됩니다. 이후 세션 작업은 `RuntimeError`를 발생시키지만, 반복적으로 또는 동시에 `close()`를 호출해도 안전합니다. 주입된 클라이언트를 사용하면 `close()`는 아무 작업도 하지 않으며 세션을 계속 사용할 수 있습니다.
+-   상태 스토어에서 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 하려면 `ttl=...`을 전달하세요.
+-   쓰기 직후 읽기에 대해 더 강한 보장이 필요하면 `consistency=DAPR_CONSISTENCY_STRONG`을 전달하세요.
+-   Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발 환경에서는 `dapr_address`에 사용되는 gRPC 포트뿐만 아니라 `--dapr-http-port 3500`도 지정하여 Dapr를 시작하세요.
+-   로컬 구성 요소와 문제 해결 방법을 포함한 전체 설정 과정은 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참고하세요.


 ### MongoDB 세션

-이미 MongoDB를 사용하거나 수평 확장이 가능한 다중 프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession` 을 사용하세요.
+이미 MongoDB를 사용하거나 수평 확장이 가능한 다중 프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession`을 사용하세요.

 ```bash
 pip install openai-agents[mongodb]
@@ -448,14 +452,14 @@ await session.close()

 참고:

-   `from_uri(...)` 는 `AsyncMongoClient` 를 생성하고 수명 주기를 관리하며, `session.close()` 시 닫습니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...` 로 `MongoDBSession(...)` 을 직접 생성하세요. 이 경우 `session.close()` 는 아무 작업도 하지 않으며 수명 주기는 호출자에게 남아 있습니다.
-   다른 변경 없이 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 `from_uri(...)` 에 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요.
-   두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=` (기본값 `agent_sessions`) 및 `messages_collection=` (기본값 `agent_messages`) 로 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서는 단조 증가하는 `seq` 카운터를 포함하여 동시 작성자와 프로세스 간 순서를 보존합니다.
-   첫 실행 전에 연결을 확인하려면 `await session.ping()` 을 사용하세요.
+-   `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()` 호출 시 이를 닫습니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...`를 사용하여 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 하지 않으며 수명 주기는 호출자가 관리합니다.
+-   다른 변경 없이 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 `from_uri(...)`에 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결할 수 있습니다.
+-   두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`)과 `messages_collection=`(기본값 `agent_messages`)을 통해 설정할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 단조 증가하는 `seq` 카운터가 포함되어 동시 작성자와 여러 프로세스 간에도 순서를 보존합니다.
+-   첫 실행 전에 연결을 확인하려면 `await session.ping()`을 사용하세요.

 ### 고급 SQLite 세션

-대화 분기, 사용량 분석, 구조화된 쿼리를 지원하는 향상된 SQLite 세션입니다.
+대화 분기, 사용량 분석 및 구조화된 쿼리를 제공하는 향상된 SQLite 세션입니다.

 ```python
 from agents.extensions.memory import AdvancedSQLiteSession
@@ -475,11 +479,11 @@ await session.store_run_usage(result)  # Track token usage
 await session.create_branch_from_turn(2)  # Branch from turn 2
 ```

-자세한 문서는 [고급 SQLite 세션](advanced_sqlite_session.md)을 참조하세요.
+자세한 문서는 [고급 SQLite 세션](advanced_sqlite_session.md)을 참고하세요.

 ### 암호화된 세션

-모든 세션 구현을 위한 투명한 암호화 래퍼입니다.
+모든 세션 구현에 적용할 수 있는 투명한 암호화 래퍼입니다.

 ```python
 from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -502,15 +506,15 @@ session = EncryptedSession(
 result = await Runner.run(agent, "Hello", session=session)
 ```

-자세한 문서는 [암호화된 세션](encrypted_session.md)을 참조하세요.
+자세한 문서는 [암호화된 세션](encrypted_session.md)을 참고하세요.

 ### 기타 세션 유형

-기본 제공 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요.
+그 밖에도 몇 가지 내장 옵션이 있습니다. `examples/memory/`와 `extensions/memory/`의 소스 코드를 참고하세요.

 ## 운영 패턴

-### 세션 ID 명명
+### 세션 ID 명명법

 대화를 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요.

@@ -518,18 +522,18 @@ result = await Runner.run(agent, "Hello", session=session)
 -   스레드 기반: `"thread_abc123"`
 -   컨텍스트 기반: `"support_ticket_456"`

-### 메모리 지속성
+### 메모리 영속성

-   임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용
-   지속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용
-   `aiosqlite` 기반 구현이 필요할 때는 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`) 사용
-   공유 저지연 세션 메모리에는 Redis 기반 세션(`RedisSession.from_url("session_id", url="redis://...")`) 사용
-   SQLAlchemy가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용
-   이미 MongoDB를 사용하거나 다중 프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용
-   기본 제공 텔레메트리, 트레이싱, 데이터 격리와 함께 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용
-   OpenAI Conversations API에 기록을 저장하고 싶다면 OpenAI가 호스팅하는 스토리지(`OpenAIConversationsSession()`) 사용
-   투명한 암호화와 TTL 기반 만료로 모든 세션을 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용
-   더 고급 사용 사례에는 다른 프로덕션 시스템(예: Django)을 위한 사용자 지정 세션 백엔드 구현 고려
+-   임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`)를 사용합니다
+-   영구 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`)를 사용합니다
+-   `aiosqlite` 기반 구현이 필요하면 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`)를 사용합니다
+-   공유되는 저지연 세션 메모리에는 Redis 기반 세션(`RedisSession.from_url("session_id", url="redis://...")`)을 사용합니다
+-   SQLAlchemy에서 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`)을 사용합니다
+-   이미 MongoDB를 사용하거나 수평 확장이 가능한 다중 프로세스 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`)을 사용합니다
+-   내장된 텔레메트리, 트레이싱 및 데이터 격리 기능과 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 스토어 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`)을 사용합니다
+-   OpenAI Conversations API에 기록을 저장하려면 OpenAI 호스팅 스토리지(`OpenAIConversationsSession()`)를 사용합니다
+-   모든 세션에 투명한 암호화와 TTL 기반 만료를 적용하려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`)을 사용합니다
+-   더 고급 사용 사례에서는 다른 프로덕션 시스템(예: Django)을 위한 맞춤형 세션 백엔드 구현을 고려합니다

 ### 여러 세션

@@ -577,7 +581,7 @@ result2 = await Runner.run(

 ## 전체 예제

-세션 메모리가 동작하는 방식을 보여주는 전체 예제입니다.
+다음은 세션 메모리의 실제 동작을 보여 주는 전체 예제입니다.

 ```python
 import asyncio
@@ -639,9 +643,9 @@ if __name__ == "__main__":
    asyncio.run(main())
 ```

-## 사용자 지정 세션 구현
+## 맞춤형 세션 구현

-[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 만들어 자체 세션 메모리를 구현할 수 있습니다.
+[`Session`][agents.memory.session.Session] 프로토콜을 따르는 클래스를 생성하여 자체 세션 메모리를 구현할 수 있습니다.

 ```python
 from agents.memory.session import SessionABC
@@ -692,11 +696,11 @@ result = await Runner.run(
 |---------|-------------|
 | [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 위한 Django ORM 기반 세션 |

-세션 구현을 만들었다면 이곳에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요!
+세션 구현을 개발했다면 여기에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요!

-## API 참조
+## API 레퍼런스

-자세한 API 문서는 다음을 참조하세요.
+자세한 API 문서는 다음을 참고하세요.

 -   [`Session`][agents.memory.session.Session] - 프로토콜 인터페이스
 -   [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 구현
@@ -706,6 +710,6 @@ result = await Runner.run(
 -   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 기반 세션 구현
 -   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현
 -   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 기반 세션 구현
-   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현
-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기와 분석을 지원하는 향상된 SQLite
+-   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 스토어 구현
+-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기 및 분석 기능을 갖춘 향상된 SQLite
 -   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼
@@ -4,31 +4,31 @@ search:
 ---
 # 도구

-도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 컴퓨터 사용 등의 작업을 수행할 수 있습니다. SDK는 다음과 같은 다섯 가지 카테고리를 지원합니다.
+도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 컴퓨터 사용 등의 작업을 수행할 수 있습니다. SDK는 다음 다섯 가지 카테고리를 지원합니다.

-   OpenAI 호스티드 툴: OpenAI 서버에서 모델과 함께 실행됩니다.
-   로컬/런타임 실행 도구: `ComputerTool`과 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다.
-   Function calling: 모든 Python 함수를 도구로 래핑합니다.
+-   호스티드 OpenAI 도구: OpenAI 서버에서 모델과 함께 실행됩니다.
+-   로컬/런타임 실행 도구: `ComputerTool`과 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행할 수 있습니다.
+-   함수 호출: 모든 Python 함수를 도구로 래핑합니다.
 -   Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다.
-   실험적 기능: Codex 도구: 도구 호출에서 워크스페이스 범위의 Codex 작업을 실행합니다.
+-   실험적 기능: Codex 도구: 도구 호출에서 작업 공간 범위의 Codex 작업을 실행합니다.

 ## 도구 유형 선택

-이 페이지를 카탈로그로 활용한 다음, 제어하는 런타임과 일치하는 섹션으로 이동하세요.
+이 페이지를 카탈로그로 활용한 다음, 제어하는 런타임에 해당하는 섹션으로 이동하세요.

-| 원하는 작업 | 시작 위치 |
+| 원하는 작업 | 시작 지점 |
 | --- | --- |
-| OpenAI 관리형 도구 사용(웹 검색, 파일 검색, Code Interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 툴](#hosted-tools) |
+| OpenAI 관리형 도구(웹 검색, 파일 검색, Code Interpreter, 호스티드 MCP, 이미지 생성) 사용 | [호스티드 툴](#hosted-tools) |
 | 도구 검색을 사용하여 대규모 도구 표면을 런타임까지 지연 | [호스티드 툴 검색](#hosted-tool-search) |
-| 생성된 JavaScript에서 여러 도구 호출 조정 | [프로그래매틱 도구 호출](#programmatic-tool-calling) |
+| 생성된 JavaScript에서 여러 도구 호출 조정 | [프로그래밍 방식 도구 호출](#programmatic-tool-calling) |
 | 자체 프로세스 또는 환경에서 도구 실행 | [로컬 런타임 도구](#local-runtime-tools) |
 | Python 함수를 도구로 래핑 | [함수 도구](#function-tools) |
 | 핸드오프 없이 한 에이전트가 다른 에이전트를 호출하도록 설정 | [Agents as tools](#agents-as-tools) |
-| 에이전트에서 워크스페이스 범위의 Codex 작업 실행 | [실험적 기능: Codex 도구](#experimental-codex-tool) |
+| 에이전트에서 작업 공간 범위의 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 벡터 스토어에서 정보를 검색할 수 있습니다.
@@ -40,7 +40,7 @@ OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponse

 고급 호스티드 검색 옵션:

-   `FileSearchTool`은 `vector_store_ids` 및 `max_num_results` 외에도 `filters`, `ranking_options`, `include_search_results`를 지원합니다.
+-   `FileSearchTool`은 `vector_store_ids`와 `max_num_results` 외에도 `filters`, `ranking_options`, `include_search_results`를 지원합니다.
 -   `WebSearchTool`은 `filters`, `user_location`, `search_context_size`를 지원합니다.

 ```python
@@ -64,9 +64,9 @@ async def main():

 ### 호스티드 툴 검색

-도구 검색을 사용하면 OpenAI Responses 모델이 대규모 도구 표면을 런타임까지 지연하므로, 모델은 현재 턴에 필요한 하위 집합만 로드합니다. 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 미리 노출하지 않으면서 도구 스키마 토큰을 줄이고자 할 때 유용합니다.
+도구 검색을 사용하면 OpenAI Responses 모델이 대규모 도구 표면의 로드를 런타임까지 지연하여 현재 턴에 필요한 일부 도구만 로드할 수 있습니다. 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 처음부터 노출하지 않으면서 도구 스키마 토큰을 줄이려는 경우에 유용합니다.

-에이전트를 구축할 때 후보 도구가 이미 정해져 있다면 호스티드 툴 검색으로 시작하세요. 애플리케이션에서 로드할 항목을 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 이 모드를 자동으로 실행하지 않습니다.
+에이전트를 빌드할 때 후보 도구가 이미 정해져 있다면 호스티드 툴 검색부터 사용하세요. 애플리케이션에서 로드할 항목을 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행형 도구 검색도 지원하지만, 표준 `Runner`는 이 모드를 자동으로 실행하지 않습니다.

 ```python
 from typing import Annotated
@@ -112,25 +112,25 @@ print(result.final_output)
 알아둘 사항:

 -   호스티드 툴 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원 여부는 `openai>=2.25.0`에 따라 달라집니다.
-   에이전트에서 지연 로딩 표면을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요.
+-   에이전트에서 지연 로드 표면을 구성할 때 정확히 하나의 `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`처럼 관련 도구가 많은 경우 가장 적합합니다.
+-   지연 로드 함수 도구는 `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개 미만으로 제한하세요.
+-   가능하면 개별적으로 지연되는 여러 함수보다 네임스페이스 또는 호스티드 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`를 참조하세요.
+-   `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)

-### 프로그래매틱 도구 호출
+### 프로그래밍 방식 도구 호출

-프로그래매틱 도구 호출을 사용하면 지원되는 OpenAI Responses 모델이 사용 가능한 도구를 호출하고, 그 출력을 결합하며, 하나의 결과를 모델에 반환하는 JavaScript를 생성할 수 있습니다. 모든 도구 호출 후 모델 왕복을 수행하지 않고도 루프, 분기, 병렬 호출 또는 중간 계산을 활용하는 범위가 제한된 워크플로에 유용합니다.
+프로그래밍 방식 도구 호출을 사용하면 지원되는 OpenAI Responses 모델이 사용 가능한 도구를 호출하고, 출력을 결합하고, 하나의 결과를 모델에 반환하는 JavaScript를 생성할 수 있습니다. 모든 도구 호출 후 모델을 왕복하지 않고도 반복, 분기, 병렬 호출 또는 중간 계산을 활용할 수 있는 제한된 워크플로에 유용합니다.

-생성된 프로그램은 새로운 호스티드 V8 환경에서 실행됩니다. 이 환경에는 Node.js API, 파일 시스템 또는 네트워크 액세스, 영구 프로세스가 없습니다. 프로그램은 명시적으로 허용한 도구와만 상호 작용할 수 있습니다.
+생성된 프로그램은 새로운 호스티드 V8 환경에서 실행됩니다. Node.js API, 파일 시스템 또는 네트워크에 접근할 수 없으며 영구 프로세스도 제공되지 않습니다. 프로그램은 명시적으로 허용한 도구와만 상호 작용할 수 있습니다.

 ```python
 from pydantic import BaseModel
@@ -167,21 +167,22 @@ print(result.final_output)

 알아둘 사항:

-   프로그래매틱 도구 호출은 지원되는 OpenAI Responses 모델에서만 사용할 수 있습니다. `ProgrammaticToolCallingTool()` 및 `tool_choice="programmatic_tool_calling"`은 Chat Completions 모델과 Responses 이외의 백엔드에서 거부됩니다.
-   에이전트에는 `ProgrammaticToolCallingTool()`을 최대 하나만 추가하세요. 에이전트는 프로그래밍 방식으로 호출 가능한 도구, `ToolSearchTool()` 또는 프롬프트로 관리되는 도구 표면 중 하나 이상도 노출해야 합니다.
-   `allowed_callers`는 도구를 호출할 수 있는 방식을 제어합니다. 생략하면 모델의 직접 호출만 허용됩니다. 프로그램에서만 액세스하려면 `["programmatic"]`을 사용하고, 두 방식 모두 허용하려면 `["direct", "programmatic"]`을 사용하세요.
-   이 기능을 선택적으로 사용할 수 있는 SDK 도구 유형은 `FunctionTool`, `CustomTool`, `ShellTool`, `ApplyPatchTool`, `HostedMCPTool`, `CodeInterpreterTool`입니다. 함수, 사용자 지정, 셸 및 패치 적용 도구는 `allowed_callers`를 직접 노출합니다. 호스티드 MCP와 Code Interpreter의 경우 `tool_config` 내부에 `allowed_callers`를 설정하세요.
-   `@function_tool(allowed_callers=[...])`의 경우 Pydantic 모델, TypedDict 또는 데이터 클래스와 같은 구조화된 반환 어노테이션은 자동으로 엄격한 객체 출력 스키마가 되며, 값이 프로그램에 반환되기 전에 검증됩니다. 함수에 사용할 수 있는 어노테이션이 없다면 `output_type=...`을 사용하고, 엄격한 객체 스키마가 이미 있다면 하위 수준의 우회 수단인 `output_json_schema={...}`를 사용하세요. `output_type`과 `output_json_schema`는 함께 사용할 수 없습니다. 일반 `str`, `Any`, `None` 반환은 타입이 지정되지 않은 상태로 유지됩니다.
-   프로그램 소유 SDK 도구에서도 일반적인 Runner 수명 주기가 계속 사용됩니다. 도구 입력 및 출력 가드레일, 훅, 시간 제한, 동시성 제한, 재시도, 승인, 세션, `RunState` 일시 중지/재개 동작이 계속 적용되며, SDK는 각 하위 호출의 프로그램 호출자 관계를 유지합니다.
-   승인이 필요하거나 영향이 큰 도구는 일반적으로 직접 호출로 유지하는 것이 좋습니다. 그러면 더 큰 프로그램의 일부가 되기 전에 사람이 각 작업을 검토할 수 있습니다. 프로그램 소유 호출이 승인을 위해 일시 중지되면 `RunState`를 통해 인터럽션(중단 처리)을 해결하고 평소와 같이 원래 실행을 재개하세요.
-   프로그래매틱 도구 호출은 [호스티드 툴 검색](#hosted-tool-search)과 함께 사용할 수 있습니다. 생성된 프로그램이 지연된 도구를 호출하려면 먼저 모델이 해당 도구를 로드해야 합니다.
-   `program` 항목과 프로그램 소유 하위 호출은 [`ToolCallItem`][agents.items.ToolCallItem] 항목으로 표시됩니다. 일치하는 `program_output`은 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]으로 표시됩니다. 검사에 관한 자세한 내용은 [결과](results.md#new-items) 및 [스트리밍](streaming.md#run-item-event-names)을 참조하세요.
-   완전한 동시 실행 재고 계획 코드 예제는 `examples/tools/programmatic_tool_calling.py`를 참조하세요.
-   공식 플랫폼 가이드: [프로그래매틱 도구 호출](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)
+-   프로그래밍 방식 도구 호출은 지원되는 OpenAI Responses 모델에서만 사용할 수 있습니다. `ProgrammaticToolCallingTool()`과 `tool_choice="programmatic_tool_calling"`은 Chat Completions 모델 및 Responses가 아닌 백엔드에서 거부됩니다.
+-   에이전트에는 `ProgrammaticToolCallingTool()`을 최대 하나만 추가하세요. 에이전트는 프로그래밍 방식으로 호출할 수 있는 도구를 하나 이상 노출하거나, 네임스페이스, 지연 함수 또는 지연된 호스티드 MCP 서버를 기반으로 하는 `ToolSearchTool()`을 제공하거나, 불투명한 프롬프트 관리형 도구 표면을 제공해야 합니다. 검색 가능한 표면이 없는 단독 `ToolSearchTool()`은 거부됩니다.
+-   `allowed_callers`는 도구를 호출할 수 있는 방식을 제어합니다. 생략하면 모델의 직접 호출만 허용됩니다. 프로그램에서만 접근하도록 하려면 `["programmatic"]`을 사용하고, 두 방식 모두 허용하려면 `["direct", "programmatic"]`을 사용하세요.
+-   이 기능을 선택적으로 사용할 수 있는 SDK 도구 유형은 `FunctionTool`, `CustomTool`, `ShellTool`, `ApplyPatchTool`, `HostedMCPTool`, `CodeInterpreterTool`입니다. 함수, 사용자 지정, 셸, 패치 적용 도구는 `allowed_callers`를 직접 노출합니다. 호스티드 MCP와 Code Interpreter의 경우 `tool_config` 내부에서 `allowed_callers`를 설정하세요.
+-   `@function_tool(allowed_callers=[...])`의 경우 Pydantic 모델, TypedDict 또는 dataclass와 같은 구조화된 반환 어노테이션은 자동으로 엄격한 객체 출력 스키마가 되며, 값이 프로그램에 반환되기 전에 검증됩니다. 함수에 사용할 수 있는 어노테이션이 없다면 `output_type=...`을 사용하고, 이미 엄격한 객체 스키마가 있다면 하위 수준의 우회 수단인 `output_json_schema={...}`를 사용하세요. `output_type`과 `output_json_schema`는 함께 사용할 수 없습니다. 일반 `str`, `Any`, `None` 반환은 유형이 지정되지 않은 상태로 유지됩니다. 스키마를 기반으로 하는 프로그램 소유 호출에서는 자유 형식 텍스트가 출력 스키마를 충족하지 않으므로 기본 실패 포매터가 비활성화됩니다. 따라서 스키마를 준수하는 JSON을 반환하는 사용자 지정 `failure_error_function`을 제공하지 않으면 핸들러 예외가 전파됩니다.
+-   프로그램 소유 SDK 도구에도 일반적인 Runner 수명 주기가 그대로 적용됩니다. 도구 입력 및 출력 가드레일, 훅, 시간 제한, 동시성 제한, 승인, 세션, `RunState` 일시 중지/재개 동작이 계속 적용되며, SDK는 각 하위 호출과 프로그램 호출자의 관계를 보존합니다.
+-   `ProgrammaticToolCallingTool()`이 있으면 프로그램이 실행되기 전이라도 모델 요청 재시도에 더 엄격한 재실행 안전성 경계가 적용됩니다. SDK는 이러한 요청에 대해 제공자 관리형 재시도와 WebSocket 사전 이벤트 재시도를 비활성화합니다. Runner 재시도 정책은 제공자의 지침이 재실행해도 안전하다고 명시적으로 표시한 경우에만 재시도합니다. `retry_policies.network_error()`만으로는 이 경계를 재정의하지 않습니다.
+-   승인에 민감하거나 영향이 큰 도구는 일반적으로 직접 호출로 유지하는 것이 좋습니다. 그러면 더 큰 프로그램의 일부가 되기 전에 각 작업을 사람이 검토할 수 있습니다. 프로그램 소유 호출이 승인을 위해 일시 중지되면 평소와 같이 `RunState`를 통해 인터럽션(중단 처리)을 해결하고 원래 실행을 재개하세요.
+-   프로그래밍 방식 도구 호출은 [호스티드 툴 검색](#hosted-tool-search)과 함께 사용할 수 있습니다. 생성된 프로그램이 지연된 도구를 호출하려면 모델이 먼저 해당 도구를 로드해야 합니다.
+-   `program` 항목과 일반적인 프로그램 소유 하위 도구 호출은 [`ToolCallItem`][agents.items.ToolCallItem] 항목으로 표시됩니다. 이에 대응하는 `program_output`은 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]으로 표시됩니다. 호스티드 MCP 승인 요청과 도구 카탈로그에는 대신 특수 MCP 항목과 스트림 이벤트가 사용됩니다. 검사에 관한 자세한 내용은 [결과](results.md#new-items)와 [스트리밍](streaming.md#run-item-event-names)을 참조하세요.
+-   완전한 동시성 재고 계획 코드 예제는 `examples/tools/programmatic_tool_calling.py`를 참조하세요.
+-   공식 플랫폼 가이드: [프로그래밍 방식 도구 호출](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)

 ### 호스티드 컨테이너 셸 + 스킬

-`ShellTool`은 OpenAI 호스티드 컨테이너 실행도 지원합니다. 로컬 런타임 대신 관리형 컨테이너에서 모델이 셸 명령을 실행하도록 하려면 이 모드를 사용하세요.
+`ShellTool`은 OpenAI 호스티드 컨테이너 실행도 지원합니다. 모델이 로컬 런타임이 아닌 관리형 컨테이너에서 셸 명령을 실행하도록 하려면 이 모드를 사용하세요.

 ```python
 from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -214,52 +215,52 @@ result = await Runner.run(
 print(result.final_output)
 ```

-이후 실행에서 기존 컨테이너를 재사용하려면 `environment={"type": "container_reference", "container_id": "cntr_..."}`를 설정하세요.
+후속 실행에서 기존 컨테이너를 재사용하려면 `environment={"type": "container_reference", "container_id": "cntr_..."}`를 설정하세요.

 알아둘 사항:

 -   호스티드 셸은 Responses API 셸 도구를 통해 사용할 수 있습니다.
-   `container_auto`는 요청을 위한 컨테이너를 프로비저닝하고, `container_reference`는 기존 컨테이너를 재사용합니다.
-   `container_auto`에는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다.
-   `environment.skills`는 스킬 참조 및 인라인 스킬 번들을 허용합니다.
+-   `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`를 참조하세요.
+-   허용 목록 모드에서 `network_policy.domain_secrets`는 이름을 기준으로 도메인 범위의 보안 비밀을 주입할 수 있습니다.
+-   완전한 코드 예제는 `examples/tools/container_shell_skill_reference.py`와 `examples/tools/container_shell_inline_skill.py`를 참조하세요.
 -   OpenAI 플랫폼 가이드: [셸](https://platform.openai.com/docs/guides/tools-shell) 및 [스킬](https://platform.openai.com/docs/guides/tools-skills)

 ## 로컬 런타임 도구

-로컬 런타임 도구는 모델 응답 자체의 외부에서 실행됩니다. 모델이 도구를 호출할 시점을 계속 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경에서 수행합니다.
+로컬 런타임 도구는 모델 응답 자체의 외부에서 실행됩니다. 호출 시점은 여전히 모델이 결정하지만, 실제 작업은 애플리케이션이나 구성된 실행 환경에서 수행합니다.

-`ComputerTool`과 `ApplyPatchTool`에는 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 지원합니다. 관리형 실행을 사용하려면 위의 호스티드 컨테이너 구성을 사용하고, 자체 프로세스에서 명령을 실행하려면 아래의 로컬 런타임 구성을 사용하세요.
+`ComputerTool`과 `ApplyPatchTool`에는 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 지원합니다. 관리형 실행을 원한다면 위의 호스티드 컨테이너 구성을 사용하고, 자체 프로세스에서 명령을 실행하려면 아래의 로컬 런타임 구성을 사용하세요.

-로컬 런타임 도구에는 다음 구현을 제공해야 합니다.
+로컬 런타임 도구를 사용하려면 구현을 제공해야 합니다.

-   [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 사용하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현하세요.
-   [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행을 모두 지원하는 최신 셸 도구
-   [`LocalShellTool`][agents.tool.LocalShellTool]: 레거시 로컬 셸 통합
-   [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: 로컬에서 diff를 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요.
-   로컬 셸 스킬은 `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 컴퓨터 도구
+### ComputerTool과 Responses 컴퓨터 도구

-`ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면 SDK가 해당 하네스를 OpenAI Responses API의 컴퓨터 표면에 매핑합니다.
+`ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면 SDK가 이 하네스를 OpenAI Responses API의 컴퓨터 표면에 매핑합니다.

-명시적인 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 정식 출시(GA)된 기본 제공 도구 페이로드 `{"type": "computer"}`를 전송합니다. 이전 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다.
+명시적인 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA 기본 제공 도구 페이로드 `{"type": "computer"}`를 전송합니다. 이전 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 계속 사용합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션과 동일합니다.

 -   모델: `computer-use-preview` -> `gpt-5.5`
 -   도구 선택자: `computer_use_preview` -> `computer`
-   컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 일괄 처리된 `actions[]`
-   잘림: 프리뷰 경로에서는 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 불필요
+-   컴퓨터 호출 형식: 각 `computer_call`당 하나의 `action` -> `computer_call`의 일괄 처리된 `actions[]`
+-   잘림: 프리뷰 경로에서는 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 필요하지 않음

-SDK는 실제 Responses 요청의 유효 모델을 기준으로 해당 전송 형식을 선택합니다. 프롬프트 템플릿을 사용하며 프롬프트가 모델을 소유하기 때문에 요청에서 `model`을 생략하는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하지 않으면 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다.
+SDK는 실제 Responses 요청의 유효 모델을 기준으로 해당 전송 형식을 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하기 때문에 요청에서 `model`을 생략하면, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다.

-[`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 기본 제공 선택자로 정규화됩니다. `ComputerTool`이 없으면 이러한 문자열은 여전히 일반 함수 이름처럼 동작합니다.
+[`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효한 요청 모델과 일치하는 기본 제공 선택자로 정규화됩니다. `ComputerTool`이 없으면 이러한 문자열은 계속 일반 함수 이름처럼 동작합니다.

-`ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 기반으로 할 때는 이 차이가 중요합니다. GA `computer` 페이로드는 직렬화 시 `environment` 또는 크기 정보가 필요하지 않으므로 확인되지 않은 팩토리도 사용할 수 있습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 전송할 수 있도록 확인된 `Computer` 또는 `AsyncComputer` 인스턴스가 여전히 필요합니다.
+`ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 기반으로 하는 경우 이 차이가 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기가 필요하지 않으므로 아직 해석되지 않은 팩토리도 사용할 수 있습니다. 프리뷰 호환 직렬화에서는 SDK가 `environment`, `display_width`, `display_height`를 전송할 수 있도록 해석된 `Computer` 또는 `AsyncComputer` 인스턴스가 필요합니다.

-런타임에서 두 경로는 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 포함된 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 일괄 처리된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 해당 작업을 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요.
+런타임에서는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 하나의 `action`이 포함된 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 일괄 처리된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. Playwright 기반의 실행 가능한 하네스는 `examples/tools/computer_use.py`를 참조하세요.

 ```python
 from agents import Agent, ApplyPatchTool, ShellTool
@@ -305,14 +306,16 @@ agent = Agent(

 모든 Python 함수를 도구로 사용할 수 있습니다. Agents SDK가 도구를 자동으로 설정합니다.

-   도구 이름은 Python 함수 이름이 됩니다. 또는 이름을 직접 제공할 수 있습니다.
-   도구 설명은 함수의 docstring에서 가져옵니다. 또는 설명을 직접 제공할 수 있습니다.
-   함수 입력의 스키마는 함수 인수에서 자동으로 생성됩니다.
-   비활성화하지 않는 한 각 입력의 설명은 함수의 docstring에서 가져옵니다.
+-   도구 이름은 Python 함수의 이름이 됩니다. 또는 이름을 직접 제공할 수 있습니다
+-   도구 설명은 함수의 docstring에서 가져옵니다. 또는 설명을 직접 제공할 수 있습니다
+-   함수 입력 스키마는 함수의 인수에서 자동으로 생성됩니다
+-   비활성화하지 않는 한 각 입력에 대한 설명은 함수의 docstring에서 가져옵니다

-함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring을 파싱하기 위해 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성을 위해 `pydantic`을 함께 사용합니다.
+`@tool`로 생성한 도구는 읽기 전용 `__wrapped__` 속성을 통해 원래 Python 호출 가능 객체를 노출합니다. 이는 검사 및 테스트에 유용하지만, 직접 호출하면 스키마 검증, 컨텍스트 주입, 가드레일, 시간 제한, 실패 처리, 트레이싱을 포함한 도구 런타임 파이프라인을 우회합니다. 직접 구성한 `FunctionTool` 인스턴스는 `__wrapped__`를 노출하지 않습니다.

-OpenAI Responses 모델을 사용하는 경우 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 함수 도구를 로드할 때까지 해당 도구를 숨깁니다. [`tool_namespace()`][agents.tool.tool_namespace]를 사용하여 관련 함수 도구를 그룹화할 수도 있습니다. 전체 설정 및 제약 조건은 [호스티드 툴 검색](#hosted-tool-search)을 참조하세요.
+함수 시그니처를 추출하기 위해 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)을 참조하세요.

 ```python
 import json
@@ -365,12 +368,12 @@ for tool in agent.tools:

 ```

-1.  모든 Python 타입을 함수 인수로 사용할 수 있으며, 함수는 동기식 또는 비동기식일 수 있습니다.
-2.  docstring이 있으면 설명 및 인수 설명을 가져오는 데 사용됩니다.
-3.  함수는 선택적으로 `context`를 받을 수 있습니다. 이 인수는 첫 번째 인수여야 합니다. 도구 이름, 설명, 사용할 docstring 스타일 등의 재정의도 설정할 수 있습니다.
+1.  모든 Python 유형을 함수의 인수로 사용할 수 있으며, 함수는 동기식 또는 비동기식일 수 있습니다.
+2.  docstring이 있으면 설명과 인수 설명을 추출하는 데 사용됩니다.
+3.  함수는 선택적으로 `context`를 받을 수 있습니다. 이 인수는 첫 번째 인수여야 합니다. 도구 이름, 설명, 사용할 docstring 스타일 등의 재정의 항목도 설정할 수 있습니다.
 4.  데코레이팅된 함수를 도구 목록에 전달할 수 있습니다.

-??? note "출력을 확인하려면 펼치기"
+??? note "출력을 보려면 펼치기"

    ```
    fetch_weather
@@ -442,20 +445,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]
+-   텍스트: 문자열이나 문자열로 변환 가능한 객체 또는 [`ToolOutputText`][agents.tool.ToolOutputText] 또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]

 ### 사용자 지정 함수 도구

-Python 함수를 도구로 사용하고 싶지 않은 경우도 있습니다. 원하는 경우 [`FunctionTool`][agents.tool.FunctionTool]을 직접 생성할 수 있습니다. 다음 항목을 제공해야 합니다.
+Python 함수를 도구로 사용하고 싶지 않은 경우도 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool]을 직접 생성할 수 있습니다. 다음 항목을 제공해야 합니다.

 -   `name`
 -   `description`
 -   인수의 JSON 스키마인 `params_json_schema`
-   [`ToolContext`][agents.tool_context.ToolContext]와 JSON 문자열 형태의 인수를 받아 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 비동기 함수인 `on_invoke_tool`
+-   [`ToolContext`][agents.tool_context.ToolContext]와 JSON 문자열 형식의 인수를 받고 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 비동기 함수인 `on_invoke_tool`

 ```python
 from typing import Any
@@ -488,12 +491,12 @@ tool = FunctionTool(
 )
 ```

-### 자동 인수 및 docstring 파싱
+### 인수 및 docstring 자동 파싱

-앞서 설명했듯이 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 이에 관한 참고 사항은 다음과 같습니다.
+앞서 설명했듯이 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구 및 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 다음 사항을 참고하세요.

-1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 어노테이션을 사용하여 인수의 타입을 파악하고 전체 스키마를 나타내는 Pydantic 모델을 동적으로 구축합니다. Python 기본 타입, Pydantic 모델, TypedDict 등을 포함한 대부분의 타입을 지원합니다.
-2. docstring 파싱에는 `griffe`를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동 감지하려고 시도하지만 이는 최선형 방식이며, `function_tool`을 호출할 때 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 docstring 파싱을 비활성화할 수도 있습니다. Google 스타일 docstring의 경우 파서는 요약 텍스트 바로 뒤에 빈 줄 없이 오는 `Args:`, `Arguments:`, `Params:`, `Parameters:` 섹션도 허용합니다.
+1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 유형 어노테이션을 사용하여 인수의 유형을 파악하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 유형, Pydantic 모델, TypedDict 등을 포함한 대부분의 유형을 지원합니다.
+2. docstring을 파싱하는 데 `griffe`를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동으로 감지하려고 시도하지만 완벽하지 않을 수 있으므로 `function_tool`을 호출할 때 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 docstring 파싱을 비활성화할 수도 있습니다. Google 스타일 docstring의 경우 파서는 요약 텍스트 바로 다음에 빈 줄 없이 배치된 `Args:`, `Arguments:`, `Params:`, `Parameters:` 섹션도 허용합니다.

 스키마 추출 코드는 [`agents.function_schema`][]에 있습니다.

@@ -540,13 +543,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
@@ -574,11 +577,11 @@ except ToolTimeoutError as e:

 ### 함수 도구의 오류 처리

-`@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 RunContextWrapper
@@ -606,7 +609,7 @@ def get_user_profile(user_id: str) -> str:

 ## Agents as tools

-일부 워크플로에서는 제어권을 핸드오프하는 대신 중앙 에이전트가 전문 에이전트 네트워크를 오케스트레이션하도록 할 수 있습니다. 에이전트를 도구로 모델링하여 이를 구현할 수 있습니다.
+일부 워크플로에서는 제어권을 핸드오프하는 대신 중앙 에이전트가 전문 에이전트 네트워크를 오케스트레이션하도록 할 수 있습니다. 에이전트를 agents as tools로 모델링하여 이를 구현할 수 있습니다.

 ```python
 import asyncio
@@ -652,9 +655,9 @@ if __name__ == "__main__":

 ### 도구 에이전트 사용자 지정

-`agent.as_tool` 함수는 에이전트를 도구로 쉽게 변환할 수 있는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval`과 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 사용하는 구조화된 입력도 지원합니다.
+`agent.as_tool` 함수는 에이전트를 도구로 쉽게 변환할 수 있는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval`과 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 통한 구조화된 입력도 지원합니다.

-상태 옵션은 도구 호출로 시작된 중첩 에이전트 실행을 구성하며, 상위 실행의 대화 상태는 자동으로 상속되지 않습니다. 상위 실행과 중첩 실행 간에 클라이언트 관리형 기록을 공유하려면 동일한 `session`을 두 실행 모두에 명시적으로 전달하세요. `Runner.run`과 마찬가지로 중첩 실행에는 하나의 상태 전략을 선택하세요. 클라이언트 관리형 `session`을 사용하거나 `previous_response_id` 또는 `conversation_id`를 통한 서버 관리형 연속 실행을 사용해야 합니다.
+상태 옵션은 도구 호출로 시작되는 중첩 에이전트 실행을 구성하며, 상위 실행의 대화 상태는 자동으로 상속되지 않습니다. 상위 실행과 중첩 실행 간에 클라이언트 관리형 기록을 공유하려면 동일한 `session`을 양쪽에 명시적으로 전달하세요. `Runner.run`과 마찬가지로 중첩 실행에는 하나의 상태 전략을 선택하세요. 클라이언트 관리형 `session`을 사용하거나 `previous_response_id` 또는 `conversation_id`를 통한 서버 관리형 연속 실행을 사용합니다.

 ```python
 from agents.decorators import tool
@@ -678,12 +681,12 @@ async def run_my_agent() -> str:

 ### 도구 에이전트의 구조화된 입력

-기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 예상하지만, `parameters`에 Pydantic 모델 또는 데이터 클래스 타입을 전달하여 구조화된 스키마를 노출할 수 있습니다.
+기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 예상하지만, `parameters`에 Pydantic 모델 또는 dataclass 유형을 전달하여 구조화된 스키마를 노출할 수 있습니다.

 추가 옵션:

- `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON 스키마를 포함합니다.
- `input_builder=...`를 사용하면 구조화된 도구 인수가 중첩 에이전트 입력으로 변환되는 방식을 완전히 사용자 지정할 수 있습니다.
+- `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON Schema를 포함합니다.
+- `input_builder=...`를 사용하면 구조화된 도구 인수를 중첩 에이전트 입력으로 변환하는 방식을 완전히 사용자 지정할 수 있습니다.
 - `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 내부에 파싱된 구조화 페이로드를 포함합니다.

 ```python
@@ -712,11 +715,11 @@ translator_tool = translator_agent.as_tool(

 ### 사용자 지정 출력 추출

-경우에 따라 중앙 에이전트에 반환하기 전에 도구 에이전트의 출력을 수정할 수 있습니다. 다음과 같은 상황에서 유용합니다.
+특정한 경우 중앙 에이전트에 반환하기 전에 도구 에이전트의 출력을 수정할 수 있습니다. 다음과 같은 작업을 수행할 때 유용합니다.

-   하위 에이전트의 채팅 기록에서 특정 정보(예: JSON 페이로드)를 추출
-   에이전트의 최종 답변을 변환하거나 형식을 변경(예: Markdown을 일반 텍스트 또는 CSV로 변환)
-   출력을 검증하거나 에이전트 응답이 없거나 형식이 잘못된 경우 대체 값 제공
+-   하위 에이전트의 채팅 기록에서 특정 정보(예: JSON 페이로드) 추출
+-   에이전트의 최종 답변 변환 또는 형식 변경(예: Markdown을 일반 텍스트나 CSV로 변환)
+-   출력 검증 또는 에이전트의 응답이 누락되었거나 형식이 잘못된 경우 대체 값 제공

 `as_tool` 메서드에 `custom_output_extractor` 인수를 제공하여 이를 수행할 수 있습니다.

@@ -737,11 +740,11 @@ json_tool = data_agent.as_tool(
 )
 ```

-사용자 지정 추출기 내부에서 중첩된 [`RunResult`][agents.result.RunResult]는 [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출합니다. 이는 중첩된 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다. [결과 가이드](results.md#agent-as-tool-metadata)를 참조하세요.
+사용자 지정 추출기 내부에서 중첩된 [`RunResult`][agents.result.RunResult]는 [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출합니다. 이는 중첩된 결과를 후처리할 때 외부 도구 이름, 호출 ID 또는 원문 인수가 필요한 경우 유용합니다. [결과 가이드](results.md#agent-as-tool-metadata)를 참조하세요.

-### 중첩 에이전트 실행의 스트리밍
+### 중첩 에이전트 실행 스트리밍

-`as_tool`에 `on_stream` 콜백을 전달하면 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신하면서도 스트림이 완료된 후 최종 출력을 반환할 수 있습니다.
+스트림이 완료되면 최종 출력을 반환하면서 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신하려면 `on_stream` 콜백을 `as_tool`에 전달하세요.

 ```python
 from agents import AgentToolStreamEvent
@@ -761,8 +764,8 @@ billing_agent_tool = billing_agent.as_tool(

 예상 동작:

- 이벤트 유형은 `StreamEvent["type"]`을 따릅니다: `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`
- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드에서 실행되고, 최종 출력을 반환하기 전에 스트림을 모두 소비합니다.
+- 이벤트 유형은 `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`를 참조하세요.
@@ -827,21 +830,21 @@ asyncio.run(main())
 `is_enabled` 매개변수는 다음을 허용합니다.

 -   **불리언 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화)
-   **호출 가능 함수**: `(context, agent)`를 받아 불리언 값을 반환하는 함수
+-   **호출 가능 함수**: `(context, agent)`를 받고 불리언을 반환하는 함수
 -   **비동기 함수**: 복잡한 조건부 로직을 위한 비동기 함수

-비활성화된 도구는 런타임에 LLM에서 완전히 숨겨지므로 다음과 같은 용도에 유용합니다.
+비활성화된 도구는 런타임에 LLM에서 완전히 숨겨지므로 다음과 같은 용도로 유용합니다.

-   사용자 권한에 따른 기능 게이팅
+-   사용자 권한 기반 기능 게이팅
 -   환경별 도구 가용성(개발 환경과 프로덕션 환경)
 -   서로 다른 도구 구성의 A/B 테스트
-   런타임 상태에 따른 동적 도구 필터링
+-   런타임 상태 기반 동적 도구 필터링

 ## 실험적 기능: Codex 도구

-`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중에 워크스페이스 범위의 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있도록 합니다. 이 기능은 실험적이며 변경될 수 있습니다.
+`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중에 작업 공간 범위의 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있도록 합니다. 이 기능 표면은 실험적이며 변경될 수 있습니다.

-현재 실행을 벗어나지 않고 기본 에이전트가 범위가 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 이 도구를 사용하세요. 기본 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다.
+메인 에이전트가 현재 실행을 벗어나지 않고 제한된 작업 공간 작업을 Codex에 위임하도록 하려면 사용하세요. 기본 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 이름은 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다.

 ```python
 from agents import Agent
@@ -872,31 +875,31 @@ agent = Agent(

 다음 옵션 그룹부터 시작하세요.

-   실행 표면: `sandbox_mode` 및 `working_directory`는 Codex가 작업할 수 있는 위치를 정의합니다. 두 옵션을 함께 사용하고, 작업 디렉터리가 Git 저장소 내부에 없으면 `skip_git_repo_check=True`를 설정하세요.
-   스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, 추론 강도, 승인 정책, 추가 디렉터리, 네트워크 액세스 및 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 우선 사용하세요.
+-   실행 표면: `sandbox_mode`와 `working_directory`는 Codex가 작업할 수 있는 위치를 정의합니다. 두 옵션을 함께 사용하고, 작업 디렉터리가 Git 저장소 내부에 없으면 `skip_git_repo_check=True`를 설정하세요.
+-   스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, 추론 수준, 승인 정책, 추가 디렉터리, 네트워크 접근, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 사용하세요.
 -   턴 기본값: `default_turn_options=TurnOptions(...)`는 `idle_timeout_seconds` 및 선택적 취소 `signal`과 같은 턴별 동작을 구성합니다.
-   도구 I/O: 도구 호출에는 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 포함된 `inputs` 항목이 하나 이상 있어야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다.
+-   도구 I/O: 도구 호출에는 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }` 형식의 `inputs` 항목이 하나 이상 포함되어야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다.

-스레드 재사용과 영속성은 별도의 제어 항목입니다.
+스레드 재사용과 지속성은 별도의 제어 항목입니다.

-   `persist_session=True`는 동일한 도구 인스턴스에 대한 반복 호출에서 하나의 Codex 스레드를 재사용합니다.
-   `use_run_context_thread_id=True`는 동일한 변경 가능 컨텍스트 객체를 공유하는 여러 실행에서 실행 컨텍스트에 스레드 ID를 저장하고 재사용합니다.
-   스레드 ID의 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 구성된 `thread_id` 옵션 순입니다.
-   기본 실행 컨텍스트 키는 `name="codex"`일 때 `codex_thread_id`이고, `name="codex_<suffix>"`일 때 `codex_thread_id_<suffix>`입니다. `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_<suffix>"`일 때 `codex_thread_id_<suffix>`입니다. `run_context_thread_id_key`로 재정의할 수 있습니다.

 런타임 구성:

-   인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나 `codex_options={"api_key": "..."}`를 전달하세요.
+-   인증: `CODEX_API_KEY`(권장) 또는 `OPENAI_API_KEY`를 설정하거나 `codex_options={"api_key": "..."}`를 전달합니다.
 -   런타임: `codex_options.base_url`은 CLI 기본 URL을 재정의합니다.
-   바이너리 확인: CLI 경로를 고정하려면 `codex_options.codex_path_override` 또는 `CODEX_PATH`를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 확인한 후 번들로 제공되는 벤더 바이너리를 대체 경로로 사용합니다.
-   환경: `codex_options.env`는 하위 프로세스 환경을 완전히 제어합니다. 이 옵션이 제공되면 하위 프로세스는 `os.environ`을 상속하지 않습니다.
-   스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes` 또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`는 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536`~`67108864`이며, 기본값은 `8388608`입니다.
+-   바이너리 확인: 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`가 포함되며, 사용량은 `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`를 참조하세요.
+-   [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`를 참조하세요.
@@ -4,31 +4,34 @@ search:
 ---
 # Model context protocol (MCP)

-[Model context protocol](https://modelcontextprotocol.io/introduction)（MCP）标准化了应用如何向语言模型公开工具和
-上下文。来自官方文档：
+[Model context protocol](https://modelcontextprotocol.io/introduction)（MCP）对应用程序向语言模型提供工具和上下文的方式进行了标准化。官方文档中的说明如下：

-> MCP是一种开放协议，标准化了应用向LLM提供上下文的方式。可以把MCP想象成AI
-> 应用的USB-C端口。正如USB-C提供了一种标准化方式，用于将你的设备连接到各种外设和配件，MCP
-> 也提供了一种标准化方式，用于将AI模型连接到不同的数据源和工具。
+> MCP是一种开放协议，用于标准化应用程序向LLM提供上下文的方式。可以将MCP视为AI
+> 应用程序的USB-C端口。正如USB-C提供了一种将设备连接到各种外围设备和配件的标准化方式，MCP
+> 也提供了一种将AI模型连接到不同数据源和工具的标准化方式。

-Agents Python SDK支持多种MCP传输方式。这使你可以复用现有的MCP服务，或构建自己的服务，向智能体公开由文件系统、HTTP或连接器支持的工具。
+Agents Python SDK支持多种MCP传输方式。这样，你就可以复用现有MCP服务，也可以构建自己的MCP服务，从而向智能体提供由文件系统、HTTP或连接器支持的工具。
+
+!!! warning "连接MCP服务前的信任要求"
+
+    MCP工具可以公开模型上下文中的数据，并使用你提供的凭据执行操作。请仅连接你信任的服务、使用最小权限凭据、将访问令牌放在授权字段或请求头中而非URL中，并要求对敏感操作进行审批。请参阅[OpenAI MCP安全指南](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#risks-and-safety)。

 ## MCP集成方案选择

-在将MCP服务接入智能体之前，请先决定工具调用应在哪里执行，以及你可以访问哪些传输方式。下表总结了Python SDK支持的选项。
+在将MCP服务接入智能体之前，应先确定工具调用的执行位置，以及可访问的传输方式。下表总结了Python SDK支持的选项。

-| 你的需求                                                                        | 推荐选项                                    |
+| 需求                                                                        | 推荐选项                                    |
 | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
-| 让OpenAI的Responses API代表模型调用可公开访问的MCP服务| 通过[`HostedMCPTool`][agents.tool.HostedMCPTool]使用**托管MCP服务工具** |
+| 让OpenAI的Responses API代表模型调用可公开访问的MCP服务| 通过[`HostedMCPTool`][agents.tool.HostedMCPTool]使用**托管式MCP服务工具** |
 | 连接到你在本地或远程运行的Streamable HTTP服务                  | 通过[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]使用**Streamable HTTP MCP服务** |
-| 与实现HTTP with Server-Sent Events的服务通信                          | 通过[`MCPServerSse`][agents.mcp.server.MCPServerSse]使用**HTTP with SSE MCP服务** |
+| 与实现了采用服务端发送事件的HTTP协议的服务通信                          | 通过[`MCPServerSse`][agents.mcp.server.MCPServerSse]使用**采用SSE的HTTP MCP服务** |
 | 启动本地进程并通过stdin/stdout通信                             | 通过[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]使用**stdio MCP服务** |

-下面各节会逐一介绍每个选项、如何配置它，以及何时优先选择某种传输方式。
+以下各节将逐一介绍每个选项、配置方式，以及何时应优先选择某种传输方式。

 ## 智能体级MCP配置

-除了选择传输方式，你还可以通过设置`Agent.mcp_config`来调整MCP工具的准备方式。
+除了选择传输方式外，你还可以通过设置`Agent.mcp_config`来调整MCP工具的准备方式。

 ```python
 from agents import Agent
@@ -48,33 +51,33 @@ agent = Agent(
 )
 ```

-说明：
+注意事项：

- `convert_schemas_to_strict`是尽力而为的。如果某个schema无法转换，则使用原始schema。
- `failure_error_function`控制MCP工具调用失败如何呈现给模型。
- 当未设置`failure_error_function`时，SDK会使用默认的工具错误格式化器。
+- `convert_schemas_to_strict`采用尽力而为的方式。如果某个模式无法转换，则使用原始模式。
+- `failure_error_function`控制如何将MCP工具调用失败呈现给模型。
+- 未设置`failure_error_function`时，SDK会使用默认的工具错误格式化程序。
 - 服务级`failure_error_function`会覆盖该服务的`Agent.mcp_config["failure_error_function"]`。
- `include_server_in_tool_names`是可选启用项。启用后，每个本地MCP工具都会以确定性的、带服务前缀的名称公开给模型，这有助于在多个MCP服务发布同名工具时避免冲突。生成的名称是ASCII安全的，会保持在工具调用名称长度限制内，并避免与同一智能体上的现有本地工具调用和已启用的任务转移名称冲突。SDK仍会在原服务上调用原始的MCP工具名称。
+- `include_server_in_tool_names`需要选择启用。启用后，每个本地MCP工具都会以带有确定性服务前缀的名称提供给模型，有助于避免多个MCP服务发布同名工具时发生冲突。生成的名称符合ASCII安全要求，不会超过工具调用名称的长度限制，并会避开同一智能体中已有的本地工具调用名称和已启用的任务转移名称。SDK仍会在原始服务上调用原始MCP工具名称。

-## 跨传输方式的通用模式
+## 各传输方式的通用模式

 选择传输方式后，大多数集成都需要做出相同的后续决策：

- 如何仅公开工具的一个子集（[工具筛选](#tool-filtering)）。
+- 如何仅公开工具的子集（[工具筛选](#tool-filtering)）。
 - 服务是否还提供可复用的提示词（[提示词](#prompts)）。
 - 是否应缓存`list_tools()`（[缓存](#caching)）。
- MCP活动如何显示在追踪中（[追踪](#tracing)）。
+- MCP活动如何显示在追踪记录中（[追踪](#tracing)）。

-对于本地MCP服务（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`），审批策略和每次调用的`_meta`载荷也是通用概念。Streamable HTTP一节展示了最完整的示例，同样的模式也适用于其他本地传输方式。
+对于本地MCP服务（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`），审批策略和每次调用的`_meta`载荷也是通用概念。Streamable HTTP一节提供了最完整的示例，相同模式也适用于其他本地传输方式。

-## 1. 托管MCP服务工具
+## 1. 托管式MCP服务工具

-托管工具会把整个工具往返过程推送到OpenAI基础设施中执行。你的代码无需列出并调用工具，[`HostedMCPTool`][agents.tool.HostedMCPTool]会将服务标签（以及可选的连接器元数据）转发给Responses API。模型会列出远程服务的工具并调用它们，而无需额外回调到你的Python进程。托管工具目前适用于支持Responses API托管MCP集成的OpenAI模型。
+托管工具会将整个工具往返流程交由OpenAI的基础设施处理。你的代码无需列出和调用工具，[`HostedMCPTool`][agents.tool.HostedMCPTool]会将服务标签（以及可选的连接器元数据）转发给Responses API。模型会列出远程服务的工具并调用它们，无需额外回调你的Python进程。托管工具目前适用于支持Responses API托管式MCP集成的OpenAI模型。

-### 基础托管MCP工具
+### 基础托管式MCP工具

-通过向智能体的`tools`列表添加[`HostedMCPTool`][agents.tool.HostedMCPTool]来创建托管工具。`tool_config`
-字典与发送给REST API的JSON保持一致：
+将[`HostedMCPTool`][agents.tool.HostedMCPTool]添加到智能体的`tools`列表中，即可创建托管工具。`tool_config`
+字典对应于你会发送给REST API的JSON：

 ```python
 import asyncio
@@ -106,14 +109,14 @@ async def main() -> None:
 asyncio.run(main())
 ```

-托管服务会自动公开其工具；你无需将其添加到`mcp_servers`。
+托管式服务会自动公开其工具；无需将其添加到`mcp_servers`。

-如果你希望托管工具搜索延迟加载托管MCP服务，请设置`tool_config["defer_loading"] = True`并将[`ToolSearchTool`][agents.tool.ToolSearchTool]添加到智能体。这仅在OpenAI Responses模型上受支持。有关完整的工具搜索设置和限制，请参阅[工具](tools.md#hosted-tool-search)。
+如果希望托管工具搜索延迟加载托管式MCP服务，请设置`tool_config["defer_loading"] = True`，并将[`ToolSearchTool`][agents.tool.ToolSearchTool]添加到智能体。此功能仅支持OpenAI Responses模型。有关完整的工具搜索设置和限制，请参阅[工具](tools.md#hosted-tool-search)。

-### 托管MCP结果的流式传输
+### 托管式MCP结果的流式传输

-托管工具支持结果流式传输，方式与工具调用完全相同。使用`Runner.run_streamed`在模型仍在工作时
-消费增量MCP输出：
+托管工具对流式结果的支持方式与工具调用完全相同。使用`Runner.run_streamed`可以在模型仍在工作时
+接收增量MCP输出：

 ```python
 result = Runner.run_streamed(agent, "Summarise this repository's top languages")
@@ -125,7 +128,7 @@ print(result.final_output)

 ### 可选审批流程

-如果某个服务可能执行敏感操作，你可以要求每次工具执行前都经过人工或程序化审批。在`tool_config`中使用单一策略（`"always"`、`"never"`）或将工具名称映射到策略的字典来配置`require_approval`。要在Python中做出决定，请提供`on_approval_request`回调。
+如果服务可以执行敏感操作，你可以要求在每次执行工具前进行人工或程序化审批。在`tool_config`中配置`require_approval`，其值可以是单一策略（`"always"`、`"never"`），也可以是将工具名称映射到策略的字典。如需在Python中做出决定，请提供`on_approval_request`回调。

 ```python
 from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest
@@ -153,11 +156,11 @@ agent = Agent(
 )
 ```

-该回调可以是同步或异步的，并会在模型需要审批数据才能继续运行时被调用。
+该回调可以是同步或异步的，并且每当模型需要审批信息才能继续运行时都会被调用。

-### 连接器支持的托管服务
+### 连接器支持的托管式服务

-托管MCP还支持OpenAI连接器。无需指定`server_url`，而是提供`connector_id`和访问令牌。Responses API会处理身份验证，托管服务会公开连接器的工具。
+托管式MCP还支持OpenAI连接器。你无需指定`server_url`，只需提供`connector_id`和访问令牌。Responses API会处理身份验证，托管式服务则会公开连接器的工具。

 ```python
 import os
@@ -173,11 +176,11 @@ HostedMCPTool(
 )
 ```

-完整可运行的托管工具代码示例——包括流式传输、审批和连接器——位于[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)。
+完整可运行的托管工具示例（包括流式传输、审批和连接器）位于[`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)。

 ## 2. Streamable HTTP MCP服务

-当你想自行管理网络连接时，请使用[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你控制传输方式，或希望在自己的基础设施中运行服务并保持低延迟时，Streamable HTTP服务是理想选择。
+如果希望自行管理网络连接，请使用[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]。当你需要控制传输方式，或希望在自己的基础设施中运行服务并保持较低延迟时，Streamable HTTP服务是理想选择。

 ```python
 import asyncio
@@ -212,15 +215,15 @@ async def main() -> None:
 asyncio.run(main())
 ```

-构造函数接受其他选项：
+构造函数还接受以下选项：

 - `client_session_timeout_seconds`控制HTTP读取超时。
- `use_structured_content`控制是否优先使用`tool_result.structured_content`而不是文本输出。
+- `use_structured_content`控制是否优先使用`tool_result.structured_content`而非文本输出。
 - `max_retry_attempts`和`retry_backoff_seconds_base`为`list_tools()`和`call_tool()`添加自动重试。
- `tool_filter`允许你仅公开工具的一个子集（参见[工具筛选](#tool-filtering)）。
- `require_approval`为本地MCP工具启用人在回路审批策略。
- `failure_error_function`自定义模型可见的MCP工具失败消息；将其设置为`None`则改为抛出错误。
- `tool_meta_resolver`会在`call_tool()`之前注入每次调用的MCP`_meta`载荷。
+- `tool_filter`用于仅公开工具的子集（请参阅[工具筛选](#tool-filtering)）。
+- `require_approval`为本地MCP工具启用人工介入审批策略。
+- `failure_error_function`用于自定义模型可见的MCP工具失败消息；将其设置为`None`则改为抛出错误。
+- `tool_meta_resolver`会在`call_tool()`之前注入每次调用的MCP `_meta`载荷。

 ### 本地MCP服务的审批策略

@@ -229,8 +232,8 @@ asyncio.run(main())
 支持的形式：

 - 对所有工具使用`"always"`或`"never"`。
- `True` / `False`（等同于always/never）。
- 按工具的映射，例如`{"delete_file": "always", "read_file": "never"}`。
+- `True` / `False`（分别等同于always/never）。
+- 按工具配置的映射，例如`{"delete_file": "always", "read_file": "never"}`。
 - 分组对象：`{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`。

 ```python
@@ -242,11 +245,11 @@ async with MCPServerStreamableHttp(
    ...
 ```

-有关完整的暂停/恢复流程，请参阅[人在回路](human_in_the_loop.md)和`examples/mcp/get_all_mcp_tools_example/main.py`。
+有关完整的暂停/恢复流程，请参阅[人工介入](human_in_the_loop.md)和`examples/mcp/get_all_mcp_tools_example/main.py`。

 ### 使用`tool_meta_resolver`的每次调用元数据

-当你的MCP服务期望在`_meta`中接收请求元数据（例如租户ID或追踪上下文）时，请使用`tool_meta_resolver`。下面的示例假定你将一个`dict`作为`context`传递给`Runner.run(...)`。
+当MCP服务要求在`_meta`中包含请求元数据（例如租户ID或追踪上下文）时，请使用`tool_meta_resolver`。以下示例假设你将`dict`作为`context`传递给`Runner.run(...)`。

 ```python
 from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext
@@ -267,19 +270,19 @@ server = MCPServerStreamableHttp(
 )
 ```

-如果你的运行上下文是Pydantic模型、dataclass或自定义类，请改用属性访问读取租户ID。
+如果运行上下文是Pydantic模型、数据类或自定义类，请改为通过属性访问读取租户ID。

-### MCP工具输出：文本和图像
+### MCP工具输出：文本与图像

-当MCP工具返回图像内容时，SDK会自动将其映射为图像工具输出条目。混合的文本/图像响应会作为输出项列表转发，因此智能体可以像消费常规工具调用的图像输出一样消费MCP图像结果。
+当MCP工具返回图像内容时，SDK会自动将其映射为图像工具输出条目。混合文本/图像响应会作为输出项列表转发，因此智能体可以像使用普通工具调用产生的图像输出一样使用MCP图像结果。

-## 3. HTTP with SSE MCP服务
+## 3. 采用SSE的HTTP MCP服务

 !!! warning

-    MCP项目已弃用Server-Sent Events传输。对于新的集成，请优先选择Streamable HTTP或stdio；仅为旧服务保留SSE。
+    MCP项目已弃用服务端发送事件传输方式。新集成应优先使用Streamable HTTP或stdio，仅为旧版服务保留SSE。

-如果MCP服务实现了HTTP with SSE传输，请实例化[`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，API与Streamable HTTP服务相同。
+如果MCP服务实现了采用SSE的HTTP传输方式，请实例化[`MCPServerSse`][agents.mcp.server.MCPServerSse]。除传输方式外，其API与Streamable HTTP服务完全相同。

 ```python

@@ -308,7 +311,7 @@ async with MCPServerSse(

 ## 4. stdio MCP服务

-对于作为本地子进程运行的MCP服务，请使用[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK会启动该进程、保持管道打开，并在上下文管理器退出时自动关闭它们。此选项适合快速概念验证，或服务仅公开命令行入口点的情况。
+对于作为本地子进程运行的MCP服务，请使用[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]。SDK会启动进程、保持管道打开，并在退出上下文管理器时自动关闭它们。此选项适用于快速构建概念验证，或服务仅提供命令行入口点的情况。

 ```python
 from pathlib import Path
@@ -336,7 +339,7 @@ async with MCPServerStdio(

 ## 5. MCP服务管理器

-当你有多个MCP服务时，请使用`MCPServerManager`预先连接它们，并向你的智能体公开已连接的子集。有关构造函数选项和重新连接行为，请参阅[MCPServerManager API参考](ref/mcp/manager.md)。
+当你有多个MCP服务时，可使用`MCPServerManager`预先连接它们，并向智能体公开已连接的服务子集。有关构造函数选项和重新连接行为，请参阅[MCPServerManager API参考](ref/mcp/manager.md)。

 ```python
 from agents import Agent, Runner
@@ -360,18 +363,18 @@ async with MCPServerManager(servers) as manager:
 关键行为：

 - 当`drop_failed_servers=True`（默认值）时，`active_servers`仅包含成功连接的服务。
- 失败会记录在`failed_servers`和`errors`中。
- 设置`strict=True`会在首次连接失败时抛出错误。
- 调用`reconnect(failed_only=True)`以重试失败的服务，或调用`reconnect(failed_only=False)`以重启所有服务。
- 使用`connect_timeout_seconds`、`cleanup_timeout_seconds`和`connect_in_parallel`来调整生命周期行为。
+- 失败信息会记录在`failed_servers`和`errors`中。
+- 设置`strict=True`可在第一次连接失败时抛出异常。
+- 调用`reconnect(failed_only=True)`可重试连接失败的服务，调用`reconnect(failed_only=False)`则会重启所有服务。
+- 使用`connect_timeout_seconds`、`cleanup_timeout_seconds`和`connect_in_parallel`调整生命周期行为。

-## 通用服务能力
+## 常见服务能力

-以下各节适用于各种MCP服务传输方式（确切API范围取决于服务类）。
+以下各节适用于各种MCP服务传输方式（确切的API接口取决于服务类）。

 ## 工具筛选

-每个MCP服务都支持工具筛选器，以便你仅公开智能体所需的函数。筛选可以在构造时进行，也可以在每次运行时动态进行。
+每个MCP服务都支持工具筛选，因此你可以仅公开智能体所需的函数。筛选既可以在构造时执行，也可以在每次运行时动态执行。

 ### 静态工具筛选

@@ -397,7 +400,7 @@ filesystem_server = MCPServerStdio(

 ### 动态工具筛选

-对于更复杂的逻辑，请传入一个接收[`ToolFilterContext`][agents.mcp.ToolFilterContext]的可调用对象。该可调用对象可以是同步或异步的；当工具应被公开时返回`True`。
+对于更复杂的逻辑，请传入一个接收[`ToolFilterContext`][agents.mcp.ToolFilterContext]的可调用对象。该可调用对象可以是同步或异步的，并在应公开工具时返回`True`。

 ```python
 from pathlib import Path
@@ -421,15 +424,15 @@ async with MCPServerStdio(
    ...
 ```

-筛选上下文会公开当前活动的`run_context`、请求这些工具的`agent`以及`server_name`。
+筛选上下文会提供当前`run_context`、请求工具的`agent`以及`server_name`。

 ## 提示词

 MCP服务还可以提供用于动态生成智能体指令的提示词。支持提示词的服务会公开两个
 方法：

- `list_prompts()`枚举可用的提示词模板。
- `get_prompt(name, arguments)`获取一个具体提示词，可选带有参数。
+- `list_prompts()`列出可用的提示词模板。
+- `get_prompt(name, arguments)`获取具体提示词，并可选择附带参数。

 ```python
 from agents import Agent
@@ -449,19 +452,19 @@ agent = Agent(

 ## 缓存

-每次智能体运行都会在每个MCP服务上调用`list_tools()`。远程服务可能引入明显延迟，因此所有MCP服务类都公开了`cache_tools_list`选项。仅当你确信工具定义不会频繁变化时，才将其设置为`True`。要在之后强制获取新列表，请在服务实例上调用`invalidate_tools_cache()`。
+每次智能体运行都会在每个MCP服务上调用`list_tools()`。远程服务可能会引入明显延迟，因此所有MCP服务类都提供`cache_tools_list`选项。仅当你确信工具定义不会频繁变化时，才将其设置为`True`。如需之后强制获取最新列表，请在服务实例上调用`invalidate_tools_cache()`。

 ## 追踪

 [追踪](./tracing.md)会自动捕获MCP活动，包括：

-1. 调用MCP服务以列出工具。
-2. 工具调用中的MCP相关信息。
+1. 为列出工具而对MCP服务发起的调用。
+2. 工具调用中与MCP相关的信息。

 ![MCP追踪截图](../assets/images/mcp-tracing.jpg)

 ## 延伸阅读

- [Model Context Protocol](https://modelcontextprotocol.io/) – 规范和设计指南。
- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的stdio、SSE和Streamable HTTP示例代码。
- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 完整的托管MCP演示，包括审批和连接器。
+- [Model Context Protocol](https://modelcontextprotocol.io/) – 规范与设计指南。
+- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 可运行的stdio、SSE和Streamable HTTP代码示例。
+- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 包含审批和连接器的完整托管式MCP演示。
@@ -2,42 +2,42 @@
 search:
  exclude: true
 ---
-# 沙盒客户端
+# 沙箱客户端

-使用本页面选择沙盒任务的运行位置。在大多数情况下，`SandboxAgent` 定义保持不变，仅需在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中更改沙盒客户端和客户端专属选项。
+使用本页选择沙箱任务的运行位置。在大多数情况下，`SandboxAgent` 定义保持不变，只需更改 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中的沙箱客户端及客户端特定选项。

-!!! warning "Beta 测试功能"
+!!! warning "Beta 功能"

-    沙盒智能体目前处于 Beta 测试阶段。在正式发布之前，API 细节、默认值和支持的功能可能会发生变化，未来还将逐步提供更多高级功能。
+    沙箱智能体目前处于 Beta 阶段。在正式发布之前，API 细节、默认值和支持的功能可能会发生变化，未来还将提供更多高级功能。

 ## 决策指南

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 目标 | 首选 | 原因 |
+| 目标 | 首选方案 | 原因 |
 | --- | --- | --- |
-| 在 macOS 或 Linux 上实现最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，便于在本地文件系统上开发。 |
-| 基本的容器隔离 | `DockerSandboxClient` | 使用指定镜像在 Docker 内运行任务。 |
-| 托管执行或生产环境级隔离 | 托管沙盒客户端 | 将工作区边界迁移至由服务提供商管理的环境。 |
+| 在 macOS 或 Linux 上实现最快的本地迭代 | `UnixLocalSandboxClient` | 无需额外安装，便于使用本地文件系统进行开发。 |
+| 基础容器隔离 | `DockerSandboxClient` | 使用指定镜像在 Docker 内运行任务。 |
+| 托管执行或生产环境级隔离 | 托管沙箱客户端 | 将工作区边界迁移到由供应商管理的环境中。 |

 </div>

 ## 本地客户端

-对于大多数用户，建议从以下两个沙盒客户端之一开始：
+对于大多数用户，建议从以下两个沙箱客户端之一开始：

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 客户端 | 安装 | 适用场景 | 代码示例 |
+| 客户端 | 安装 | 适用场景 | 示例 |
 | --- | --- | --- | --- |
-| `UnixLocalSandboxClient` | 无 | 在 macOS 或 Linux 上实现最快的本地迭代。适合作为本地开发的默认选择。 | [Unix 本地入门代码示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
-| `DockerSandboxClient` | `openai-agents[docker]` | 需要容器隔离，或使用指定镜像以确保本地环境的一致性。 | [Docker 入门代码示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |
+| `UnixLocalSandboxClient` | 无 | 需要在 macOS 或 Linux 上实现最快的本地迭代。适合作为本地开发的默认选择。 | [Unix 本地入门示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_runner.py) |
+| `DockerSandboxClient` | `openai-agents[docker]` | 需要容器隔离，或需要使用特定镜像以确保本地环境的一致性。 | [Docker 入门示例](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) |

 </div>

-Unix 本地模式是在本地文件系统上开始开发的最简单方式。当需要更强的环境隔离或与生产环境保持一致时，可以迁移到 Docker 或托管服务提供商。
+Unix 本地模式是基于本地文件系统开始开发的最简便方式。当需要更强的环境隔离或与生产环境保持一致时，请迁移到 Docker 或托管供应商。

-`SandboxPathGrant.host_path` 仅适用于 Docker，用于将主机路径映射到容器内的另一个 POSIX 路径。Unix 本地模式仅支持相同路径的授权。有关详细信息，请参阅[清单路径授权](guide.md#manifest)。
+`SandboxPathGrant.host_path` 仅适用于 Docker，可将主机路径映射到容器内的另一个 POSIX 路径。Unix 本地模式仅支持相同路径的授权。有关详细信息，请参阅[清单路径授权](guide.md#manifest)。

 要从 Unix 本地模式切换到 Docker，请保持智能体定义不变，仅更改运行配置：

@@ -56,74 +56,74 @@ run_config = RunConfig(
 )
 ```

-当需要容器隔离或镜像一致性时，请使用此方式。请参阅 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。
+当需要容器隔离或镜像一致性时，请使用此配置。请参阅 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)。

 ## 挂载与远程存储

-挂载条目用于描述要公开的存储；挂载策略用于描述沙盒后端如何连接该存储。可从 `agents.sandbox.entries` 导入内置挂载条目和通用策略。托管服务提供商的策略可从 `agents.extensions.sandbox` 或服务提供商专属扩展包中获取。
+挂载条目描述要公开的存储；挂载策略描述沙箱后端如何附加该存储。请从 `agents.sandbox.entries` 导入内置挂载条目和通用策略。托管供应商策略可从 `agents.extensions.sandbox` 或供应商特定的扩展包中获取。

 常用挂载选项：

- `mount_path`：存储在沙盒中的显示位置。相对路径基于清单根目录解析；绝对路径则按原样使用。
- `read_only`：默认为 `True`。仅当沙盒需要将内容写回已挂载存储时，才将其设置为 `False`。
- `mount_strategy`：必填。应使用同时兼容挂载条目和沙盒后端的策略。
+- `mount_path`：存储在沙箱中的显示位置。相对路径基于清单根目录解析；绝对路径则按原样使用。
+- `read_only`：默认为 `True`。仅当沙箱需要将数据写回已挂载存储时，才将其设为 `False`。
+- `mount_strategy`：必填。请使用同时与挂载条目和沙箱后端匹配的策略。

 挂载会被视为临时工作区条目。快照和持久化流程会分离或跳过已挂载路径，而不会将已挂载的远程存储复制到保存的工作区中。

-通用本地和容器策略：
+通用本地/容器策略：

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 策略或模式 | 适用场景 | 备注 |
+| 策略或模式 | 适用场景 | 说明 |
 | --- | --- | --- |
-| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 沙盒镜像能够运行 `rclone`。 | 支持 S3、GCS、R2、Azure Blob 和 Box。`RcloneMountPattern` 可以在 `fuse` 模式或 `nfs` 模式下运行。 |
+| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | 沙箱镜像可以运行 `rclone`。 | 支持 S3、GCS、R2、Azure Blob 和 Box。`RcloneMountPattern` 可以在 `fuse` 模式或 `nfs` 模式下运行。 |
 | `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | 镜像包含 `mount-s3`，并且需要以 Mountpoint 方式访问 S3 或 S3 兼容存储。 | 支持 `S3Mount` 和 `GCSMount`。 |
 | `InContainerMountStrategy(pattern=FuseMountPattern(...))` | 镜像包含 `blobfuse2` 并支持 FUSE。 | 支持 `AzureBlobMount`。 |
 | `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | 镜像包含 `mount.s3files`，并且可以访问现有的 S3 Files 挂载目标。 | 支持 `S3FilesMount`。 |
-| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前连接由卷驱动支持的挂载。 | 仅适用于 Docker。S3、GCS、R2、Azure Blob 和 Box 支持 `rclone`；S3 和 GCS 还支持 `mountpoint`。 |
+| `DockerVolumeMountStrategy(driver=...)` | Docker 应在容器启动前附加由卷驱动程序支持的挂载。 | 仅适用于 Docker。S3、GCS、R2、Azure Blob 和 Box 支持 `rclone`；S3 和 GCS 还支持 `mountpoint`。 |

 </div>

 ## 支持的托管平台

-当需要托管环境时，通常可以继续使用相同的 `SandboxAgent` 定义，仅需在 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中更改沙盒客户端。
+当需要托管环境时，通常可以沿用同一个 `SandboxAgent` 定义，只需更改 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] 中的沙箱客户端。

-如果使用已发布的 SDK，而不是此代码仓库的检出版本，请通过对应的软件包额外依赖安装沙盒客户端依赖项。
+如果使用已发布的 SDK，而不是当前仓库的检出版本，请通过匹配的软件包附加项安装沙箱客户端依赖项。

-有关特定服务提供商的设置说明，以及代码仓库中扩展代码示例的链接，请参阅 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。
+有关供应商特定的设置说明及仓库中扩展代码示例的链接，请参阅 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md)。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

-| 客户端 | 安装 | 代码示例 |
+| 客户端 | 安装 | 示例 |
 | --- | --- | --- |
-| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
-| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
-| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) |
-| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) |
-| `ModalSandboxClient` | `openai-agents[modal]` | [Modal 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) |
-| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) |
-| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel 运行器](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
+| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
+| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
+| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) |
+| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) |
+| `ModalSandboxClient` | `openai-agents[modal]` | [Modal 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) |
+| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) |
+| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel 运行程序](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |

 </div>

-托管沙盒客户端会提供服务提供商专属的挂载策略。请选择最适合相应存储服务提供商的后端和挂载策略：
+托管沙箱客户端提供供应商特定的挂载策略。请选择最适合存储供应商的后端和挂载策略：

 <div class="sandbox-nowrap-first-column-table" markdown="1">

 | 后端 | 挂载说明 |
 | --- | --- |
-| Docker | 支持通过 `InContainerMountStrategy` 和 `DockerVolumeMountStrategy` 等本地策略挂载 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` 和 `S3FilesMount`。 |
-| `ModalSandboxClient` | 支持通过 `ModalCloudBucketMountStrategy`，在 `S3Mount`、`R2Mount` 和使用 HMAC 身份验证的 `GCSMount` 上挂载 Modal 云存储桶。可以使用内联凭据或具名 Modal Secret。 |
-| `CloudflareSandboxClient` | 支持通过 `CloudflareBucketMountStrategy`，在 `S3Mount`、`R2Mount` 和使用 HMAC 身份验证的 `GCSMount` 上挂载 Cloudflare 存储桶。 |
+| Docker | 支持将 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` 和 `S3FilesMount` 与 `InContainerMountStrategy`、`DockerVolumeMountStrategy` 等本地策略配合使用。 |
+| `ModalSandboxClient` | 支持通过 `ModalCloudBucketMountStrategy`，在 `S3Mount`、`R2Mount` 和采用 HMAC 身份验证的 `GCSMount` 上挂载 Modal 云存储桶。可以使用内联凭据或具名 Modal Secret。 |
+| `CloudflareSandboxClient` | 支持通过 `CloudflareBucketMountStrategy`，在 `S3Mount`、`R2Mount` 和采用 HMAC 身份验证的 `GCSMount` 上挂载 Cloudflare 存储桶。 |
 | `BlaxelSandboxClient` | 支持通过 `BlaxelCloudBucketMountStrategy`，在 `S3Mount`、`R2Mount` 和 `GCSMount` 上挂载云存储桶。还支持使用 `agents.extensions.sandbox.blaxel` 中的 `BlaxelDriveMount` 和 `BlaxelDriveMountStrategy` 挂载持久化 Blaxel Drive。 |
 | `DaytonaSandboxClient` | 支持通过 `DaytonaCloudBucketMountStrategy` 挂载由 rclone 支持的云存储；可将其与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 配合使用。 |
 | `E2BSandboxClient` | 支持通过 `E2BCloudBucketMountStrategy` 挂载由 rclone 支持的云存储；可将其与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 配合使用。 |
 | `RunloopSandboxClient` | 支持通过 `RunloopCloudBucketMountStrategy` 挂载由 rclone 支持的云存储；可将其与 `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount` 和 `BoxMount` 配合使用。 |
-| `VercelSandboxClient` | 支持通过 `VercelCloudBucketMountStrategy`，在 `S3Mount` 上挂载仅能在创建时配置的 S3 和 S3 兼容存储桶；已挂载存储的会话无法恢复，并且使用内联凭据时必须设置 `allow_s3_credential_exposure=True`。 |
+| `VercelSandboxClient` | 支持通过 `VercelCloudBucketMountStrategy`，在 `S3Mount` 上挂载仅能在创建时指定的 S3 和 S3 兼容存储桶；已挂载的会话无法恢复，并且使用内联凭据时需要设置 `allow_s3_credential_exposure=True`。 |

 </div>

-下表汇总了每个后端可以直接挂载的远程存储条目。
+下表汇总了各后端可以直接挂载的远程存储条目。

 <div class="sandbox-nowrap-first-column-table" markdown="1">

@@ -140,4 +140,4 @@ run_config = RunConfig(

 </div>

-如需更多可运行的代码示例，请浏览 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)，了解本地运行、编码、记忆、任务转移和智能体组合模式；还可浏览 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)，查看托管沙盒客户端。
+如需更多可运行的代码示例，请浏览 [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox)，其中包含本地、编码、记忆、任务转移和智能体组合模式；托管沙箱客户端的代码示例请参阅 [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions)。
@@ -4,13 +4,13 @@ search:
 ---
 # 会话

-Agents SDK 提供内置会话记忆，用于在多次智能体运行之间自动维护对话历史记录，从而无需在各轮之间手动处理 `.to_input_list()`。
+Agents SDK提供内置会话记忆，可在多次智能体运行之间自动维护对话历史，无需在轮次之间手动处理 `.to_input_list()`。

-会话会存储特定会话的对话历史记录，使智能体能够维护上下文，而无需显式的手动记忆管理。这对于构建聊天应用或多轮对话尤其有用，因为你希望智能体记住之前的交互。
+会话会存储特定会话的对话历史，使智能体无需显式的手动记忆管理即可维护上下文。这对于构建聊天应用或多轮对话尤其有用，因为你希望智能体记住之前的交互。

-当你希望 SDK 为你管理客户端侧记忆时，请使用会话。会话不能在同一次运行中与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 结合使用。如果你希望改用由 OpenAI 服务端管理的延续机制，请选择其中一种机制，而不是在其上叠加会话。
+当你希望 SDK 为你管理客户端侧记忆时，请使用会话。在同一次运行中，会话不能与 `conversation_id`、`previous_response_id` 或 `auto_previous_response_id` 结合使用。如果希望改用由OpenAI服务管理的延续机制，请选择其中一种机制，而不是在其上叠加会话。

-## 快速开始
+## 快速入门

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -51,7 +51,7 @@ print(result.final_output)  # "Approximately 39 million"

 ## 使用同一会话恢复中断的运行

-如果某次运行因等待批准而暂停，请使用同一个会话实例（或另一个指向同一后端存储的会话实例）来恢复它，以便恢复后的轮次继续使用同一份已存储的对话历史记录。
+如果运行因等待批准而暂停，请使用同一会话实例（或指向同一底层存储的另一个会话实例）恢复运行，以便恢复后的轮次继续使用同一份已存储对话历史。

 ```python
 result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -63,31 +63,31 @@ if result.interruptions:
    result = await Runner.run(agent, state, session=session)
 ```

-## 核心会话行为
+## 会话的核心行为

 启用会话记忆后：

-1. **每次运行之前**：运行器会自动检索该会话的对话历史记录，并将其前置到输入项中。
-2. **每次运行之后**：运行期间生成的所有新项（用户输入、助手响应、工具调用等）都会自动存储到会话中。
-3. **上下文保留**：同一会话的每次后续运行都会包含完整的对话历史记录，使智能体能够维护上下文。
+1. **每次运行前**：运行器会自动检索该会话的对话历史，并将其添加到输入条目之前。
+2. **每次运行后**：运行期间生成的所有新条目（用户输入、助手响应、工具调用等）都会自动存储到会话中。
+3. **上下文保留**：之后每次使用同一会话运行时，都会包含完整的对话历史，使智能体能够维护上下文。

-这消除了手动调用 `.to_input_list()` 并在运行之间管理对话状态的需要。
+这样便无需手动调用 `.to_input_list()`，也无需在运行之间管理对话状态。

 ## 历史记录与新输入的合并控制

-当你传入会话时，运行器通常会按如下方式准备模型输入：
+传入会话时，运行器通常会按以下顺序准备模型输入：

-1. 会话历史记录（从 `session.get_items(...)` 检索）
+1. 会话历史（从 `session.get_items(...)` 检索）
 2. 新轮次输入

-使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 在模型调用之前自定义该合并步骤。回调会接收两个列表：
+使用 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 可在调用模型之前自定义该合并步骤。回调会接收两个列表：

-   `history`：检索到的会话历史记录（已规范化为输入项格式）
-   `new_input`：当前轮次的新输入项
+-   `history`：检索到的会话历史（已规范化为输入条目格式）
+-   `new_input`：当前轮次的新输入条目

-返回应发送给模型的最终输入项列表。
+返回应发送给模型的最终输入条目列表。

-回调接收的是这两个列表的副本，因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入，但 SDK 仍然只会持久化属于新轮次的项。因此，对旧历史记录重新排序或过滤，并不会导致旧会话项被再次作为新输入保存。
+回调接收的是两个列表的副本，因此你可以安全地修改它们。返回的列表会控制该轮次的模型输入，但 SDK 仍只持久化属于新轮次的条目。因此，对旧历史记录进行重新排序或筛选，不会导致旧会话条目被再次保存为新输入。

 ```python
 from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -109,16 +109,16 @@ result = await Runner.run(
 )
 ```

-当你需要自定义裁剪、重新排序或选择性纳入历史记录，同时不改变会话存储项的方式时，请使用此功能。如果你需要在模型调用前立即进行更靠后的最终处理步骤，请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。
+当你需要自定义历史记录的裁剪、重新排序或选择性纳入方式，同时又不改变会话存储条目的方式时，请使用此功能。如果需要在模型调用前立即执行后续的最终处理，请使用[运行智能体指南](../running_agents.md)中的 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]。

-## 检索历史记录的限制
+## 历史记录检索限制

-使用 [`SessionSettings`][agents.memory.SessionSettings] 控制每次运行前获取多少历史记录。
+使用 [`SessionSettings`][agents.memory.SessionSettings] 控制每次运行前获取的历史记录量。

-   `SessionSettings(limit=None)`（默认）：检索所有可用的会话项
-   `SessionSettings(limit=N)`：仅检索最近的 `N` 个项
+-   `SessionSettings(limit=None)`（默认）：检索所有可用的会话条目
+-   `SessionSettings(limit=N)`：仅检索最近的 `N` 个条目

-你可以通过 [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 按运行应用此设置：
+可以通过 [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 将此设置应用于单次运行：

 ```python
 from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
@@ -134,13 +134,13 @@ result = await Runner.run(
 )
 ```

-如果你的会话实现公开了默认会话设置，`RunConfig.session_settings` 会为该次运行覆盖任何非 `None` 的值。这对于长对话很有用：你可以在不改变会话默认行为的情况下限制检索大小。
+如果会话实现提供默认会话设置，`RunConfig.session_settings` 会在该次运行中覆盖所有非 `None` 值。这对于长对话非常有用，可以限制检索量而无需更改会话的默认行为。

 ## 记忆操作

 ### 基本操作

-会话支持用于管理对话历史记录的多种操作：
+会话支持多种对话历史管理操作：

 ```python
 from agents import SQLiteSession
@@ -167,7 +167,7 @@ await session.clear_session()

 ### 使用 pop_item 进行修正

-当你想撤销或修改对话中的最后一项时，`pop_item` 方法尤其有用：
+当你想撤销或修改对话中的最后一个条目时，`pop_item` 方法尤其有用：

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -198,32 +198,32 @@ print(f"Agent: {result.final_output}")

 ## 内置会话实现

-SDK 为不同用例提供了多个会话实现：
+SDK 针对不同使用场景提供了多种会话实现：

 ### 内置会话实现的选择

-在阅读下方详细示例之前，使用此表选择一个起点。
+阅读下方详细示例之前，可使用此表选择起点。

-| 会话类型 | 适用场景 | 备注 |
+| 会话类型 | 最适用场景 | 说明 |
 | --- | --- | --- |
-| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，可基于文件或内存 |
-| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 支持异步驱动的扩展后端 |
-| `RedisSession` | 跨多个工作进程/服务的共享记忆 | 适合低延迟分布式部署 |
+| `SQLiteSession` | 本地开发和简单应用 | 内置、轻量，可由文件支持或在内存中运行 |
+| `AsyncSQLiteSession` | 使用 `aiosqlite` 的异步 SQLite | 支持异步驱动程序的扩展后端 |
+| `RedisSession` | 跨工作进程或服务共享记忆 | 适合低延迟分布式部署 |
 | `SQLAlchemySession` | 使用现有数据库的生产应用 | 适用于 SQLAlchemy 支持的数据库 |
-| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo；通过原子序列计数器保证顺序 |
-| `DaprSession` | 带有 Dapr sidecar 的云原生部署 | 支持多种状态存储，以及 TTL 和一致性控制 |
-| `OpenAIConversationsSession` | OpenAI 中由服务端管理的存储 | 基于 OpenAI Conversations API 的历史记录 |
-| `OpenAIResponsesCompactionSession` | 带有自动压缩的长对话 | 另一个会话后端的包装器 |
-| `AdvancedSQLiteSession` | SQLite 加分支/分析 | 功能集较重；请参阅专门页面 |
-| `EncryptedSession` | 基于另一个会话的加密 + TTL | 包装器；请先选择底层后端 |
+| `MongoDBSession` | 已使用 MongoDB 或需要多进程存储的应用 | 异步 pymongo；使用原子序列计数器保持顺序 |
+| `DaprSession` | 使用 Dapr sidecar 的云原生部署 | 支持多种状态存储，以及 TTL 和一致性控制 |
+| `OpenAIConversationsSession` | 由OpenAI服务管理的存储 | 由OpenAI Conversations API 支持的历史记录 |
+| `OpenAIResponsesCompactionSession` | 需要自动压缩的长对话 | 对另一种会话后端的封装 |
+| `AdvancedSQLiteSession` | 支持分支和分析的 SQLite | 功能集更丰富；请参阅专门页面 |
+| `EncryptedSession` | 在另一会话之上提供加密和 TTL | 封装器；请先选择底层后端 |

-一些实现有包含更多详细信息的专门页面；这些页面已在其小节中以内联链接形式给出。
+某些实现拥有提供更多详细信息的专门页面；其链接位于对应小节中。

-如果你正在为 ChatKit 实现 Python 服务，请使用 `chatkit.store.Store` 实现来持久化 ChatKit 的线程和项。Agents SDK 会话（如 `SQLAlchemySession`）会管理 SDK 侧的对话历史记录，但它们不能直接替代 ChatKit 的 store。请参阅 [`chatkit-python` 关于实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。
+如果你正在为 ChatKit 实现 Python 服务，请使用 `chatkit.store.Store` 实现来持久化 ChatKit 的线程和条目。`SQLAlchemySession` 等 Agents SDK会话用于管理 SDK 侧的对话历史，但不能直接替代 ChatKit 的存储。请参阅 [`chatkit-python` 中有关实现 ChatKit 数据存储的指南](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)。

 ### OpenAI Conversations API 会话

-通过 `OpenAIConversationsSession` 使用 [OpenAI 的 Conversations API](https://platform.openai.com/docs/api-reference/conversations)。
+通过 `OpenAIConversationsSession` 使用 [OpenAI的 Conversations API](https://platform.openai.com/docs/api-reference/conversations)。

 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -259,7 +259,7 @@ print(result.final_output)  # "California"

 ### OpenAI Responses 压缩会话

-使用 `OpenAIResponsesCompactionSession` 通过 Responses API（`responses.compact`）压缩已存储的对话历史记录。它会包装一个底层会话，并可根据 `should_trigger_compaction` 在每轮之后自动压缩。不要用它包装 `OpenAIConversationsSession`；这两个功能以不同方式管理历史记录。
+使用 `OpenAIResponsesCompactionSession` 通过 Responses API（`responses.compact`）压缩已存储的对话历史。它会封装一个底层会话，并可根据 `should_trigger_compaction` 在每个轮次后自动执行压缩。不要用它封装 `OpenAIConversationsSession`；这两项功能管理历史记录的方式不同。

 #### 典型用法（自动压缩）

@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```

-默认情况下，一旦达到候选阈值，压缩会在每轮之后运行。
+默认情况下，一旦达到候选阈值，每个轮次后都会执行压缩。

-当你已经使用 Responses API 响应 ID 串联各轮时，`compaction_mode="previous_response_id"` 效果最好。`compaction_mode="input"` 则会基于当前会话项重建压缩请求，这在响应链不可用，或你希望以会话内容作为事实来源时很有用。默认的 `"auto"` 会选择可用的最安全选项。
+当你已经使用 Responses API 响应 ID 串联各轮次时，`compaction_mode="previous_response_id"` 效果最佳。`compaction_mode="input"` 则根据当前会话条目重新构建压缩请求，适用于响应链不可用，或你希望将会话内容作为权威数据源的情况。默认值 `"auto"` 会选择最安全的可用选项。

-如果你的智能体使用 `ModelSettings(store=False)` 运行，Responses API 不会保留最后一个响应以供之后查找。在这种无状态设置中，默认的 `"auto"` 模式会退回到基于输入的压缩，而不是依赖 `previous_response_id`。有关完整示例，请参阅 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。
+如果智能体使用 `ModelSettings(store=False)` 运行，Responses API 不会保留最后一次响应供后续查询。在这种无状态配置中，默认的 `"auto"` 模式会改用基于输入的压缩，而不依赖 `previous_response_id`。完整示例请参阅 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)。

-#### 自动压缩对流式传输的阻塞
+#### 自动压缩造成的流式传输阻塞

-压缩会清空并重写会话历史记录，因此 SDK 会等待压缩完成后才将该运行视为完成。在流式传输模式下，这意味着如果压缩开销较大，在最后一个输出 token 之后，`run.stream_events()` 可能仍会保持打开数秒。
+压缩会清除并重写会话历史，因此 SDK 会等待压缩完成后，才将运行视为已完成。在流式传输模式下，如果压缩负载较重，这意味着最后一个输出 token 生成后，`run.stream_events()` 可能还会保持打开数秒。

-如果你希望低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲期间）自行调用 `run_compaction()`。你可以根据自己的标准决定何时强制压缩。
+如果你需要低延迟流式传输或快速轮次切换，请禁用自动压缩，并在轮次之间（或空闲时）自行调用 `run_compaction()`。你可以根据自己的条件决定何时强制执行压缩。

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -332,7 +332,7 @@ result = await Runner.run(

 ### 异步 SQLite 会话

-当你希望使用由 `aiosqlite` 支持的 SQLite 持久化时，请使用 `AsyncSQLiteSession`。
+如果希望使用由 `aiosqlite` 支持的 SQLite 持久化，请使用 `AsyncSQLiteSession`。

 ```bash
 pip install aiosqlite
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)

 ### Redis 会话

-使用 `RedisSession` 在多个工作进程或服务之间共享会话记忆。
+使用 `RedisSession` 可在多个工作进程或服务之间共享会话记忆。

 ```bash
 pip install openai-agents[redis]
@@ -365,11 +365,14 @@ session = RedisSession.from_url(
    url="redis://localhost:6379/0",
 )
 result = await Runner.run(agent, "Hello", session=session)
+await session.close()
 ```

+`from_url(...)` 会创建并拥有 Redis 客户端。调用 `close()` 后，会话将进入终止状态，后续会话操作会引发 `RuntimeError`；重复或并发调用 `close()` 是安全的。如果应用已管理 Redis 客户端，请直接构造 `RedisSession(...)` 并传入 `redis_client=...`。在这种情况下，`close()` 不执行任何操作，调用方仍拥有客户端所有权，会话也仍可使用。
+
 ### SQLAlchemy 会话

-使用任何 SQLAlchemy 支持的数据库实现的生产就绪型 Agents SDK 会话持久化：
+使用任何 SQLAlchemy 支持的数据库，为 Agents SDK提供可用于生产环境的会话持久化：

 ```python
 from agents.extensions.memory import SQLAlchemySession
@@ -387,11 +390,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
 session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 ```

-请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)了解详细文档。
+详细文档请参阅 [SQLAlchemy 会话](sqlalchemy_session.md)。

 ### Dapr 会话

-当你已经运行 Dapr sidecar，或希望在不更改智能体代码的情况下，让会话存储能够在不同状态存储后端之间迁移时，请使用 `DaprSession`。
+如果你已运行 Dapr sidecar，或希望在不更改智能体代码的情况下，让会话存储可在不同状态存储后端之间迁移，请使用 `DaprSession`。

 ```bash
 pip install openai-agents[dapr]
@@ -412,18 +415,19 @@ async with DaprSession.from_address(
    print(result.final_output)
 ```

-备注：
+注意：

-   `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果你的应用已经管理了一个客户端，请直接使用 `dapr_client=...` 构造 `DaprSession(...)`。
-   当底层状态存储支持 TTL 时，传入 `ttl=...` 可让它自动使旧会话数据过期。
-   当你需要更强的写后读保证时，传入 `consistency=DAPR_CONSISTENCY_STRONG`。
-   Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中，启动 Dapr 时除了 `dapr_address` 中使用的 gRPC 端口外，还应使用 `--dapr-http-port 3500`。
-   请参阅 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)获取完整设置演练，包括本地组件和故障排查。
+-   `from_address(...)` 会为你创建并拥有 Dapr 客户端。如果应用已管理客户端，请直接构造 `DaprSession(...)` 并传入 `dapr_client=...`。
+-   退出上下文或调用 `close()` 会使拥有客户端的会话进入终止状态；后续会话操作会引发 `RuntimeError`，但重复或并发调用 `close()` 是安全的。使用注入的客户端时，`close()` 不执行任何操作，会话仍可使用。
+-   当底层状态存储支持 TTL 时，传入 `ttl=...` 可让其自动使旧会话数据过期。
+-   当需要更强的写后读保证时，传入 `consistency=DAPR_CONSISTENCY_STRONG`。
+-   Dapr Python SDK 还会检查 HTTP sidecar 端点。在本地开发中，除了 `dapr_address` 使用的 gRPC 端口之外，还应使用 `--dapr-http-port 3500` 启动 Dapr。
+-   完整的设置演练（包括本地组件和故障排除）请参阅 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)。


 ### MongoDB 会话

-对于已使用 MongoDB 或需要可水平扩展的多进程会话存储的应用，请使用 `MongoDBSession`。
+对于已使用 MongoDB，或需要可横向扩展的多进程会话存储的应用，请使用 `MongoDBSession`。

 ```bash
 pip install openai-agents[mongodb]
@@ -446,12 +450,12 @@ print(result.final_output)
 await session.close()
 ```

-备注：
+注意：

-   `from_uri(...)` 会创建并拥有 `AsyncMongoClient`，并在 `session.close()` 时关闭它。如果你的应用已经管理了一个客户端，请直接使用 `client=...` 构造 `MongoDBSession(...)`；在这种情况下，`session.close()` 不执行任何操作，生命周期由调用方管理。
-   通过向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI，即可连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)，无需其他更改。
-   会使用两个集合，且二者名称都可通过 `sessions_collection=`（默认 `agent_sessions`）和 `messages_collection=`（默认 `agent_messages`）配置。首次使用时会自动创建索引。每个消息文档都带有一个单调递增的 `seq` 计数器，可在并发写入者和进程之间保持顺序。
-   在首次运行之前，使用 `await session.ping()` 验证连接性。
+-   `from_uri(...)` 会创建并拥有 `AsyncMongoClient`，并在调用 `session.close()` 时将其关闭。如果应用已管理客户端，请直接构造 `MongoDBSession(...)` 并传入 `client=...`；在这种情况下，`session.close()` 不执行任何操作，生命周期仍由调用方管理。
+-   若要连接到 [MongoDB Atlas](https://www.mongodb.com/products/platform)，只需向 `from_uri(...)` 传入 `mongodb+srv://user:password@cluster.example.mongodb.net` URI，无需进行其他更改。
+-   系统会使用两个集合，二者的名称均可配置：通过 `sessions_collection=` 配置会话集合（默认值为 `agent_sessions`），通过 `messages_collection=` 配置消息集合（默认值为 `agent_messages`）。首次使用时会自动创建索引。每个消息文档都包含一个单调递增的 `seq` 计数器，可在并发写入方和进程之间保持顺序。
+-   在首次运行前，使用 `await session.ping()` 验证连接。

 ### 高级 SQLite 会话

@@ -475,11 +479,11 @@ await session.store_run_usage(result)  # Track token usage
 await session.create_branch_from_turn(2)  # Branch from turn 2
 ```

-请参阅 [高级 SQLite 会话](advanced_sqlite_session.md)了解详细文档。
+详细文档请参阅[高级 SQLite 会话](advanced_sqlite_session.md)。

 ### 加密会话

-用于任何会话实现的透明加密包装器：
+适用于任何会话实现的透明加密封装器：

 ```python
 from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -502,17 +506,17 @@ session = EncryptedSession(
 result = await Runner.run(agent, "Hello", session=session)
 ```

-请参阅 [加密会话](encrypted_session.md)了解详细文档。
+详细文档请参阅[加密会话](encrypted_session.md)。

 ### 其他会话类型

-还有一些其他内置选项。请参阅 `examples/memory/` 以及 `extensions/memory/` 下的源代码。
+此外还有一些内置选项。请参阅 `examples/memory/` 以及 `extensions/memory/` 下的源代码。

-## 操作模式
+## 运维模式

 ### 会话 ID 命名

-使用有意义的会话 ID 来帮助你组织对话：
+使用有意义的会话 ID 以便组织对话：

 -   基于用户：`"user_12345"`
 -   基于线程：`"thread_abc123"`
@@ -520,18 +524,18 @@ result = await Runner.run(agent, "Hello", session=session)

 ### 记忆持久化

-   使用内存 SQLite（`SQLiteSession("session_id")`）处理临时对话
-   使用基于文件的 SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）处理持久对话
-   当你需要基于 `aiosqlite` 的实现时，使用异步 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）
-   使用基于 Redis 的会话（`RedisSession.from_url("session_id", url="redis://...")`）实现共享的低延迟会话记忆
-   对于使用 SQLAlchemy 支持的现有数据库的生产系统，使用基于 SQLAlchemy 的会话（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）
-   对于已使用 MongoDB 或需要多进程、可水平扩展会话存储的应用，使用 MongoDB 会话（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）
-   对于支持 30+ 数据库后端，并内置遥测、追踪和数据隔离的生产级云原生部署，使用 Dapr 状态存储会话（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）
-   当你希望将历史记录存储在 OpenAI Conversations API 中时，使用 OpenAI 托管存储（`OpenAIConversationsSession()`）
-   使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任何会话包装透明加密和基于 TTL 的过期机制
-   对于更高级的用例，可以考虑为其他生产系统（例如 Django）实现自定义会话后端
+-   对于临时对话，使用内存 SQLite（`SQLiteSession("session_id")`）
+-   对于持久化对话，使用基于文件的 SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）
+-   当需要基于 `aiosqlite` 的实现时，使用异步 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）
+-   对于共享的低延迟会话记忆，使用 Redis 支持的会话（`RedisSession.from_url("session_id", url="redis://...")`）
+-   对于拥有 SQLAlchemy 所支持现有数据库的生产系统，使用基于 SQLAlchemy 的会话（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）
+-   对于已使用 MongoDB，或需要多进程、可横向扩展会话存储的应用，使用 MongoDB 会话（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）
+-   对于生产环境中的云原生部署，使用 Dapr 状态存储会话（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`），它支持 30 多种数据库后端，并内置遥测、追踪和数据隔离功能
+-   如果希望将历史记录存储在 OpenAI Conversations API 中，请使用 OpenAI托管的存储（`OpenAIConversationsSession()`）
+-   使用加密会话（`EncryptedSession(session_id, underlying_session, encryption_key)`）为任意会话提供透明加密和基于 TTL 的过期机制
+-   对于更高级的使用场景，可以考虑为其他生产系统（例如 Django）实现自定义会话后端

-### 多个会话
+### 多会话

 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -577,7 +581,7 @@ result2 = await Runner.run(

 ## 完整示例

-下面是展示会话记忆实际效果的完整示例：
+以下完整示例展示了会话记忆的实际运作方式：

 ```python
 import asyncio
@@ -641,7 +645,7 @@ if __name__ == "__main__":

 ## 自定义会话实现

-你可以创建一个遵循 [`Session`][agents.memory.session.Session] 协议的类来实现自己的会话记忆：
+你可以创建遵循 [`Session`][agents.memory.session.Session] 协议的类，实现自己的会话记忆：

 ```python
 from agents.memory.session import SessionABC
@@ -686,26 +690,26 @@ result = await Runner.run(

 ## 社区会话实现

-社区已开发出其他会话实现：
+社区开发了其他会话实现：

-| 包 | 描述 |
+| 软件包 | 描述 |
 |---------|-------------|
-| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 基于 Django ORM 的会话，适用于任何 Django 支持的数据库（PostgreSQL、MySQL、SQLite 等） |
+| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 适用于任何 Django 支持的数据库（PostgreSQL、MySQL、SQLite 等）的基于 Django ORM 的会话 |

-如果你构建了一个会话实现，欢迎提交文档 PR，将它添加到这里！
+如果你构建了会话实现，欢迎提交文档 PR，将其添加到此处！

 ## API 参考

-有关详细 API 文档，请参阅：
+详细 API 文档请参阅：

 -   [`Session`][agents.memory.session.Session] - 协议接口
 -   [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 实现
-   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 压缩包装器
+-   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 压缩封装器
 -   [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基础 SQLite 实现
 -   [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - 基于 `aiosqlite` 的异步 SQLite 实现
-   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - 基于 Redis 的会话实现
+-   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 支持的会话实现
 -   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 基于 SQLAlchemy 的实现
-   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - 基于 MongoDB 的会话实现
+-   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 支持的会话实现
 -   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状态存储实现
 -   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 支持分支和分析的增强型 SQLite
-   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 用于任何会话的加密包装器
+-   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 适用于任意会话的加密封装器
@@ -4,43 +4,43 @@ search:
 ---
 # 工具

-工具让智能体能够执行操作：例如获取数据、运行代码、调用外部 API，甚至使用计算机。SDK 支持五个目录：
+工具让智能体能够执行操作，例如获取数据、运行代码、调用外部 API，甚至操作计算机。SDK 支持五个目录：

-   由OpenAI托管的工具：与模型一起在OpenAI服务上运行。
+-   由OpenAI托管的工具：与模型一同在OpenAI服务上运行。
 -   本地/运行时执行工具：`ComputerTool` 和 `ApplyPatchTool` 始终在你的环境中运行，而 `ShellTool` 可以在本地或托管容器中运行。
-   Function calling：将任意 Python 函数封装为工具。
+-   Function Calling：将任意 Python 函数封装为工具。
 -   Agents as tools：将智能体公开为可调用工具，而无需完整的任务转移。
-   实验性 Codex 工具：通过工具调用运行限定于工作区的 Codex 任务。
+-   实验性功能：Codex 工具：通过工具调用运行限定于工作区的 Codex 任务。

 ## 工具类型选择

-将本页面用作目录，然后跳转到与你所控制运行时相匹配的章节。
+可将本页面作为目录，然后跳转到与你所控制的运行时相匹配的部分。

 | 如果你想要…… | 从这里开始 |
 | --- | --- |
-| 使用由OpenAI管理的工具（网络检索、文件检索、Code Interpreter、托管MCP、图像生成） | [托管工具](#hosted-tools) |
-| 使用工具搜索将大型工具集合推迟到运行时加载 | [托管工具搜索](#hosted-tool-search) |
-| 通过生成的 JavaScript 协调多个工具调用 | [编程式工具调用](#programmatic-tool-calling) |
-| 在自己的进程或环境中运行工具 | [本地运行时工具](#local-runtime-tools) |
+| 使用由OpenAI管理的工具（网络检索、文件检索、Code Interpreter、托管 MCP、图像生成） | [托管工具](#hosted-tools) |
+| 通过工具搜索将大型工具集延迟到运行时加载 | [托管工具搜索](#hosted-tool-search) |
+| 通过生成的 JavaScript 协调多个工具调用 | [程序化工具调用](#programmatic-tool-calling) |
+| 在你自己的进程或环境中运行工具 | [本地运行时工具](#local-runtime-tools) |
 | 将 Python 函数封装为工具 | [工具调用](#function-tools) |
 | 让一个智能体在不进行任务转移的情况下调用另一个智能体 | [Agents as tools](#agents-as-tools) |
-| 从智能体运行限定于工作区的 Codex 任务 | [实验性 Codex 工具](#experimental-codex-tool) |
+| 从智能体运行限定于工作区的 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服务。
-   [`ProgrammaticToolCallingTool`][agents.tool.ProgrammaticToolCallingTool] 让模型能够通过生成的 JavaScript 协调符合条件的工具。
+-   [`ToolSearchTool`][agents.tool.ToolSearchTool] 允许模型按需加载延迟加载的工具、命名空间或托管 MCP 服务。
+-   [`ProgrammaticToolCallingTool`][agents.tool.ProgrammaticToolCallingTool] 允许模型通过生成的 JavaScript 协调符合条件的工具。

 高级托管搜索选项：

-   除了 `vector_store_ids` 和 `max_num_results`，`FileSearchTool` 还支持 `filters`、`ranking_options` 和 `include_search_results`。
+-   除 `vector_store_ids` 和 `max_num_results` 外，`FileSearchTool` 还支持 `filters`、`ranking_options` 和 `include_search_results`。
 -   `WebSearchTool` 支持 `filters`、`user_location` 和 `search_context_size`。

 ```python
@@ -64,9 +64,9 @@ async def main():

 ### 托管工具搜索

-工具搜索让 OpenAI Responses 模型能够将大型工具集合推迟到运行时加载，使模型仅加载当前轮次所需的子集。当你有大量工具调用、命名空间组或托管MCP服务，并且希望在不预先公开每个工具的情况下减少工具架构所占的 token 时，这非常有用。
+工具搜索允许 OpenAI Responses 模型将大型工具集延迟到运行时加载，使模型仅加载当前轮次所需的工具子集。当你拥有大量工具调用、命名空间组或托管 MCP 服务，并希望在不预先公开所有工具的情况下减少工具模式所占用的 token 时，此功能非常有用。

-如果候选工具在构建智能体时已经确定，请优先使用托管工具搜索。如果你的应用需要动态决定加载哪些内容，Responses API 也支持由客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。
+如果构建智能体时已经知道候选工具，请从托管工具搜索开始。如果你的应用需要动态决定加载哪些内容，Responses API 也支持由客户端执行的工具搜索，但标准 `Runner` 不会自动执行该模式。

 ```python
 from typing import Annotated
@@ -111,26 +111,26 @@ 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})`。
+-   托管工具搜索仅适用于 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`。
+-   `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)。

-### 编程式工具调用
+### 程序化工具调用

-编程式工具调用让受支持的 OpenAI Responses 模型能够生成 JavaScript，以调用符合条件的工具、组合其输出，并向模型返回一个结果。它适用于范围明确的工作流，这些工作流可受益于循环、分支、并行调用或中间计算，而无需在每次工具调用后都与模型往返交互。
+程序化工具调用允许受支持的 OpenAI Responses 模型生成 JavaScript，以调用符合条件的工具、组合其输出，并向模型返回一个结果。它适用于边界明确的工作流，这些工作流能够受益于循环、分支、并行调用或中间计算，并且不需要在每次工具调用后都与模型往返交互。

-生成的程序在全新的托管 V8 环境中运行。它不具备 Node.js API、文件系统或网络访问权限，也不是持久进程。该程序只能与明确允许的工具交互。
+生成的程序在全新的托管 V8 环境中运行。它无法使用 Node.js API，不能访问文件系统或网络，也没有持久化进程。程序只能与明确允许的工具交互。

 ```python
 from pydantic import BaseModel
@@ -167,21 +167,22 @@ print(result.final_output)

 注意事项：

-   编程式工具调用仅适用于受支持的 OpenAI Responses 模型。Chat Completions 模型和非 Responses 后端会拒绝 `ProgrammaticToolCallingTool()` 和 `tool_choice="programmatic_tool_calling"`。
-   一个智能体最多只能添加一个 `ProgrammaticToolCallingTool()`。该智能体还必须公开至少一个可通过编程方式调用的工具、一个 `ToolSearchTool()`，或由提示词管理的工具集合。
-   `allowed_callers` 控制工具的调用方式。省略该参数时，仅允许模型直接调用。使用 `["programmatic"]` 可仅允许程序访问，使用 `["direct", "programmatic"]` 则允许两种方式。
-   可选择启用此功能的 SDK 工具类型包括 `FunctionTool`、`CustomTool`、`ShellTool`、`ApplyPatchTool`、`HostedMCPTool` 和 `CodeInterpreterTool`。函数、自定义、shell 和补丁应用工具直接公开 `allowed_callers`。对于托管MCP和 Code Interpreter，请在 `tool_config` 中设置 `allowed_callers`。
-   对于 `@function_tool(allowed_callers=[...])`，Pydantic 模型、TypedDict 或 dataclass 等结构化返回注解会自动转换为严格的对象输出架构，并在值返回给程序之前进行验证。如果函数没有可用的注解，请使用 `output_type=...`；如果你已有严格的对象架构，则可使用较低层级的 `output_json_schema={...}` 作为替代方案。`output_type` 和 `output_json_schema` 互斥。返回普通 `str`、`Any` 和 `None` 时仍不指定类型。
-   由程序拥有的 SDK 工具仍使用常规 Runner 生命周期。工具输入和输出安全防护措施、钩子、超时、并发限制、重试、审批、会话以及 `RunState` 暂停/恢复行为仍然适用，并且 SDK 会保留每个子调用与程序调用方之间的关系。
-   对审批敏感或影响较大的工具通常更适合作为直接调用保留，以便人员在每项操作成为大型程序的一部分之前进行审查。如果由程序拥有的调用因审批而暂停，请通过 `RunState` 处理中断，并照常恢复原始运行。
-   编程式工具调用可以与[托管工具搜索](#hosted-tool-search)结合使用。生成的程序必须先由模型加载延迟工具，然后才能调用它们。
-   `program` 项目及其由程序拥有的子调用会显示为 [`ToolCallItem`][agents.items.ToolCallItem] 条目。对应的 `program_output` 会显示为 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]。有关检查详情，请参阅[结果](results.md#new-items)和[流式传输](streaming.md#run-item-event-names)。
+-   程序化工具调用仅适用于受支持的 OpenAI Responses 模型。Chat Completions 模型和非 Responses 后端会拒绝 `ProgrammaticToolCallingTool()` 和 `tool_choice="programmatic_tool_calling"`。
+-   一个智能体最多添加一个 `ProgrammaticToolCallingTool()`。智能体还必须公开至少一个可由程序调用的工具、一个由命名空间、延迟函数或延迟托管 MCP 服务支持的 `ToolSearchTool()`，或者一个由提示词管理的不透明工具集。没有可搜索工具集的单独 `ToolSearchTool()` 会被拒绝。
+-   `allowed_callers` 控制工具的调用方式。省略它时，仅允许模型直接调用。使用 `["programmatic"]` 可限制为仅由程序访问，使用 `["direct", "programmatic"]` 则可同时允许两种方式。
+-   可选择启用此功能的 SDK 工具类型包括 `FunctionTool`、`CustomTool`、`ShellTool`、`ApplyPatchTool`、`HostedMCPTool` 和 `CodeInterpreterTool`。函数、自定义、Shell 和补丁应用工具直接公开 `allowed_callers`。对于托管 MCP 和 Code Interpreter，请在 `tool_config` 内设置 `allowed_callers`。
+-   对于 `@function_tool(allowed_callers=[...])`，Pydantic 模型、TypedDict 或 dataclass 等结构化返回注解会自动转换为严格的对象输出模式，并在将值返回给程序之前进行验证。如果函数没有可用的注解，请使用 `output_type=...`；如果你已经拥有严格的对象模式，可使用更底层的 `output_json_schema={...}` 备用方式。`output_type` 与 `output_json_schema` 互斥。普通 `str`、`Any` 和 `None` 返回值仍不带类型。对于由模式支持且归程序所有的调用，默认失败格式化程序会被禁用，因为其自由格式文本不符合输出模式。因此，除非你提供返回符合模式的 JSON 的自定义 `failure_error_function`，否则处理程序异常将继续向上传播。
+-   归程序所有的 SDK 工具仍使用正常的 Runner 生命周期。工具输入和输出安全防护措施、钩子、超时、并发限制、审批、会话以及 `RunState` 暂停/恢复行为仍然适用，SDK 也会保留每个子调用与程序调用者之间的关系。
+-   只要存在 `ProgrammaticToolCallingTool()`，模型请求重试就会采用更严格的重放安全边界，即使程序尚未执行也是如此。SDK 会为这些请求禁用提供方管理的重试和 WebSocket 事件前重试。仅当提供方建议明确将重放标记为安全时，Runner 重试策略才会重试；单独使用 `retry_policies.network_error()` 不会覆盖此边界。
+-   涉及审批或影响较大的工具通常更适合作为直接调用，以便人工在每个操作成为大型程序的一部分之前进行审查。如果归程序所有的调用因等待审批而暂停，请通过 `RunState` 处理中断，并照常恢复原始运行。
+-   程序化工具调用可以与[托管工具搜索](#hosted-tool-search)结合使用。模型必须先加载延迟工具，生成的程序才能调用它们。
+-   `program` 条目及其普通的归程序所有的子工具调用会显示为 [`ToolCallItem`][agents.items.ToolCallItem] 条目。对应的 `program_output` 会显示为 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]。托管 MCP 审批请求和工具目录则使用专用的 MCP 条目和流式事件。有关检查详情，请参阅[结果](results.md#new-items)和[流式传输](streaming.md#run-item-event-names)。
 -   有关完整的并发库存规划代码示例，请参阅 `examples/tools/programmatic_tool_calling.py`。
-   官方平台指南：[编程式工具调用](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)。
+-   官方平台指南：[程序化工具调用](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)。

-### 托管容器 shell 与技能
+### 托管容器 Shell 与技能

-`ShellTool` 还支持在OpenAI托管的容器中执行。当你希望模型在托管容器中运行 shell 命令，而不是在本地运行时中运行时，请使用此模式。
+`ShellTool` 还支持在OpenAI托管的容器中执行。当你希望模型在托管容器中而不是本地运行时中执行 Shell 命令时，请使用此模式。

 ```python
 from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -214,52 +215,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 工具使用。
+-   托管 Shell 可通过 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` 模式。
-   在允许列表模式下，`network_policy.domain_secrets` 可以按名称注入限定于域的密钥。
+-   在允许列表模式下，`network_policy.domain_secrets` 可以按名称注入限定于域名的密钥。
 -   有关完整代码示例，请参阅 `examples/tools/container_shell_skill_reference.py` 和 `examples/tools/container_shell_inline_skill.py`。
-   OpenAI 平台指南：[Shell](https://platform.openai.com/docs/guides/tools-shell)和[技能](https://platform.openai.com/docs/guides/tools-skills)。
+-   OpenAI平台指南：[Shell](https://platform.openai.com/docs/guides/tools-shell)和[技能](https://platform.openai.com/docs/guides/tools-skills)。

 ## 本地运行时工具

-本地运行时工具在模型响应本身之外执行。模型仍然决定何时调用它们，但实际工作由你的应用或配置的执行环境完成。
+本地运行时工具在模型响应本身之外执行。模型仍会决定何时调用它们，但实际工作由你的应用或已配置的执行环境完成。

-`ComputerTool` 和 `ApplyPatchTool` 始终需要由你提供本地实现。`ShellTool` 横跨两种模式：如果需要托管执行，请使用上述托管容器配置；如果希望命令在你自己的进程中运行，请使用下述本地运行时配置。
+`ComputerTool` 和 `ApplyPatchTool` 始终需要由你提供本地实现。`ShellTool` 横跨两种模式：如果需要托管执行，请使用上面的托管容器配置；如果希望命令在你自己的进程中运行，请使用下面的本地运行时配置。

 本地运行时工具要求你提供实现：

 -   [`ComputerTool`][agents.tool.ComputerTool]：实现 [`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]，以便在本地应用差异。
-   本地 shell 技能可通过 `ShellTool(environment={"type": "local", "skills": [...]})` 使用。
+-   [`ShellTool`][agents.tool.ShellTool]：同时适用于本地执行和托管容器执行的最新 Shell 工具。
+-   [`LocalShellTool`][agents.tool.LocalShellTool]：旧版本地 Shell 集成。
+-   [`ApplyPatchTool`][agents.tool.ApplyPatchTool]：实现 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]，以在本地应用差异。
+-   可通过 `ShellTool(environment={"type": "local", "skills": [...]})` 使用本地 Shell 技能。

 ### ComputerTool 与 Responses 计算机工具

-`ComputerTool` 仍然是一个本地执行框架：你需要提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 会将该执行框架映射到 OpenAI Responses API 的计算机操作界面。
+`ComputerTool` 仍是本地运行框架：你需要提供 [`Computer`][agents.computer.Computer] 或 [`AsyncComputer`][agents.computer.AsyncComputer] 实现，SDK 会将该运行框架映射到 OpenAI Responses API 的计算机操作界面。

-对于明确的 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 请求，SDK 会发送正式发布版内置工具载荷 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型则继续使用预览版载荷 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI 的[计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)中所述的平台迁移一致：
+对于显式的 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 请求，SDK 会发送正式发布版内置工具载荷 `{"type": "computer"}`。较旧的 `computer-use-preview` 模型仍使用预览版载荷 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`。这与 OpenAI[计算机操作指南](https://developers.openai.com/api/docs/guides/tools-computer-use/)中所述的平台迁移一致：

 -   模型：`computer-use-preview` -> `gpt-5.5`
 -   工具选择器：`computer_use_preview` -> `computer`
-   计算机调用结构：每个 `computer_call` 包含一个 `action` -> `computer_call` 上批量的 `actions[]`
+-   计算机调用形式：每个 `computer_call` 包含一个 `action` -> `computer_call` 上的批量 `actions[]`
 -   截断：预览版路径要求使用 `ModelSettings(truncation="auto")` -> 正式发布版路径不要求

-SDK 会根据实际 Responses 请求中的有效模型选择相应的传输结构。如果你使用提示词模板，并且由于模型由提示词指定而使请求省略 `model`，SDK 会继续使用兼容预览版的计算机载荷；除非你明确保留 `model="gpt-5.5"`，或通过 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制使用正式发布版选择器。
+SDK 会根据实际 Responses 请求中的有效模型选择该传输格式。如果你使用提示词模板，并且由于模型由提示词指定而在请求中省略 `model`，SDK 会继续使用与预览版兼容的计算机载荷，除非你显式保留 `model="gpt-5.5"`，或者使用 `ModelSettings(tool_choice="computer")` 或 `ModelSettings(tool_choice="computer_use")` 强制选择正式发布版选择器。

-存在 [`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] 工厂支持时，这一区别很重要。正式发布版 `computer` 载荷在序列化时不需要 `environment` 或尺寸，因此工厂尚未解析也没有问题。兼容预览版的序列化仍然需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 可以发送 `environment`、`display_width` 和 `display_height`。
+当 `ComputerTool` 由 [`ComputerProvider`][agents.tool.ComputerProvider] 工厂支持时，这一区别非常重要。正式发布版 `computer` 载荷在序列化时不需要 `environment` 或尺寸，因此工厂尚未解析也没有问题。与预览版兼容的序列化仍需要已解析的 `Computer` 或 `AsyncComputer` 实例，以便 SDK 发送 `environment`、`display_width` 和 `display_height`。

-在运行时，两条路径仍然使用同一个本地执行框架。预览版响应会发出包含单个 `action` 的 `computer_call` 项目；`gpt-5.5` 可以发出批量的 `actions[]`，SDK 会按顺序执行这些操作，然后生成一个 `computer_call_output` 截图项目。有关基于 Playwright 的可运行执行框架，请参阅 `examples/tools/computer_use.py`。
+在运行时，两条路径仍使用相同的本地运行框架。预览版响应会发出包含单个 `action` 的 `computer_call` 条目；`gpt-5.5` 可以发出批量 `actions[]`，SDK 会依次执行这些操作，然后生成 `computer_call_output` 屏幕截图条目。有关基于 Playwright 的可运行框架，请参阅 `examples/tools/computer_use.py`。

 ```python
 from agents import Agent, ApplyPatchTool, ShellTool
@@ -305,14 +306,16 @@ agent = Agent(

 你可以将任意 Python 函数用作工具。Agents SDK 会自动设置该工具：

-   工具名称将是 Python 函数的名称（也可以自行提供名称）
-   工具描述将取自函数的文档字符串（也可以自行提供描述）
-   函数输入的架构会根据函数参数自动创建
+-   工具名称将使用 Python 函数的名称（你也可以提供名称）
+-   工具描述将取自函数的文档字符串（你也可以提供描述）
+-   函数输入的模式会根据函数参数自动创建
 -   除非禁用，否则每个输入的描述都取自函数的文档字符串

-我们使用 Python 的 `inspect` 模块提取函数签名，使用 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析文档字符串，并使用 `pydantic` 创建架构。
+由 `@tool` 创建的工具通过只读 `__wrapped__` 属性公开原始 Python 可调用对象。这对检查和测试很有用，但直接调用它会绕过工具运行时管线，包括模式验证、上下文注入、安全防护措施、超时、失败处理和追踪。手动构建的 `FunctionTool` 实例不公开 `__wrapped__`。

-使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏工具调用，直到 `ToolSearchTool()` 将其加载。你还可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关工具调用进行分组。有关完整设置和限制，请参阅[托管工具搜索](#hosted-tool-search)。
+我们使用 Python 的 `inspect` 模块提取函数签名，并结合 [`griffe`](https://mkdocstrings.github.io/griffe/) 解析文档字符串，再使用 `pydantic` 创建模式。
+
+使用 OpenAI Responses 模型时，`@function_tool(defer_loading=True)` 会隐藏工具调用，直到 `ToolSearchTool()` 加载它。你也可以使用 [`tool_namespace()`][agents.tool.tool_namespace] 对相关的工具调用进行分组。有关完整设置和限制，请参阅[托管工具搜索](#hosted-tool-search)。

 ```python
 import json
@@ -365,10 +368,10 @@ for tool in agent.tools:

 ```

-1.  你可以使用任意 Python 类型作为函数参数，并且函数可以是同步或异步的。
-2.  如果存在文档字符串，则会使用它来获取描述和参数描述
+1.  你可以使用任意 Python 类型作为函数参数，函数可以是同步或异步函数。
+2.  如果存在文档字符串，则会使用它来获取描述和参数描述。
 3.  函数可以选择接收 `context`（必须是第一个参数）。你还可以设置覆盖项，例如工具名称、描述、要使用的文档字符串样式等。
-4.  你可以将经过装饰的函数传递给工具列表。
+4.  你可以将经过装饰的函数传入工具列表。

 ??? note "展开以查看输出"

@@ -442,11 +445,11 @@ for tool in agent.tools:

 ### 从工具调用返回图像或文件

-除了返回文本输出之外，你还可以返回一个或多个图像或文件作为工具调用的输出。为此，可以返回以下任意内容：
+除了返回文本输出外，你还可以将一个或多个图像或文件作为工具调用的输出返回。为此，你可以返回以下任意内容：

-   图像：[`ToolOutputImage`][agents.tool.ToolOutputImage]（或其 TypedDict 版本 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]）
-   文件：[`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（或其 TypedDict 版本 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]）
-   文本：字符串、可转换为字符串的对象，或 [`ToolOutputText`][agents.tool.ToolOutputText]（或其 TypedDict 版本 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
+-   图像：[`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]）

 ### 自定义工具调用

@@ -454,8 +457,8 @@ for tool in agent.tools:

 -   `name`
 -   `description`
-   `params_json_schema`，即参数的 JSON 架构
-   `on_invoke_tool`，它是一个异步函数，接收 [`ToolContext`][agents.tool_context.ToolContext] 和 JSON 字符串形式的参数，并返回工具输出（例如文本、结构化工具输出对象或输出列表）。
+-   `params_json_schema`，即参数的 JSON 模式
+-   `on_invoke_tool`，即一个异步函数，它接收 [`ToolContext`][agents.tool_context.ToolContext] 和以 JSON 字符串形式提供的参数，并返回工具输出（例如文本、结构化工具输出对象或输出列表）。

 ```python
 from typing import Any
@@ -490,16 +493,16 @@ tool = FunctionTool(

 ### 参数与文档字符串的自动解析

-如前所述，我们会自动解析函数签名以提取工具架构，并解析文档字符串以提取工具和各个参数的描述。相关注意事项如下：
+如前所述，我们会自动解析函数签名以提取工具模式，并解析文档字符串以提取工具及各个参数的描述。相关注意事项如下：

-1. 签名解析通过 `inspect` 模块完成。我们使用类型注解了解参数类型，并动态构建 Pydantic 模型来表示整体架构。它支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。
-2. 我们使用 `griffe` 解析文档字符串。支持的文档字符串格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测文档字符串格式，但这只是尽力而为；你可以在调用 `function_tool` 时明确设置格式。也可以将 `use_docstring_info` 设置为 `False` 来禁用文档字符串解析。对于 Google 风格的文档字符串，解析器还接受紧跟在摘要文本之后且中间没有空行的 `Args:`、`Arguments:`、`Params:` 或 `Parameters:` 章节。
+1. 签名解析通过 `inspect` 模块完成。我们使用类型注解理解参数类型，并动态构建 Pydantic 模型来表示整体模式。它支持大多数类型，包括 Python 基本类型、Pydantic 模型、TypedDict 等。
+2. 我们使用 `griffe` 解析文档字符串。支持的文档字符串格式包括 `google`、`sphinx` 和 `numpy`。我们会尝试自动检测文档字符串格式，但这属于尽力而为；你也可以在调用 `function_tool` 时显式设置格式。还可以将 `use_docstring_info` 设置为 `False`，以禁用文档字符串解析。对于 Google 风格的文档字符串，解析器还接受紧接在摘要文本之后且中间没有空行的 `Args:`、`Arguments:`、`Params:` 或 `Parameters:` 部分。

-架构提取代码位于 [`agents.function_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 架构和验证均包含这些约束。
+你可以使用 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
@@ -570,15 +573,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 RunContextWrapper
@@ -602,11 +605,11 @@ def get_user_profile(user_id: str) -> str:

 ```

-如果手动创建 `FunctionTool` 对象，则必须在 `on_invoke_tool` 函数内部处理错误。
+如果手动创建 `FunctionTool` 对象，则必须在 `on_invoke_tool` 函数中处理错误。

 ## Agents as tools

-在某些工作流中，你可能希望由一个中心智能体编排专用智能体网络，而不是转移控制权。你可以通过将智能体建模为工具来实现这一点。
+在某些工作流中，你可能希望由一个中央智能体编排由多个专用智能体组成的网络，而不是转移控制权。你可以通过将智能体建模为工具来实现这一点。

 ```python
 import asyncio
@@ -652,9 +655,9 @@ if __name__ == "__main__":

 ### 工具智能体自定义

-`agent.as_tool` 函数是一种便捷方法，可以轻松地将智能体转换为工具。它支持 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval` 等常见运行时选项。它还通过 `parameters`、`input_builder` 和 `include_input_schema` 支持结构化输入。
+`agent.as_tool` 函数是一种便捷方法，可轻松将智能体转换为工具。它支持常见运行时选项，例如 `max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session` 和 `needs_approval`。它还通过 `parameters`、`input_builder` 和 `include_input_schema` 支持结构化输入。

-状态选项用于配置由工具调用启动的嵌套智能体运行；父运行的对话状态不会自动继承。若要在父运行和嵌套运行之间共享由客户端管理的历史记录，请明确向两者传入相同的 `session`。与 `Runner.run` 一样，应为嵌套运行选择一种状态策略：使用由客户端管理的 `session`，或通过 `previous_response_id` 或 `conversation_id` 在服务端管理延续状态。
+状态选项用于配置由工具调用启动的嵌套智能体运行；父运行的对话状态不会自动继承。若要在父运行和嵌套运行之间共享由客户端管理的历史记录，请显式向两者传入相同的 `session`。与 `Runner.run` 一样，请为嵌套运行选择一种状态策略：使用由客户端管理的 `session`，或者通过 `previous_response_id` 或 `conversation_id` 在服务端延续。

 ```python
 from agents.decorators import tool
@@ -678,12 +681,12 @@ async def run_my_agent() -> str:

 ### 工具智能体的结构化输入

-默认情况下，`Agent.as_tool()` 需要单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）公开结构化架构。
+默认情况下，`Agent.as_tool()` 需要单个字符串输入（`{"input": "..."}`），但你可以通过传入 `parameters`（Pydantic 模型或 dataclass 类型）公开结构化模式。

 其他选项：

 - `include_input_schema=True` 会在生成的嵌套输入中包含完整的 JSON Schema。
- `input_builder=...` 让你可以完全自定义如何将结构化工具参数转换为嵌套智能体输入。
+- `input_builder=...` 允许你完全自定义如何将结构化工具参数转换为嵌套智能体输入。
 - `RunContextWrapper.tool_input` 包含嵌套运行上下文中已解析的结构化载荷。

 ```python
@@ -708,17 +711,17 @@ translator_tool = translator_agent.as_tool(

 ### 工具智能体的审批门控

-`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理项目将显示在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复运行。有关完整的暂停/恢复模式，请参阅[人工介入指南](human_in_the_loop.md)。
+`Agent.as_tool(..., needs_approval=...)` 使用与 `function_tool` 相同的审批流程。如果需要审批，运行会暂停，待处理条目会出现在 `result.interruptions` 中；然后使用 `result.to_state()`，并在调用 `state.approve(...)` 或 `state.reject(...)` 后恢复运行。有关完整的暂停/恢复模式，请参阅[人工介入指南](human_in_the_loop.md)。

 ### 自定义输出提取

-在某些情况下，你可能希望先修改工具智能体的输出，再将其返回给中心智能体。以下情况可能会需要这样做：
+在某些情况下，你可能希望先修改工具智能体的输出，再将其返回给中央智能体。以下情况可能会用到此功能：

-   从子智能体的聊天历史中提取特定信息（例如 JSON 载荷）。
+-   从子智能体的聊天历史记录中提取特定信息（例如 JSON 载荷）。
 -   转换或重新格式化智能体的最终答案（例如将 Markdown 转换为纯文本或 CSV）。
-   验证输出，或在智能体响应缺失或格式错误时提供回退值。
+-   验证输出，或者在智能体响应缺失或格式错误时提供回退值。

-你可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现：
+可以通过向 `as_tool` 方法提供 `custom_output_extractor` 参数来实现：

 ```python
 async def extract_json_payload(run_result: RunResult) -> str:
@@ -737,11 +740,11 @@ json_tool = data_agent.as_tool(
 )
 ```

-在自定义提取器内部，嵌套的 [`RunResult`][agents.result.RunResult] 还会公开 [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]。当你需要在对嵌套结果进行后处理时获取外层工具名称、调用 ID 或原始参数，这会很有用。请参阅[结果指南](results.md#agent-as-tool-metadata)。
+在自定义提取器内部，嵌套的 [`RunResult`][agents.result.RunResult] 还会公开 [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]。当你需要在后处理嵌套结果时获取外层工具名称、调用 ID 或原始参数，这一属性非常有用。请参阅[结果指南](results.md#agent-as-tool-metadata)。

 ### 嵌套智能体运行的流式传输

-向 `as_tool` 传入 `on_stream` 回调，以侦听嵌套智能体发出的流式传输事件，同时仍在流完成后返回其最终输出。
+向 `as_tool` 传入 `on_stream` 回调，以监听嵌套智能体发出的流式事件，同时仍会在流完成后返回其最终输出。

 ```python
 from agents import AgentToolStreamEvent
@@ -762,12 +765,12 @@ billing_agent_tool = billing_agent.as_tool(
 预期行为：

 - 事件类型与 `StreamEvent["type"]` 一致：`raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。
- 提供 `on_stream` 会自动以流式传输模式运行嵌套智能体，并在返回最终输出前耗尽该流。
+- 提供 `on_stream` 后，嵌套智能体会自动以流式传输模式运行，并在返回最终输出前读取完流。
 - 处理程序可以是同步或异步的；每个事件都会按到达顺序传递。
- 通过模型工具调用来调用工具时，会提供 `tool_call`；直接调用时，其值可能为 `None`。
- 有关完整的可运行示例，请参阅 `examples/agent_patterns/agents_as_tools_streaming.py`。
+- 通过模型工具调用来调用工具时，会存在 `tool_call`；直接调用时，其值可能为 `None`。
+- 有关完整的可运行代码示例，请参阅 `examples/agent_patterns/agents_as_tools_streaming.py`。

-### 条件式工具启用
+### 工具的条件启用

 你可以使用 `is_enabled` 参数，在运行时有条件地启用或禁用智能体工具。这样便可根据上下文、用户偏好或运行时条件，动态筛选可供 LLM 使用的工具。

@@ -830,18 +833,18 @@ asyncio.run(main())
 -   **可调用函数**：接收 `(context, agent)` 并返回布尔值的函数
 -   **异步函数**：用于复杂条件逻辑的异步函数

-禁用的工具在运行时对 LLM 完全隐藏，因此适用于：
+禁用的工具在运行时对 LLM 完全不可见，因此此功能适用于：

-   根据用户权限进行功能门控
-   特定环境下的工具可用性（开发环境与生产环境）
+-   根据用户权限控制功能
+-   特定于环境的工具可用性（开发环境与生产环境）
 -   对不同工具配置进行 A/B 测试
 -   根据运行时状态动态筛选工具

-## 实验性 Codex 工具
+## 实验性功能：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
@@ -872,31 +875,31 @@ 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`。
-   工具输入/输出：工具调用必须至少包含一个 `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`。
+-   工具输入/输出：工具调用必须至少包含一个 `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_<suffix>"` 时，则为 `codex_thread_id_<suffix>`。可以使用 `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_<suffix>"`，则为 `codex_thread_id_<suffix>`。可使用 `run_context_thread_id_key` 覆盖该键。
- 
 运行时配置：

-   身份验证：设置 `CODEX_API_KEY`（首选）或 `OPENAI_API_KEY`，或者传入 `codex_options={"api_key": "..."}`。
+-   身份验证：设置 `CODEX_API_KEY`（推荐）或 `OPENAI_API_KEY`，或者传入 `codex_options={"api_key": "..."}`。
 -   运行时：`codex_options.base_url` 会覆盖 CLI 基础 URL。
 -   二进制文件解析：设置 `codex_options.codex_path_override`（或 `CODEX_PATH`）以固定 CLI 路径。否则，SDK 会先从 `PATH` 中解析 `codex`，然后回退到捆绑的供应商二进制文件。
-   环境：`codex_options.env` 完全控制子进程环境。提供该选项时，子进程不会继承 `os.environ`。
+-   环境：`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`；用量会添加到 `RunContextWrapper.usage`。
+-   流式传输：`on_stream` 接收线程/轮次生命周期事件和条目事件（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list` 和 `error` 条目更新）。
+-   输出：结果包括 `response`、`usage` 和 `thread_id`；使用量会添加到 `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`。
+-   有关完整的可运行代码示例，请参阅 `examples/tools/codex.py` 和 `examples/tools/codex_same_thread.py`。